Global behavior
AGENTS.md holds durable rules that should apply across projects: verify before stating, fix root causes, respect approval boundaries, and communicate like a human.
Back to homev2 · Codex + Claude · MIT
Agent Brain v2
The public version of how I work with coding agents today. One shared operating brain, four focused workflows, and a thin adapter for each runtime — packaged so you can understand it before you install it.
bash <(curl -fsSL https://dormizrahi.com/install-v2)macOS or Linux · Codex, Claude Code, or both · Existing matching files are backed up first.
What the fuck is going on?
Version 1 treated Claude's global CLAUDE.md as the whole brain. It also pushed every project into one fixed project-brain folder and stored each workflow as a large slash command. That worked, but it mixed permanent behavior, project facts, current status, and procedures into one system.
Version 2 separates those jobs. The global brain says how the agent should work with you. Each project says what is special about that project. Code and configuration own facts the agent can inspect. Sprint or tracker files own current work. Skills hold procedures that should load only when needed.
The result is smaller where it should be small, deeper where it needs depth, and much harder to make stale. Codex and Claude use the same behavioral source instead of slowly drifting into two different collaborators.
One brain, two runtimes
AGENTS.md is the canonical source. Codex reads it directly. Claude gets a tiny CLAUDE.md that imports it and adds only Claude-specific wiring.
Source of truth
~/.codex/AGENTS.mdCollaboration rules, verification discipline, approval boundaries, communication style, and information ownership.
Claude adapter
~/.claude/CLAUDE.mdImports the canonical brain and describes only Claude's skill and style-hook wiring.
On-demand workflows
~/.agents/skills/ + ~/.claude/skills/The same four procedures are exposed to both agents without bloating every conversation.
Where every kind of truth lives
Project behavior
A project AGENTS.md contains only unusual local rules and pointers. A project CLAUDE.md imports it instead of duplicating it.
Operational facts
Code, configuration, migrations, logs, and live inspection remain authoritative. The brain tells the agent to look; it does not cache facts that will rot.
Current work
The project's existing sprint, session, issue tracker, or handoff system owns status. V2 does not force a new folder or vocabulary onto the project.
Reusable procedure
Skills hold conditional workflows. They load when their trigger matches instead of living in the global context on every turn.
Four workflows, no command theatre
These replace the three giant v1 commands. Claude exposes them as slash commands; Codex can invoke them naturally or through a skill mention.
init-projectInitializes or audits lean project instructions. It verifies the repository first and does not create a brain folder unless the project already owns one.
sprintTurns an outcome into bounded, ordered work using the planning format the project already has.
handoffCaptures verified progress, failures, changed state, and the exact next action in the project's existing session system.
orient-statusAnswers “what are we doing?” from current evidence instead of paraphrasing stale conversation memory.
What changes in the agent
Evidence before confidence
Claims about files, runtime behavior, tests, and external facts must come from something inspected or run. Unknowns stay labeled unknown.
Outcome before implementation
The agent establishes what the user is trying to achieve before choosing a technical mechanism.
Autonomy with real boundaries
Safe reads, diagnostics, and approved local work continue without ceremony. Pushes, deployments, destructive deletion, purchases, and messages to others still wait for explicit approval.
Plain communication
The style layer leads with the answer and removes filler without reducing English to cryptic fragments.
Exactly what gets installed
| Path | Owner |
|---|---|
| ~/.codex/AGENTS.md | Canonical global brain |
| ~/.claude/CLAUDE.md | Thin Claude adapter |
| ~/.agents/skills/<skill>/ | Shared Codex skill copies |
| ~/.claude/skills/<skill>/ | Claude skill copies |
| ~/.claude/rules/conversation-style.md | Full Claude response-style rule |
| ~/.claude/hooks/conversation-style-*.js | Session and per-prompt style reinforcement |
| ~/.claude/settings.json | Two hook entries merged; other settings preserved |
| ~/.agents/backups/brain-v2-install-*/ | Pre-install copies of replaced files |
What it deliberately does not do
- ✓It does not copy Dor's client instructions, project lists, audit archives, credentials, or personal work history.
- ✓It does not enable bypass-permissions or change any existing permission mode.
- ✓It does not install notification sounds, send messages, connect accounts, push code, or deploy anything.
- ✓It does not delete v1. Both packages and routes can exist side by side while people compare them.
v1 → v2, in plain English
Claude owns the brainCodex and Claude share one brain
Large global CLAUDE.mdCanonical AGENTS.md + tiny adapter
Mandatory project-brain structureUse the project's existing structure
Three giant slash commandsFour focused, triggerable skills
Telegraph EnglishConcise, natural language
Workflow and facts mixed togetherOne owner for each kind of information
Install it only after you understand it
The installer asks three personalization questions, prints every destination, backs up matching files, and then writes the package. Read the source or run it locally first if you want to inspect every line.
bash <(curl -fsSL https://dormizrahi.com/install-v2)