I made project memory portable between Claude Code and Codex

When Codex hit a usage limit during my April port of synthesis project management, the project files already recorded what had been completed, which repositories had been pushed, and what remained. When the session resumed, Codex picked up from those files.

I had been using the same approach with Claude Code across more than sixty projects. I wanted to carry the work between assistants without reconstructing every decision from conversation history. The project memory belongs in the project; each tool needs its own instructions, skills and checks for working with it.

The record the next assistant needs

I use synthesis project management for a file-based working method: the project keeps its current state, durable facts and session history, and the assistant updates them as part of the work. The core layout is:

project/
├── CONTEXT.md       # Current state, active tasks, next action
├── REFERENCE.md     # Decisions, reasons, stable facts
├── sessions/        # Chronological work and verification history
└── resources/
    └── artifacts/   # Plans, test results, audits and other evidence

CONTEXT.md lets a receiving assistant find the next task. REFERENCE.md explains the decisions that constrain it. Session history preserves how the work reached this state, including checks that failed or were never run. The artifacts keep substantial evidence available without putting every log in the active context.

These files need a loading policy. In my setup, startup instructions direct the assistant to the project index and then to the matching context file. A reference file or old session is read when the task needs it. Naming a file CONTEXT.md does not by itself make every agent load it. The tiered context architecture explains the maintenance routine in more detail.

The record also needs reconciliation. A note saying that a repository was pushed is an account of an earlier check. The receiving session can inspect the current branch, working tree and remote state before depending on it. Another contributor may have changed the code since the note was written.

I used this structure to manage the port itself, with artifacts for the customization audit, hook setup and handoff checklist. Project management became part of the work. The receiving agent's job is to read the record, continue the task, and write back what it did. Decisions and results then remain available across compaction, tool restarts, model changes and moves between machines, provided the receiving environment has the project files.

What I changed in April

The first part of the port was instruction discovery. I synchronized Codex-facing AGENTS.md instructions with the durable-memory rules in my Claude-facing CLAUDE.md files. I also configured CLAUDE.md as a Codex fallback filename. That was an explicit setting, allowing existing instructions to be found while the project instruction files were being aligned.

The second part was the hook setup. Hooks run code at selected points in an agent's workflow. In April, I configured an installed-skill edit check before selected editing-tool calls, and shortcut-language and repository checks at Stop. The edit check was intended to catch changes made to deployed skill copies; the repository check addressed local work left unsynchronized. The shortcut-language check was advisory.

The April setup checks covered configuration parsing, matching source and installed files, script syntax, and sample hook payloads. To validate your own setup, start a fresh session, exercise the editing and Stop paths you intend to rely on, and inspect the hook results.

The third part was skill installation. The April 26 installer source targeted:

  • ~/.claude/skills
  • ~/.codex/skills
  • ~/.agents/skills
  • ~/.cursor/skills, when the Cursor directory existed

That list describes the installer at that time. For a current installation, use the host's current discovery and plugin rules. Check the available skills in the receiving tool, invoke the intended one on a representative task, and compare its work with the skill's instructions.

Source repositories remained authoritative. Installed copies were deployment artifacts. Editing the copy a tool happened to load could lose the change the next time the installer ran, so my update procedure was to change the source, push its configured remotes, and refresh the installed copies. The private and shared skill collections followed the same source-first principle.

I also changed the skills' configuration instructions to prefer .agents files while retaining the previous .claude paths as fallbacks. That change told the assistant where to read agent-neutral settings.

What the receiving tool loads today

Update — October 1, 2026: The client setup guidance below reflects current documentation.

Codex instruction discovery combines global guidance with project guidance along the path from the repository root to the working directory. In each directory, it selects AGENTS.override.md, then AGENTS.md, then a configured fallback name. It uses the first applicable file at that level, rather than automatically combining every filename. A CLAUDE.md fallback therefore needs configuration, and the working directory affects which project instructions apply.

Claude Code can also load AGENTS.md directly, with conditions introduced in version 2.1.277. Its default depends on whether Claude instruction files are present in the working directory or its ancestry. Settings can select both formats, and version, plugin and environment exceptions affect discovery. If a project has both filenames, inspect the active mode instead of assuming that one file is invisible to one tool. Importing shared guidance is another documented option.

For local skills, Codex documents .agents/skills locations, while Claude Code documents .claude/skills locations, alongside their other distribution mechanisms. A shared skill format helps carry a procedure across tools. Its discovery path, invocation controls and available dependencies still need checking in the receiving session.

Current Codex hook documentation describes events including SessionStart, PreToolUse and Stop, trust requirements for non-managed hook contents, and limits on tool coverage. Local shell tools match Bash; an edit-tool matcher alone does not cover that route. Hosted web search and some specialized paths do not follow the same local tool-hook path, and write_stdin does not create a fresh PreToolUse event. Test each event and tool path you intend to rely on.

LayerWhat to inspectWhat the inspection can establish
Project recordCurrent state, decisions, history and evidenceWhat was recorded and what still needs reconciliation
Instructions and skillsDiscovery path, active file, invocation and dependenciesWhich procedure is available; selection needs its own evidence
Runtime checksTrusted hook content, matching event, retained execution resultWhether the tested check ran on the tested path
Tool accessFiles, services, credentials and permissions needed for the taskWhether the next action is available and authorized in this session

A request to the assistant to summarize its instructions can help diagnose loading, but it is still the assistant's account. Use exposed configuration, file reads or event records where the tool provides them. If a tool does not expose selection or activation evidence, keep that part unknown.

