codex-chat is a safety-first Codex skill for coordinating a browser-based
external engineering collaborator without turning the user into a manual
copy-and-paste relay.
Codex remains the accountable engineering lead: it understands the request, inspects the repository, limits what source may leave the machine, delegates a bounded task, reviews the response, applies changes only through an isolated scratch copy, and independently runs the required tests.
The external collaborator is an untrusted senior engineer. It can research, challenge a design, review code, or return one tightly bounded patch. Its claims are never treated as proof that the implementation is correct.
Important
This is an experimental local workflow, not an official OpenAI product. Browser availability, account capabilities, usage limits, and model labels can change. The implementation deliberately avoids depending on a particular model or subscription name.
Complex engineering work benefits from separating implementation from acceptance:
| Role | Responsibilities |
|---|---|
| Codex | Product framing, repository inspection, authority boundaries, source selection, task decomposition, communication recovery, integration, testing, security review, and the final verdict |
| External collaborator | Deep research, design alternatives, implementation suggestions, adversarial review, and a bounded advisory or patch result |
| User | Defines the goal and authority; intervenes only for authentication, consequential product decisions, or an unrecoverable external blocker |
The separation is useful only if it remains an actual trust boundary.
codex-chat therefore assumes the collaborator can be mistaken, incomplete,
rate-limited, disconnected, or silently changed by its provider.
flowchart LR
U["User goal and authority"] --> C["Codex lead"]
C --> P["Preflight and minimal context pack"]
P --> S["Secret scan and SHA-256 binding"]
S --> E["External collaborator"]
E --> R["Bounded result envelope"]
R --> Q["Quarantine and validation"]
Q --> I["Scratch-only integration"]
I --> T["Independent local tests"]
T -->|pass| A["Codex accepts"]
T -->|fail| F["Bounded correction turn"]
F --> E
The bundled CLI is a deterministic safety and evidence helper. It does not control the browser, inspect browser profiles, extract cookies, send messages, or call an API. Browser interaction remains a Codex host capability using the user's existing authenticated session.
- Explicit invocation only. Source can leave the local machine, so the skill cannot activate implicitly.
- Authority never expands itself. Permission to edit locally does not imply permission to commit, push, publish, deploy, purchase credits, migrate data, or access production.
- Minimum necessary context. Files are selected explicitly. VCS internals, credentials, environment files, databases, runtime state, browser state, caches, and build output are denied.
- Scan and bind the exact egress. The serialized context sent to the
collaborator is identity-checked with
gitleaks, measured, and bound to a SHA-256 digest. The exact task envelope has its own digest, so context bytes cannot be confused with the actual outbound instruction. Parent gitleaks configuration is removed; inline allow directives and ambient ignore files are disabled in an isolated scan policy. - At-most-once automatic submission. A durable visible marker and idempotency record are created before sending. Ambiguity never authorizes a blind retry.
- Bind the exact response. Both the complete terminal response and the extracted result envelope are scanned and stored as create-once, content-addressed evidence. Review, import, and acceptance revalidate the receipt and reject changed bytes even when run, turn, and context identifiers match.
- Treat returned code as hostile. Results are quarantined and scanned. The MVP accepts either an advisory or a zero-fuzz patch for one existing UTF-8/LF file with an exact preimage digest.
- Apply only to scratch. The collaborator never writes directly to the working tree.
- Verify independently. Test claims from the collaborator are not evidence. Codex runs digest-pinned argument-vector commands locally without a shell. Coordinated acceptance re-hashes every required success receipt.
- Fail closed. Corrupt state, changed paths, missing scanners, exhausted usage, ambiguous sends, and malformed responses stop or suspend the workflow.
- Route by immutable identity. Multi-agent work binds workspace, coordinator, run, work unit, agent, conversation, and turn. Titles and visible model labels are never routing keys. A shared local registry leases both logical conversation identity and confirmed provider locator so active coordinators cannot interleave one conversation.
- Separate source from representations. Exact bytes, excerpts, OCR, page renders, summaries, formulas, displayed values, and crops have separate digests and provenance. Model visibility remains unknown until transport evidence proves otherwise.
The complete rules live in
SKILL.md, with detailed protocol and
security contracts under
references/.
The v2 context sidecar keeps every representation explicit. Original code, text, images, rendered pages, OCR, excerpts, summaries, spreadsheet values, and formulas each carry their own digest, byte count, fidelity, locator, and transformation provenance. A derived representation cannot silently stand in for its source.
Transport evidence is separate from context provenance. A delivery receipt
binds one representation and attachment ordinal to the exact coordinated run
head, route, conversation, turn, provider observation, and scanned raw
evidence. Provider acceptance still leaves modelVisible: "unknown".
Concurrent work is isolated by immutable workspace, coordinator, run, work
unit, agent, conversation, and turn identities. Each run has its own
compare-and-swap ledger; hardened turns lease the provider conversation across
all runs in one state directory; and overlapping writers serialize behind
target-specific locks. Direct mailboxes, broadcast receipts, coordinator
epochs, and fencing remain distributed-extension contracts rather than claims
about the local CLI. See
coordination-v2.md
for the complete local contract and the remaining distributed-fencing work.
- Codex in the ChatGPT desktop app when browser collaboration is required
- An authenticated browser session for the chosen external collaborator
- Node.js 22 or newer
gitleaksavailable onPATH
Authentication, account selection, CAPTCHA, passkeys, passwords, and two-factor verification always remain human actions.
Clone the repository and start Codex from inside it. The skill is already in
.agents/skills/codex-chat, the standard repository-scoped skills location.
git clone https://github.com/xicv/codex-chat.git
cd codex-chatSynchronize the skill to the standard personal skills directory:
mkdir -p "$HOME/.agents/skills/codex-chat"
rsync -a --delete \
.agents/skills/codex-chat/ \
"$HOME/.agents/skills/codex-chat/"The trailing slashes are intentional: they update the existing skill contents
without creating a nested codex-chat/codex-chat directory. Codex detects
skill changes automatically. If an update does not appear, restart Codex.
Open a Codex task and invoke the skill explicitly:
$codex-chat
Work in /path/to/project.
Task:
Fix the intermittent duplicate-processing race in the background worker.
Acceptance criteria:
- Add a deterministic regression test.
- Preserve the public job payload contract.
- Unit, contract, and local E2E tests pass.
Authority:
- Read and modify local source and run tests.
- Do not commit, push, create a PR, deploy, migrate data, purchase credits,
or use paid API fallback.
Codex should then:
- inspect the project and its instructions;
- select and scan only the necessary context;
- reserve and send one bounded external turn;
- monitor without duplicate submission;
- import and review the exact returned result;
- run local acceptance gates;
- send precise correction evidence when necessary; and
- report what is local, committed, pushed, published, or deployed as separate states.
The MVP was developed by applying its own responsibility split:
- Codex established the product boundary, wrote the implementation, and packaged an exact scanned review capsule.
- The external collaborator found concrete flaws in crash recovery, idempotency binding, terminal-result integrity, scanner impersonation, and destructive output handling.
- Codex reproduced those findings, added regression tests, and corrected the implementation.
- After an external
GO, Codex's own dogfood import found another integration defect: an advisory result from an early durable run attempted to canonicalize a missing source root. - Codex fixed the defect test-first, imported the exact external result, sent one final bounded recheck, and reran every local gate.
- A continuation run then examined typed multimodal context and multi-coordinator isolation. The external advisory led to run-head-bound, immutable delivery slots with scanned raw evidence and idempotent replay.
Current local evidence:
| Gate | Result |
|---|---|
| Unit tests | 80/80 |
| Contract tests | 27/27 |
| Chaos/recovery tests | 5/5 |
| Local E2E tests | 2/2 |
| Aggregate test gate | 114/114 |
| Independent scratch verification | Passed |
| Repository source scan | Clean |
| Installed skill parity / secret scan | Exact / Clean |
This example is intentionally not presented as production proof. It demonstrates local orchestration, recovery, correction, and verification.
The executable entry point is:
.agents/skills/codex-chat/scripts/codex-chat.mjs
Run it directly with Node:
node .agents/skills/codex-chat/scripts/codex-chat.mjs --help
node .agents/skills/codex-chat/scripts/codex-chat.mjs preflight \
--root "$PWD" \
--include src/example.mjs
node .agents/skills/codex-chat/scripts/codex-chat.mjs pack \
--root "$PWD" \
--include src/example.mjs \
--output /private/tmp/codex-chat-context.json
node .agents/skills/codex-chat/scripts/codex-chat.mjs manifest \
--root "$PWD" \
--plan /private/tmp/codex-chat-manifest-plan.json \
--output /private/tmp/codex-chat-manifest.json
node .agents/skills/codex-chat/scripts/codex-chat.mjs delivery-receipt \
--state-dir /private/tmp/codex-chat-runs \
--run-id <run-id> \
--manifest /private/tmp/codex-chat-manifest.json \
--plan /private/tmp/codex-chat-delivery-plan.json \
--evidence /private/tmp/codex-chat-provider-evidence.bin
node .agents/skills/codex-chat/scripts/codex-chat.mjs terminal-capture \
--state-dir /private/tmp/codex-chat-runs \
--run-id <run-id> \
--capture /private/tmp/codex-chat-terminal-response.txt \
--result /private/tmp/codex-chat-result.json
node .agents/skills/codex-chat/scripts/codex-chat.mjs recovery-plan \
--state-dir /private/tmp/codex-chat-runs \
--run-id <run-id>Context outputs must be new paths in existing real directories. Delivery receipts use create-only, content-addressed paths beneath the durable run state directory. The CLI never replaces an existing artifact.
| Command | Purpose |
|---|---|
preflight |
Validate source selection, state location, VCS metadata, and scanner availability |
pack |
Create and scan a deterministic COLLAB_CONTEXT_V1 artifact |
manifest |
Create and scan a typed COLLAB_CONTEXT_MANIFEST_V2 provenance sidecar |
delivery-receipt |
Create and scan immutable, digest-bound transport evidence without claiming model visibility |
terminal-capture |
Verify, scan, and publish create-once full-response and result evidence |
record |
Append a typed transition to the hash-chained run ledger |
status |
Derive the current run state and safe next action |
resume |
Recover state without authorizing an unsafe resend |
recovery-plan |
Emit a deterministic read-only transport reconciliation contract |
import |
Bind, quarantine, scan, and optionally apply one result to scratch |
verify |
Execute a digest-pinned verification plan without a shell |
Every command returns one stable JSON envelope suitable for inspection or automation.
codex-chat tracks the controller, collaborator, transport, observed external
model label, agentic allowance, upload capability, and API budget separately.
- A slow or disconnected response remains observe-only after submission.
- A changed reset time or refreshed page never authorizes another send.
- A conclusively failed provider turn ends the current run.
- If the collaborator is temporarily limited, the run records the observation and waits for a known reset or explicit recovery.
- If both Codex and the collaborator are limited, the run suspends with resume metadata rather than spinning or purchasing capacity.
- Codex may take over locally only when the existing authority permits it. The run then permanently records degraded reviewer independence.
- A changed or unobservable model label is reported as an observation, never treated as proof of backend identity.
- A delivery receipt binds one representation and attachment ordinal to a confirmed routed turn, its exact ledger head, and scanned raw observation evidence. It proves neither upload automation nor model visibility.
- A terminal capture receipt binds the exact task, full response, extracted result, route, conversation, turn, provider fingerprint, and terminal marker.
- Equivalent noncritical resource observations may coalesce within five seconds. General idempotency snapshots retain 128 records, outbound records remain permanent, and a run history segment is capped at 1,024 events before an exact-head-bound continuation; the final 32 slots are reserved for safe completion.
- Paid API fallback and automatic credit purchase are disabled by policy.
The runtime has no npm dependencies. Tests use the Node.js built-in test runner.
npm run test:unit
npm run test:contract
npm run test:chaos
npm run test:e2e
npm testThe aggregate npm test gate runs up to four independent test files in
parallel. Focused suites remain serialized to keep failure diagnosis simple.
Project structure:
.agents/skills/codex-chat/
├── SKILL.md
├── agents/openai.yaml
├── references/
└── scripts/
├── codex-chat.mjs
└── lib/
test/
├── unit/
├── contract/
├── chaos/
└── e2e/
Before sharing or publishing changes:
- inspect the exact file inventory;
- search for machine-specific paths and personal identifiers;
- scan the working tree with
gitleaks; - run the project tests;
- inspect the staged diff;
- scan the committed Git history; and
- verify that the remote contains the intended commit only.
Do not commit generated collaboration capsules, run ledgers, browser state, quarantine artifacts, credentials, or local verification evidence.
Security assumptions and exclusions are documented in
references/security.md.
- The MVP imports at most one existing text-file patch per result.
- The CLI provides evidence and state management; it does not itself automate a browser.
- The v2 manifest records typed representations, and the receipt command binds
observed transport acceptance or rejection. Attachment upload, delta
reconstruction, and proof of backend model visibility are not implemented;
modelVisibleremainsunknown. - Coordinated local runs reject crossed routes, lease provider conversations, and serialize import targets when every coordinator shares one canonical state directory. Multi-host coordinator epochs, externally fenced leases, durable partitioned mailboxes, backpressure, and cancellation remain distributed-extension work.
- Hosted, production, deployment, and physical-device verification are outside the local E2E evidence class.
- Original dual-agent workflow article (Chinese) — inspiration for separating the engineering collaborator from the accountable lead; its product and model claims are not treated as implementation requirements.
- OpenAI: Build skills — skill structure, explicit invocation, local discovery, and supporting resources.
- OpenAI: Browser — built-in browser capabilities, separate browser profiles, permissions, and safety boundaries.
- Agent Skills specification — the open skill format
used by
SKILL.md. - Gitleaks — secret scanning for exact context and result artifacts.
codex-chat is an MVP intended for local experimentation and review. It is not
an official OpenAI project, and it is not yet distributed as a plugin or npm
package.