An opinionated, configurable collaboration harness for handing bounded work between Claude Code and Codex without losing scope, ownership, review evidence, or resume state.
It enforces conservative defaults around ownership, model spending, data egress, review scope, and Git hook activation while allowing repository-specific commands and path policies.
The bundle supports both directions:
- Claude → Codex for implementation, investigation, adversarial review, and computer-use prompts.
- Codex → Claude for a frontend slice backed by a durable, bidirectional task backlog.
- Either model → the other for bounded, grounded ideation and architecture deliberation.
These are workflow and prompt wrappers. They do not install either CLI, authenticate accounts, grant permissions, or bypass sandboxing.
The bundle also ships optional collaboration review hooks. Installing the bundle copies that module but does not activate it or change Git configuration.
| Skill | Invoked by | Delegates to | Purpose |
|---|---|---|---|
codex-implementation |
Claude Code | Codex | Bounded implementation, debugging, refactoring, tests, or investigation |
codex-review |
Claude Code | Codex | Adversarial, read-only review of a diff, plan, branch, commit, or patch |
codex-computer-use |
Claude Code | Codex | Safe preparation of browser, screenshot, desktop, or visual-QA work |
ui-nitpicker |
Claude Code | Codex | UI implementation plus optional/required Codex frontend-logic audit |
delegate-frontend-to-claude |
Codex | Claude Code | Backend-first delegation of a bounded frontend slice with resumable queues |
deliberate-with-peer |
Either | Other model | Grounded proposals, critique, adjudication, and bounded consensus |
route-codex-subagents |
Codex | Codex | Cost-aware Sol/Terra routing for explicitly requested internal delegation |
integration-review |
Codex | — | Decisive root-owned acceptance gate over the complete tree, with a validator |
setup-collaboration-hooks |
Codex | — | Safe installation, adaptation, composition, and deactivation of review hooks |
collab-config |
Either | — | View or change every bundle setting: models, budgets, rates, audit policy |
session-handoff |
Either | — | Write a resumable handoff and end an expensive session cleanly |
| Phase | Owner | Responsibility |
|---|---|---|
| 1. Scope | Codex | Record the request, ownership boundaries, queues, and starting state |
| 2. Backend | Codex | Implement and verify backend behavior and shared contracts |
| 3. Frontend | Claude | Review the backend contract, implement the UI slice, and report findings |
| 4. Return work | Codex or Claude | Route confirmed findings through the appropriate model queue |
| 5. Audit | Codex | Audit Claude's frontend logic and report a separate evidence-based verdict |
| 6. Integration | Codex | Inspect the complete diff, run combined checks, and update the backlog |
| 7. Delivery | Operator | Decide whether to commit, push, open a pull request, or merge |
Delegation state lives in:
plans/agent-handoffs/<task-slug>.md
The backlog records stable task IDs, model-owned queues, contract checkpoints, blockers, changed paths, verification evidence, the next owner, and an exact resume prompt. A temporary CLI prompt points to this file; it never replaces it.
- Git repository with project instructions available to both agents.
- Claude Code CLI installed and authenticated for Claude-owned work.
- Codex CLI installed and authenticated for Codex-owned work.
- Bash 4 or newer for the installers and hook adapters.
- Git and standard Unix tools (
rg,sed,awk,grep, andfind); install additionally requiressha256sum. - Python 3 for the
review_gatereview runtime, peer preference parsing, session handling, alert configuration, and release archives. - Node and pnpm only when the target repository's configured checks use them.
Verify the CLIs:
command -v claude
claude --version
command -v codex
codex --version
codex exec --help | sed -n '1,80p'Do not infer browser or computer-use support from the Codex CLI alone. Use those capabilities only when the active environment visibly exposes them.
Project-local installation is recommended because the skills and their assumptions can be reviewed and versioned with the repository.
From this repository or an extracted release bundle:
./install.sh /path/to/your/repoThe installer copies:
.claude/skills/* → /path/to/your/repo/.claude/skills/
.agents/skills/* → /path/to/your/repo/.agents/skills/
review-hooks/* → /path/to/your/repo/review-hooks/
It then generates one file that has no counterpart in the bundle,
/path/to/your/repo/.codex-claude-skills-version, stamping which bundle release the copied files
came from. It is rewritten only when its contents would change.
The copied hook module remains inactive. Before writing anything, the installer compares every
existing bundled skill and review-hooks/ directory with the bundle. Any drift is displayed and
preserved. After reviewing the diff, --force explicitly updates bundled files:
./install.sh --repo /path/to/your/repo --forceThis makes repeat installation safe for repositories whose local skill copies have evolved. Files
that exist only in a drifted destination are retained even with --force; remove obsolete local
files as a separate, reviewable change.
To report what a repository has without writing anything, use --check. It prints one line per
installed tree, compares the stamp against this bundle, and exits 0 when the repository is
current — or is the bundle itself, which is an install source and never a target — 1 when it is
missing content, drifted, or stamped from another release, and 2 on a usage error, an unusable
target, or a missing requirement. This is the supported way to sweep many repositories:
for repo in ~/projects/*/; do
root="$(git -C "$repo" rev-parse --show-toplevel 2>/dev/null)" || continue
[ "$root" = "$(cd "$repo" && pwd -P)" ] || continue
./install.sh --check --repo "$repo"
doneBoth guard lines matter. rev-parse alone is not enough: for a plain directory inside a Git
repository it succeeds and reports that repository's root, so the sweep would silently check — and
with --force, write to — a repository the operator never named. Comparing the reported root
against the swept path keeps the sweep to actual repository roots. The loop reports per repository
and does not aggregate; check the individual exit codes if you need a single verdict.
VERSION at the bundle root versions the bundle release as a whole; it is what --check,
doctor.sh, and the installed stamp compare. review-hooks/VERSION separately versions the review
runtime component and is pinned to RUNTIME_VERSION, which labels every run.json. They version
different things and are expected to differ.
To install manually:
mkdir -p /path/to/your/repo/.claude/skills
mkdir -p /path/to/your/repo/.agents/skills
cp -R .claude/skills/* /path/to/your/repo/.claude/skills/
cp -R .agents/skills/* /path/to/your/repo/.agents/skills/
cp -R review-hooks /path/to/your/repo/Optionally copy the relevant content from
CLAUDE.md.codex-skills-snippet.md into the target repository's CLAUDE.md.
Global installation makes the skills available across repositories, but project-local copies are safer when repositories have different ownership or verification rules.
mkdir -p ~/.claude/skills ~/.agents/skills
cp -R .claude/skills/* ~/.claude/skills/
cp -R .agents/skills/* ~/.agents/skills/Run the read-only doctor against the target repository:
./doctor.sh --repo /path/to/your/repoIt reports a capability matrix covering system dependencies, bundled skill presence and drift, CLI
availability, GitHub CLI authentication, the active Git hook path, hook executability, AI-review
state, the implement → /tdd dependency, manual page-audit safeguards, and release-archive
freshness. Warnings are advisory by default; --strict makes them fail. The doctor does not install
packages or skills, change Git config, authenticate tools, enable AI review, or approve pages.
For direct inspection from the target repository:
find .claude/skills .agents/skills -maxdepth 2 -name SKILL.md -print | sort
bash -n .agents/skills/delegate-frontend-to-claude/scripts/run-claude-frontend.shExpected skill entry points:
.agents/skills/collab-config/SKILL.md
.agents/skills/delegate-frontend-to-claude/SKILL.md
.agents/skills/deliberate-with-peer/SKILL.md
.agents/skills/session-handoff/SKILL.md
.agents/skills/setup-collaboration-hooks/SKILL.md
.claude/skills/codex-computer-use/SKILL.md
.claude/skills/collab-config/SKILL.md
.claude/skills/deliberate-with-peer/SKILL.md
.claude/skills/codex-implementation/SKILL.md
.claude/skills/codex-review/SKILL.md
.claude/skills/session-handoff/SKILL.md
.claude/skills/ui-nitpicker/SKILL.md
bootstrap.sh is the single entry point for installing the bundled helpers and, when explicitly
requested, activating their deterministic hardening gates:
./bootstrap.sh \
--repo /path/to/your/repo \
--activate \
--profile genericIt runs a dependency capability report first, installs from the current bundle directory with drift
protection, activates pre-commit, commit-msg, and pre-push through core.hooksPath, then runs the full doctor
again. Omit --activate for install-only behavior.
Plain bootstrap never installs system packages. To explicitly install missing, safely mapped core dependencies or active hook dependencies, use:
./bootstrap.sh --repo /path/to/your/repo --install-depsUse --deps-dry-run to print the package-manager command without executing it. The capability
manager supports apt, dnf, yum, apk, pacman, and Homebrew. It does not install Node, pnpm, Claude,
Codex, or the optional gh CLI because their versions, accounts, quotas, and authentication belong
to the operator. It never authenticates credentials. gh auth status is checked read-only when
gh is already installed.
The activation flag does not enable quota-consuming AI review, add CI secrets, configure branch
protection, or approve pages. Those remain separate operator decisions. Existing hook systems are
still refused unless the operator explicitly selects --replace-hooks-path; use manual composition
when both systems must remain active.
In an interactive terminal, bootstrap also asks whether to enable Claude Code's user-level terminal bell when Claude finishes or needs attention. Automation can decide explicitly:
./bootstrap.sh --repo /path/to/your/repo --claude-alert enable
./bootstrap.sh --repo /path/to/your/repo --claude-alert skipThe setting is merged into ~/.claude/settings.json without replacing other keys. It uses Claude
Code's supported preferredNotifChannel: "terminal_bell" setting; it does not install a
quota-consuming hook. This remains Claude's own notification, not a copy of Codex's completion
alert. When Codex launches a nested Claude task, Claude can ring as soon as its subprocess finishes
while Codex continues integrating the result and later emits its own completion notification. The
runners do not add a second wrapper bell.
The optional module separates deterministic commit checks from aggregate AI review:
pre-commit → staged whitespace, secret scan, configured deterministic commands
commit-msg → configured deterministic message commands (no-op by default)
pre-push → configured deterministic commands → bounded aggregate AI review
Inspect its interface and perform a dry run before activation:
sed -n '1,260p' review-hooks/README.md
review-hooks/install.sh \
--repo "$PWD" \
--profile generic \
--dry-runThe generic profile leaves AI review disabled. Activation is a separate explicit command:
review-hooks/install.sh \
--repo "$PWD" \
--profile genericThe installer refuses to replace an existing Husky, Lefthook, .githooks, or other
core.hooksPath configuration by default. Use --no-activate to compose with an existing system.
See review-hooks/README.md for the profile interface, resource budgets,
credential rules, deactivation, and the LMM reference adapter.
Repositories may also opt into a profile-owned durable-intake command that must preserve a fresh
non-blocking MERGE-WITH-FIXES decision before the gate caches or reuses it. The generic profile
leaves this off; the LMM reference adapter shows the repository-specific command without bundling
its tracker.
Repositories with a manual page-review ledger can add its advisory checker to
PRE_PUSH_COMMANDS. The LMM reference profile does this with pnpm audit:pages. Agents may detect
stale approvals, demote affected routes with a specific reason, register new routes as PENDING,
and report the operator queue. They must never approve a page: approval represents a person
physically inspecting the rendered surface.
The broader Matt Pocock engineering flow's implement skill invokes /tdd. This collaboration
bundle does not vendor that third-party flow, but the doctor detects a dangling reference when
implement is installed without tdd.
Install the upstream skill explicitly for agents that use that flow:
npx skills add https://github.com/mattpocock/skills \
--skill tdd \
--agent '*' \
--global \
--yes \
--copy \
--full-depthReview upstream changes before updating it. Skill-directory install counts are discovery and popularity signals, not security or quality audit evidence.
Ask Claude Code:
Use codex-implementation to implement the narrowest fix for this bug, then inspect the complete diff and run the relevant tests yourself.
Use codex-review adversarially on my staged changes. Block on concrete correctness, security, migration, data, or compatibility issues.
Use codex-computer-use to prepare a scoped browser QA pass for the local checkout flow. Do not touch production, billing, or real customer data.
Use ui-nitpicker to review this dashboard against our design spec, write the implementation plan, implement it, then give Codex a read-only frontend logic audit under my peer-audit policy.
Ask Codex:
Use delegate-frontend-to-claude to record both model queues in a durable backlog, implement and verify the backend contract, delegate the bounded frontend slice to Claude, and verify the integrated result.
The Codex-side runner can also be invoked directly after creating the backlog and a filled handoff prompt:
prompt_file="$(mktemp /tmp/claude-frontend-handoff.XXXXXX.md)"
.agents/skills/delegate-frontend-to-claude/scripts/run-claude-frontend.sh \
--prompt-file "$prompt_file" \
--backlog-file "plans/agent-handoffs/<task-slug>.md" \
--repo "$PWD"The runner refuses unrelated dirty files by default. Use --allow-dirty only after proving every
existing change belongs to the delegated task. Use --dry-run to validate the inputs without
launching Claude.
Claude reviews Codex's backend and contract checkpoint before consuming it. After Claude implements the frontend, Codex separately audits the Claude-authored logic before integration. The Codex verdict covers state, data flow, contract consumption, permissions, failure states, accessibility semantics, rendering cost, and test sensitivity; Claude retains design ownership and fixes its frontend findings.
Direct Claude Code UI work gets the same opportunity through ui-nitpicker → codex-review. The
policy is required, offer, or off. An explicit skip records authority and reason; capacity or
execution failure is INCONCLUSIVE, never a pass.
Invoke deliberate-with-peer from either environment:
Use deliberate-with-peer to evaluate whether this checkout workflow belongs in the API or web shell. Ground both positions in the repository, reconcile material disagreements, and preserve the decision record.
The initiator remains in its current thread, at the model and effort that environment is already set to. The runner starts one fresh peer session for the decision and resumes that exact session for at most one focused rebuttal or confirmation. Session ids, positions, evidence, disagreements, adjudication, and the exact resume prompt live in:
plans/model-deliberations/<task-slug>.md
Architecture and implementation plans can select Codex as artifact author and Claude as
adversarial reviewer even when the request begins in Claude. The terminal states are CONVERGED,
CONVERGED_WITH_DISSENT, NEEDS_EXPERIMENT, NEEDS_OPERATOR, or an explicit capacity/execution
blocker. The flow never forces matching preferences or silently treats an unavailable peer as
agreement.
Copy and edit the non-executable JSON example outside the project:
mkdir -p ~/.config/codex-claude-skills
cp preferences.example.json ~/.config/codex-claude-skills/preferences.jsonThe example selects Claude Fable 5/xhigh and GPT 5.6 Sol/high for peer deliberation and architecture
work, a two-call maximum, resume-within-task sessions, Codex-authored architecture, and an offer
peer-audit policy. Only the two deliberate-with-peer runners read the model and effort fields,
and each field configures the peer call only: codex.* applies when Claude initiates and calls
Codex, claude.* applies when Codex initiates and calls Claude. The initiating session always
runs at whatever model its own CLI is currently set to—in Claude Code, the window's /model
selection. Starting a deliberation from an Opus window keeps the entire Claude side on Opus; the
preferences file never switches the initiator, and the skill will flag the mismatch rather than
silently proceed.
Implementation, frontend delegation, code review, hooks, and every other skill retain the
developer's Claude or Codex environment defaults. Explicit runner flags take precedence. Missing
values preserve each environment's normal defaults. No fallback model is selected automatically.
Internal Codex delegation uses roles rather than letting each workflow choose a model independently. The recommended shape is a Sol primary thread, bounded Terra workers, and at most one Sol reviewer when risk or unresolved ambiguity warrants it:
Sol primary → Terra explorer or implementer → primary verification → optional Sol review
Start with no more than two children, cap open child threads at three, and cap each user task at
three primary-authorized child creations and four delegated child turns. Closing a child restores
no budget. Persist that budget under plans/agent-runs/ so resuming a task continues the same
counters. Initialize each ledger with the active canonical root and an immutable snapshot of the
pre-existing agent tree; ledgers from before baseline-aware schema v2 fail closed rather than
guessing historical ownership. Baseline ids cannot settle current-task reservations. Keep only one
spawn reservation unresolved, settling or tree-reconciling it before reserving another even when
starting two independent workers. A
definitively failed spawn remains charged but can be closed after complete-tree reconciliation
confirms that no child exists, preserving retry capacity without weakening accounting.
Prohibit descendant spawning and prefer bounded context packets, while allowing justified
full-history forks according to the active spawn contract. Reconcile the observable agent tree
before and after child turns; an unexpected descendant is charged, violates the ledger, and stops
further delegation. Terra workers must return an acceptance ledger; the primary rejects completion
when any criterion is missing or uncertain. Deterministic searches and checks stay in the primary
thread instead of consuming an agent call.
Keep model and effort selection in Codex custom-agent profiles or trusted project configuration.
Skills should request terra_explorer, terra_implementer, or sol_reviewer by role and remain
independent of model pricing. Terra Medium is the implementation default; Terra Low is reserved for
read-heavy exploration. An unavailable cheaper adapter never silently fans out into Sol children.
See Codex subagent routing architecture for the routing seam, task packet, configuration, escalation rules, and worker return contract.
The installable route-codex-subagents skill applies this policy when a user, AGENTS.md, or
another skill explicitly requests subagents. It uses explicit Terra model/effort overrides where
the active spawn contract permits them, tracks concurrent and cumulative fan-out, and centralizes
the acceptance-ledger and escalation contract. Installing the bundle makes the workflow available
without changing personal Codex model or quota settings.
One file owns every setting: ~/.config/codex-claude-skills/preferences.json. Skills read
resolved values from it instead of naming a model, provider, or budget directly, so changing what
a skill uses is a configuration edit rather than a code edit.
mkdir -p ~/.config/codex-claude-skills
cp preferences.example.json ~/.config/codex-claude-skills/preferences.jsonThen edit it directly, or ask the bundle: /collab-config in Claude Code, $collab-config in
Codex.
claude and codex set provider defaults; skills overrides per skill, because one provider can
serve different work with different models:
{
"claude": { "model": "claude-fable-5", "effort": "xhigh" },
"codex": { "model": "gpt-5.6-sol", "effort": "high" },
"skills": {
"codex-review": { "model": "gpt-5.6-terra", "effort": "medium" }
}
}Resolution walks skill → provider and stops. A field absent at every level stays absent, so an
unconfigured model falls through to whatever the CLI itself defaults to — the bundle never invents
one. An explicit null means unset: it falls through to the next level and cannot dodge a
repository cap. Explicit runner flags and explicit user instructions outrank the file. Inspect
what a skill will actually use:
resolver=.claude/skills/collab-config/scripts/resolve_config.py
python3 "$resolver" --skill codex-review
python3 "$resolver" --skill deliberate-with-peer --provider codex
python3 "$resolver" --policy peerAudit
python3 "$resolver" --showNo model list is validated anywhere. New models, renamed models, and provider-specific identifiers all work by putting the string in the config.
Cost reporting is the one place that needs a price, and the bundle ships no built-in price table —
prices change faster than releases. Rather than fail or guess, a model without a modelRates
entry reports tokens only and says how to price it:
{
"modelRates": {
"claude-fable-5": { "input": 5.00, "output": 25.00 }
}
}Rates are USD per million tokens. Cache pricing defaults to the standard multipliers (read 0.1×,
5-minute write 1.25×, 1-hour write 2× of input) and each may be overridden per entry with
cacheRead, cacheWrite5m, or cacheWrite1h. A malformed entry is dropped with a warning rather
than half-applied.
A repository may ship .codex-claude-skills.json at its root to tighten policy. Two classes,
with opposite winners:
| Class | Keys | Repository may |
|---|---|---|
| Spend-authorizing | claude.maxBudgetUsd, codex.maxBudgetUsd, deliberation.maxRounds |
lower a value — never raise it |
| Process policy | peerAudit.policy |
require stricter than the operator's — never weaker |
Anything else in that file — a model, an effort, a billing mode — is refused loudly. An attempt to
widen a spend control is an error naming both values, not a silent clamp; for process policy the
comparison is anchored to the operator's preference or, when unset, the documented default, so a
repository cannot weaken below offer just because the operator never wrote the key. A
repository budget cap — even one equal to the operator's value — bounds any per-skill
maxBudgetUsd override. Nothing
checked into a repository can authorize spending against a personal account. The doctor runs the
resolver and fails when a repository policy does not compose with the user's preferences.
Long sessions get expensive in a way that is invisible while it happens. Every request re-sends the whole conversation and the cached prefix bills at read rate on every turn, so cumulative cost is roughly turns × context — and since context grows with turns, cost rises with roughly the square of session length. The governor reads a Claude Code session transcript and reports it:
governor=.claude/skills/collab-config/scripts/session_governor.py
python3 "$governor" --transcript ~/.claude/projects/<slug>/<session-id>.jsonl --billing planTurns: 214 Rebuilds: 25 Peak context: 631,178 tokens
Cache: 53,191,616 read, 9,691,848 written (5m), 0 written (1h)
Cost: $93.29 API-equivalent (not charged on a plan)
Each further turn re-reads the context for about $0.32
File drift: 0.20
It recommends a handoff only when a session is both expensive and drifted off the files it
started on. Expensive alone is not a reason — a long session on one task is the prompt cache
working correctly. Billing mode matters and is declared, never inferred: under a subscription
plan the dollar figure is an inert API-equivalent shown because "$47 equivalent" reads faster
than "94M cache-read tokens"; under --billing api the figures are real.
To run it after every turn, add a Stop hook to Claude Code settings; in --hook mode it reads
the hook payload on stdin, surfaces advice as a systemMessage, and always exits zero — advice
that could block a turn would be worse than no advice.
/session-handoff in Claude Code, $session-handoff in Codex. This writes
plans/agent-handoffs/<task-slug>.md — the same artifact the delegation runner already
validates — so a cost-driven handoff and a model-to-model handoff are interchangeable.
- Keep the operator as the commit, push, and merge gate unless explicitly authorized otherwise.
- Give every task a stable ID and assign it to Codex, Claude, or the operator before delegation.
- Preserve unrelated work; never reset, stash, discard, or reformat it to manufacture a clean tree.
- Inspect staged, unstaged, and untracked files after every delegated run.
- Treat model summaries as leads, not proof. Re-run relevant checks in the integrating agent.
- Keep credentials, private data, production values, and unrelated diffs out of prompts.
- Escalate security and money-movement blockers to a human instead of silently downgrading them.
- Never mark a delegation complete while any model or operator queue still contains open work.
- Do not let delegated agents spawn descendants unless a repository-specific architecture replaces the default bounded routing policy.
The Claude → Codex skills are broadly repository-agnostic and instruct the agent to discover local guidance before acting.
delegate-frontend-to-claude currently encodes the ownership model it was designed for:
- Codex owns backend services, APIs, SQL, migrations, and shared backend contracts.
- Claude owns
apps/web/implementation and frontend tests. - Non-trivial frontend work uses
ui-nitpicker. - Its handoff template references TanStack navigation, a design system,
pnpmchecks, and a page visual-audit workflow.
Before using that skill in a repository with a different layout or stack, adapt the ownership paths, frontend guidance, validation commands, and visual-release rules. Do not let either model guess replacement conventions.
.agents/skills/
collab-config/
SKILL.md
scripts/resolve_config.py
deliberate-with-peer/
delegate-frontend-to-claude/
SKILL.md
agents/openai.yaml
references/
delegation-backlog-template.md
frontend-handoff-template.md
scripts/run-claude-frontend.sh
integration-review/
SKILL.md
agents/openai.yaml
references/
decisive-integration-review-gate.md
integration-review-artifact-template.json
scripts/check-integration-review-readiness.mjs
route-codex-subagents/
SKILL.md
references/task-packet.md
scripts/subagent_ledger.py
session-handoff/
SKILL.md
setup-collaboration-hooks/
SKILL.md
.claude/skills/
codex-computer-use/
collab-config/
SKILL.md
scripts/
resolve_config.py
session_governor.py
deliberate-with-peer/
codex-implementation/
codex-review/
session-handoff/
SKILL.md
ui-nitpicker/
review-hooks/
hooks/
profiles/
scripts/
tests/
README.md
install.sh
scripts/bundle-version.sh
scripts/configure-claude-alert.py
scripts/manage-dependencies.py
CLAUDE.md.codex-skills-snippet.md
README.md
LICENSE
VERSION
bootstrap.sh
doctor.sh
install.sh
package.sh
preferences.example.json
tests/
codex-claude-skills.tar.gz
codex-claude-skills.zip
The ZIP and TAR files are committed release artifacts. Rebuild both after any bundled skill, installer, snippet, or README change:
./package.shVerify the archive entry points and test installation from an extracted archive before committing. This single command runs syntax checks, both test suites, and the archive check:
bash tests/run-all.shWhen behavior changes, update the relevant skill, this README, and both archives in the same commit.
Use Git tags or GitHub releases when consumers need a stable version instead of tracking main.
Bob Oyier
Licensed under the MIT License.