// Blog / comparison
Claude Code vs Codex for repo context
The important question is not which agent remembers your repo better. It is whether both agents can read the same repo-owned source of context.
// direct answer
Short answer
Claude Code and Codex can have different UX, model behavior, and tool ergonomics. A repo-local .knowledge layer gives both the same first-read contract: routing bundle, trust report, module cards, evidence, repair queue, and source-of-truth rules.
Understand how Claude Code, Codex, and other coding agents can share repo context without relying on one chat history.
// real failure mode
The failure mode
One agent builds useful repo context in its own session. Another agent starts later and repeats the orientation crawl.
The team then has two partial memories: one in chat history, one in tool state, neither easy to review beside the code.
Switching agents becomes expensive because each tool has to rediscover the same project structure and the same trust warnings.
// shared layer
The repo-local fix
.knowledge makes the shared context an artifact of the repository instead of an accident of one agent session.
Codex can read `.agents/skills/*/SKILL.md`; Claude Code can read `.claude/skills/*/SKILL.md`; both point back to the same .knowledge files.
The agent-specific integration changes, but the source-of-truth order stays the same.
// concrete example
A handoff between agents
Codex starts a migration, runs a release check, and leaves the module marked `needs_recheck` because tests were not conclusive.
Claude Code picks up the next task. Instead of trusting the prior chat, it reads the routing bundle, trust report, repair queue, and current source.
The handoff is now encoded in repo-local artifacts, not in one private conversation.
// repo proof
Repo proof to inspect
.agents/skills/*/SKILL.md
Codex-specific workflows can point to the same .knowledge files the rest of the team uses.
- Codex onboarding
- Repeatable local commands
- Agent-specific product claims
- Skipping source review
.claude/skills/*/SKILL.md
Claude Code can consume the same repo-local routing layer with its own skill format.
- Claude handoff
- Shared source-of-truth rules
- Assuming identical model behavior
.knowledge/agent-integrations/
Agent integrations make the shared context portable across tools.
- Installing or refreshing integrations
- Auditing what each agent reads first
- Hiding agent instructions outside the repo
.knowledge/maintenance/handoff_summary.json
A compact handoff summary gives the next agent a repo-local continuation point.
- Session handoff
- Finding pending repair work
- Treating handoff prose as proof
// command transcript
Commands and expected checks
node .knowledge/tools/install-agent-integrations.js - expected
- Codex, Claude Code, OpenCode, and command integrations are installed or refreshed.
- inspect next
- .agents/skills/ and .claude/skills/
node .knowledge/tools/build-routing-bundle.js - expected
- The shared routing bundle is rebuilt for all agents.
- inspect next
- .knowledge/maintenance/routing_bundle.json
node .knowledge/tools/doctor.js - expected
- The next agent sees whether the shared layer is usable or needs caution.
- inspect next
- .knowledge/maintenance/quality_report.json
One repo-local layer, multiple agents
// field guide
Comparison that matters
| Area | Tool-specific behavior | Shared .knowledge behavior |
|---|---|---|
| Onboarding | Each agent may have a different command surface. | Each agent reads the same routing bundle and trust report. |
| Memory | Session memory can be private to one tool. | Repo-local artifacts are reviewable and portable. |
| Handoff | Chat summaries can drift. | Handoff points to source, evidence, and repair queue. |
| Review | Agents can produce different plans. | Both plans can be checked against the same source-of-truth order. |
// guardrails
What the agent should not trust blindly
- Do not assume Claude Code and Codex interpret a task identically.
- Do not let either agent treat its chat history as stronger than current source and tests.
- Rebuild the routing bundle after meaningful knowledge changes so both agents start from the same map.
// common mistakes
Common mistakes
- Comparing agents only by prompt feel instead of handoff quality.
- Keeping Codex instructions in one place and Claude instructions in another with no shared contract.
- Letting one agent's stale summary become the next agent's source of truth.
// quick FAQ
FAQ
Should a team pick only one coding agent?
Not necessarily. The safer pattern is to make the repository own the shared context so different agents can be swapped or combined.
Does .knowledge make all agents behave the same?
No. It gives them the same first-read map and trust rules. Model behavior and tool UX still differ.
// page-specific next step
Use this page when running more than one coding agent
Install the agent integrations, make .knowledge the first-read layer, and keep source and tests above every generated summary.