The project record is the stable center; tool-specific adapters handle the changing interfaces around it. Separating project state, working procedures, runtime checks and tool configuration lets me improve one layer without rewriting the project's history every time I change tools.

A handoff with something left to verify

Consider an illustrative report change: sort rows by score, highest first, and use the row ID as the tie-break. The tie-break gives equal-score rows a defined order even when the input order changes.

rows = [
    {"id": 4, "score": -1},
    {"id": 2, "score": 10},
    {"id": 1, "score": 10},
    {"id": 3, "score": 7},
]
ordered = sorted(rows, key=lambda row: (-row["score"], row["id"]))
assert [row["id"] for row in ordered] == [1, 2, 3, 4]

An offline check tested all 24 permutations of those four rows, plus an empty input. It checked the expected order and that the input was not mutated. Application and browser checks remain the receiving session's next task in this example.

Download the handoff example to run the sorting checks and packet checks with Python. The archive includes the source, retained result, handoff record and a README explaining the expected output and limits.

A departing record for this example can carry:

Task: Order report rows by descending score, then ascending ID.
Decision: Use ID to define the order of tied scores.
Changed: report.py, with its exact file digest.
Verified: the retained offline sorting result for that source.
Not run: application and browser checks.
Next: inspect the real report screen and run its application checks.
Scope: local synthetic fixture only.
Evidence: report-sort-result.json, with its exact file digest.

The filenames belong to the retained example package. The source digest identifies the implementation checked; the result digest detects a changed result file. Neither digest proves the truth of an arbitrary assertion in a file. The result must still be inspected, and consequential checks reproduced when the current task requires them.

For this packet, an offline checker accepted the intact record and rejected variants that lost the reason, changed the evidence digest, reported the unrun browser check as passed, invented a native handoff, or omitted the next action. These are checks on the example's record and evidence. They leave the receiving assistant's behavior to be tested separately.

When receiving work, I use six steps:

  1. Locate the project. Read the project index, identify the correct repository or checkout, and establish the working directory and permitted write area. Similar project names are not enough.
  2. Read current state. Load CONTEXT.md, compare its next task with the working tree, and inspect evidence for claims the next action depends on. Keep “not run” distinct from “passed.”
  3. Consult the reference. Read the relevant decision and its reason. In this example, preserving the tie-break matters even if a different sort implementation looks cleaner.
  4. Inspect the relevant history. Follow the session's artifact pointers. Check what the previous contributor verified, what it could not access, and whether those conditions still apply.
  5. Continue the next authorized task. Establish that the necessary instructions, skills and tools are available. For the example, an assistant without the application environment can inspect the local result but cannot certify the report screen. Continue work that its access supports and identify the missing check precisely.
  6. Update the records before the next handoff. Write the resulting state, retain the new evidence, and attribute the contribution. Synchronize the files needed by the next environment through the project's authorized workflow.

A useful acceptance exercise starts a receiving session without the departing conversation and asks it to identify the requirement, the tie-break reason, the exact checked source and the pending browser review. Then it performs the next permitted task. Run that exercise in each direction you intend to use. A written checklist for the exercise is preparation; the retained session and task result are the evidence that it worked under those conditions.

OpenAI's Sora Android case study reports that four engineers built the app in 28 days in 2025. Its useful connection here is the way the team supplied instructions, planned work, and saved plans to files for longer tasks. Multiple Codex sessions still required attention, review and integration; the case also describes engineering foundations supplied by humans.

That is synthesis engineering under another name. My earlier response examined these practices as synthesis coding. This port applies the same reasoning to project management. If agents are to work as a distributed team, they need shared project memory.

Sora became unavailable on April 26, 2026. The case study preserves how its Android app was built.

Letting judgment compound across tools

Claude Code and Codex have different interfaces, limits, permission models and strengths. Some work will fit one better, and some integrations need tool-specific effort. Portability lets judgment compound across tools: a decision, its reason and the result of checking it remain useful when the next assistant takes over.

The human directs, the AI executes, the human verifies, and the AI iterates. Practice improves the handoff: use both tools on real projects, write down what breaks, and tighten the protocol. Claude Code can be one excellent interface into the system and Codex another. Future agents can join as they become capable, using the same project memory.

Update (July 6, 2026): which agent did what

On July 5, Claude Code ran one session on a project and Codex ran the next, a few hours apart. Both updated project files and committed under the same human Git identity. I wanted the history to answer which agent did the work, at what capability, with what verification. That day I also found model names in commit trailers inherited from an old session template. An authored trailer could repeat a stale claim.

The attribution convention adds one compact entry per materially contributing agent when that information helps future work. It records provenance, not every edit; routine single-agent sessions do not need extra lines. Its six fields are:

agent: the tool actually used
model: exact model string, or unknown
effort: explicitly known setting, or unknown
scope: what this contributor did, including a relevant capability gap
verified: checks actually performed, or none
ref: a real commit or retained artifact, or unknown

The model and effort fields come from the current session or explicit human information. Otherwise they stay unknown. A previous session's model, a remembered setting or a commit trailer cannot fill the gap. A reference should lead to the actual work and verification, and the reader can compare the attribution with that evidence.

The convention entered the context-lifecycle skill, version 1.3.0, and the project-management skill, version 1.1.0, in the July 5 source change. The July 6 article update documented it.

I keep session attribution in the chronological archive. CONTEXT.md needs agent identity only when it changes how the active state should be read. REFERENCE.md can carry a stable capability fact, such as a required integration being unavailable in a particular environment, with enough scope and date to check it again. When access changes, that fact needs updating; the older session record still explains what the previous contribution covered.