I have been using synthesis project management with Claude Code for months. It is the system that lets me keep more than sixty projects moving without trusting any single chat transcript to remember what matters.
This week I ported that system to OpenAI Codex.
The interesting part was not the mechanics of copying files into another tool’s directory. The interesting part was what had to stay outside the tool.
Claude Code has CLAUDE.md. Codex has AGENTS.md. Claude Code has hooks. Codex has hooks. Claude Code has skills. Codex has skills. Those surfaces matter because they shape behavior at the start of a session and at the edges of a workflow.
But none of them should be the project’s memory.
The project memory belongs in the project.
Updated: July 6, 2026: Synthesis project management now includes an agent attribution convention: session logs record which agent did what, at what capability, with what verification. See the update at the end of this article.
The real portability problem
Most AI tooling discussions focus on which model is better. That is the wrong layer for this problem.
If I am using Claude Code on Monday, Codex on Tuesday, and perhaps another capable coding agent later, the critical question is not whether each tool has a memory feature. The question is whether the work itself has a durable state that any capable agent can read.
Tool-native memory is useful. Claude Code has its own memory mechanisms. ChatGPT has persistent memory. Codex has its own configuration, skills, and session context. These help within a tool.
They do not solve cross-tool continuity.
A project needs its own working memory, semantic memory, and session history. In synthesis project management, that means:
project/
├── CONTEXT.md # Current state and active tasks
├── REFERENCE.md # Stable facts, updated in place
└── sessions/ # Chronological session historyThis is the same tiered context architecture I wrote about earlier. What changed this week is that I made the surrounding tool interfaces work across both Claude Code and Codex.
The center did not move.
What Codex needed
OpenAI’s Codex documentation says Codex reads AGENTS.md files before doing work, layering global instructions with project-specific guidance. That is the Codex equivalent of the CLAUDE.md convention I had already built around.
So the first step was simple: create and synchronize AGENTS.md files where Codex needed them, and configure Codex to fall back to CLAUDE.md while the ecosystem migrates.
That fallback matters. I do not want every existing synthesis project to require a flag day. A good portability layer should let old projects continue working while new projects become explicitly multi-agent.
The second step was hooks. Codex supports hook events such as SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, and Stop. That allowed me to port the guardrails that matter most in my workflow:
- detect lazy shortcut language before it hardens into recommendations
- prevent direct edits to installed skill copies
- run repo sync checks so local work does not get stranded on one machine
The third step was skills. My public synthesis skills now install into four local targets:
~/.claude/skills~/.codex/skills~/.agents/skills~/.cursor/skills
The private personal skills and shared team skills follow the same principle. Source repos are authoritative. Installed copies are deployment artifacts.
That distinction prevents a quiet failure mode: editing the copy a tool happens to load, then losing the change when the installer runs again. The rule is now explicit: edit source first, push every configured remote, then reinstall.
The durable memory layer
During the port, I used synthesis project management to manage the port itself.
That sounds recursive, but it is the point.
The project lived in ai-knowledge-rajiv/projects/synthesis-codex-portability/. It had a CONTEXT.md for active state, a REFERENCE.md for stable facts, a session archive, and artifacts for the customization audit, hook setup, handoff checklist, and article plan.
When Codex hit a usage limit, the work did not disappear into a chat summary. The project files already knew what had been completed, which repos had been pushed, and what remained. When the session resumed, Codex picked up from the project files.
That is the core claim: synthesis project management is not documentation about the work. It is part of the work.
It gives an AI agent a place to put state that survives:
- context compaction
- tool restarts
- model changes
- moving from Claude Code to Codex
- moving from Codex back to Claude Code
- switching machines
The system does not require the agent to remember. It requires the agent to write things down in the right place.
Why this matches what OpenAI found
OpenAI’s Sora Android Codex case study describes a four-engineer team building the Android app in 28 days with Codex. The detail that mattered most to me was not the 28 days. It was the working model.
They treated Codex like a capable senior engineer who needed onboarding. They used agent instruction files to document how the team worked. They planned before implementation. They saved plans to files for long-running tasks. They ran multiple sessions and then managed the review and integration work.
That is synthesis engineering under another name.
My earlier response to that case study focused on synthesis coding: foundation-first development, persistent context files, planning before coding, and the conductor model.
This port extends the same lesson to project management.
If AI agents are going to operate more like a distributed team, then the team needs a shared project memory. Not a transcript. Not a private model memory. A project memory.
What changed in the synthesis system
The practical changes were small but important:
Instruction parity. Claude-facing CLAUDE.md files and Codex-facing AGENTS.md files now express the same durable-memory rule. Codex can also read CLAUDE.md as a fallback while repos are migrated.
Skill parity. Public, private, and shared skills install into Codex locations as well as Claude Code locations. The cross-agent .agents convention gives other tools a neutral place to look.
Hook parity. Codex now has equivalents for the most important guardrails: shortcut detection, installed-skill edit protection, and repo sync checks.
Configuration parity. Skills that used .claude/*.yaml for agent-neutral configuration now prefer .agents/*.yaml with .claude/*.yaml as a compatibility fallback.
Project-memory discipline. The synthesis project files are now explicitly documented as the durable handoff layer between tools.
The result is not that Codex imitates Claude Code. That would be the wrong goal. Each tool has its own surfaces and strengths.
The result is that the synthesis system has a stable center while tool-specific adapters sit at the edges.
The useful distinction
Here is the mental model I ended up with:
| Layer | Purpose | Examples |
|---|---|---|
| Project memory | What is true about this project | CONTEXT.md, REFERENCE.md, sessions/ |
| Procedural memory | How the agent should work | CLAUDE.md, AGENTS.md, skills |
| Guardrails | What should be caught at runtime | hooks, repo guard, edit guards |
| Tool configuration | How a specific tool is wired | Codex config, Claude settings |
Most confusion comes from mixing those layers.
If project memory lives in CLAUDE.md, Codex starts at a disadvantage. If project memory lives in AGENTS.md, Claude Code starts at a disadvantage. If project memory lives only in the chat transcript, both tools are fragile.
But if project memory lives in CONTEXT.md, REFERENCE.md, and sessions/, then CLAUDE.md and AGENTS.md can do what they are good at: telling each tool how to work.
That separation is what makes the system portable.
What this means in practice
A synthesis project can now be paused in Codex and resumed in Claude Code. Or paused in Claude Code and resumed in Codex.
The receiving agent should not need a long recap from the human. It should:
- read
projects/index.yaml - load the matching project’s
CONTEXT.md - consult
REFERENCE.mdif needed - search session history for older decisions
- continue from the recorded next task
- update the same project files before handing off again
That is the workflow I want for myself, and it is the workflow I want the synthesis system to teach.
The human remains responsible. The agent still needs direction. But the friction of changing tools drops because the state is not trapped in any one tool.
What this does not solve
This does not make all AI coding tools interchangeable.
Codex and Claude Code have different interfaces, different limits, different permission models, and different strengths. Some workflows will feel better in one than the other. Some integrations will require tool-specific work.
It also does not remove the need for verification. OpenAI’s own Codex guidance emphasizes review, planning, and context. Synthesis engineering says the same thing: the human directs, the AI executes, the human verifies, the AI iterates.
Portability is not a substitute for judgment.
What portability does is let judgment compound across tools.
The next layer
The immediate work is done: the skills install, the instructions align, the hooks exist, and the project-management system records the state.
The next layer is practice. Use Codex on real synthesis projects. Move work between Codex and Claude Code when it makes sense. Keep tightening the handoff protocol. Write down what breaks.
That is how synthesis engineering has developed from the beginning: not by naming a theory first, but by building workflows that survive real use.
The important thing is that the center now holds.
Claude Code can be one excellent interface into the synthesis system. Codex can be another. Future agents can join as they become capable.
The project memory remains the same.
Update (July 6, 2026): which agent did what
Two months of cross-agent practice surfaced a gap worth closing.
Yesterday, Claude Code ran one session on a project and Codex ran the next, a few hours apart. Both updated the same project files. Both committed. The git history recorded the same author for both, because different agent tools commonly commit under the same human identity. Git alone could not answer a question I will care about later: which agent did this work, at what capability, verified how?
Trailers like Co-Authored-By do not settle it. They are authored claims, not verified facts. The same day, I found commits whose trailer named one model while the session was actually running another — the trailer had been inherited from an old session template.
So synthesis project management now records it. When more than one agent contributes materially to a project, the session log entry ends with one compact line per contributing agent:
*Attribution — agent: Codex CLI · model: unknown · effort: unknown · scope: single-stack sweep only (session lacked the Gmail connector) · verified: plan re-run to zero · ref: d4e5f6a*Six fields: the agent or tool, the model string, the effort setting, what this agent actually did, what verification actually ran, and a durable reference such as a commit hash.
Two rules give the line its value.
Unknown means unknown. The model and effort fields are recorded only when the session or the human explicitly provides them. Otherwise they stay the literal word unknown. Never inferred from memory, from prior sessions, or from git trailers. A wrong provenance claim is worse than an honest gap.
Attribution is provenance, not telemetry. The line appears when it helps future work: cross-agent handoffs, sessions where a tool’s capability gap shaped the scope, multi-model or subagent contributions, work whose verification a future reader needs to trust or re-check. Routine sessions in a single-agent project do not need it. Nothing logs every edit.
Placement follows the tiered architecture this article describes. Attribution lines live in the session archive, which is episodic and append-only. CONTEXT.md gets at most a short (via Codex) tag when agent identity changes how to read the state. REFERENCE.md carries only stable agent facts, such as a standing connector gap that scopes what a tool’s sessions can do.
The convention shipped in the public skills: synthesis-context-lifecycle v1.3.0 carries the full definition, and synthesis-project-management v1.1.0 adds it to the session-end and cross-agent handoff protocols. A departing agent now attributes its own work before the handoff, so the receiving agent knows who did what, with what verification.
That closes a loop this article opened. Project memory that moves between agents needs to remember more than what happened. It needs to remember who did it, and how much to trust it.