README
¶
Codex Handoff Kit
Portable, verifiable task handoffs for Codex.
Codex Handoff Kit captures the goal, progress, decisions, Git checkpoint, validation evidence, risks, and next actions needed to continue a coding task in a fresh account, session, or machine. It creates an open file bundle that any coding agent can read; the Codex plugin makes saving and resuming conversational.
Independent community project. Not affiliated with or endorsed by OpenAI.
Why this exists
codex resume continues a saved local session, while compaction keeps a long conversation usable. Neither is a portable, reviewable handoff artifact for a different account or machine. The same gap is described in openai/codex#21673.
This project deliberately does not clone a chat. It creates a new, explicit continuation boundary.
flowchart LR
A["Current Codex session"] --> B["Skill writes semantic draft"]
H["Low-sensitivity hooks"] --> C
B --> C["Go CLI enriches, redacts, validates"]
C --> D["Portable handoff bundle"]
D --> E["Fresh Codex account or session"]
E --> F["Verify drift and produce continuation plan"]
60-second workflow
$ codex-handoff init --hooks user
Initialized .codex-handoff
# In Codex:
> Use $codex-handoff to save this task before I switch accounts.
$ codex-handoff verify
Valid: true
$ codex-handoff export --out ../project-handoff.zip
Exported: ../project-handoff.zip
# In the fresh account/session:
> Read .codex-handoff/current/HANDOFF.md and resume this task.
The handoff package contains:
HANDOFF.md human-first continuation brief
state.json canonical machine-readable task state
events.jsonl curated milestone timeline
decisions.md rendered decision log
next-actions.md rendered ordered work queue
environment.json sanitized Git and dependency checkpoint
manifest.sha256 integrity hashes
Install
CLI
With Go 1.26 or newer:
go install github.com/nnccc415/codex-handoff-kit/cmd/codex-handoff@latest
Prebuilt Windows, macOS, and Linux archives are published on the Releases page. Every release includes checksums and an SBOM.
Codex plugin
codex plugin marketplace add nnccc415/codex-handoff-kit
codex plugin add codex-handoff-kit@codex-handoff-kit
Start a new Codex task after installation so the skill is discovered. Hooks are installed separately by the CLI because they must point at the local binary and be reviewed:
codex-handoff init --hooks user
Open /hooks in Codex to review and trust the installed definition.
Commands
| Command | Purpose |
|---|---|
init [--hooks user|repo|none] |
Initialize private project storage |
save --draft FILE |
Create a verified snapshot from semantic JSON |
save --interactive |
Create a minimal snapshot without the skill |
status |
Show the active handoff and Git drift |
verify [PATH] [--json] |
Validate schema, required files, hashes, and secret findings |
export --out FILE.zip |
Create a portable ZIP; blocks on potential secrets |
import FILE.zip [--activate] |
Safely extract and optionally activate a package |
resume [--print-prompt] |
Print the continuation boundary and drift status |
hooks install|status|uninstall |
Manage idempotent lifecycle hooks |
recover list |
List local Codex sessions without exposing absolute paths |
recover SESSION_ID |
Experimental visible-message recovery |
See the v1 protocol and threat model for exact behavior.
Privacy and security defaults
.codex-handoff/is added to.gitignore.- Hooks record event type, tool name, timestamp, and hashed session/turn references only.
- Environment capture excludes environment variable values, usernames, absolute workspace paths, raw diffs, and credential-bearing URLs.
- Semantic drafts are redacted before validation and storage.
- Export fails when known private-key, bearer-token, GitHub, OpenAI, AWS, credential-URL, or secret-assignment patterns remain.
- ZIP import rejects traversal, nested entries, duplicate names, non-regular files, and oversized archives.
- Transcript recovery excludes system/developer messages, reasoning, tools, outputs, images, and encrypted content, and fails closed on unknown event shapes.
Review every handoff before sharing it. Pattern scanning reduces risk; it cannot prove that arbitrary prose contains no confidential information.
What cannot be transferred
Account memory, original chat identity, hidden reasoning, OAuth grants, plugin permissions, quotas, credentials, secrets, cloud-task access, and uncommitted files themselves are not migrated. File entries are references to a Git/worktree checkpoint, not a source-code backup.
Protocol compatibility
state.json follows JSON Schema Draft 2020-12. Readers accept compatible 1.x packages and reject unknown major versions. Markdown files are deterministic views of state.json; they are not independent sources of truth.
Quality gates
- Core protocol and redaction coverage: at least 90%.
- Required state-field completeness: 100%.
- Seeded secret corpus: zero exported known secrets.
- Windows, macOS, and Linux CI.
- Ten blind continuation cases with a target of at least 9/10 passing.
The repository includes reproducible case definitions and a rubric, but they are evaluator-only inputs. Tested Codex sessions run in isolated fixture workspaces created by scripts/prepare-eval.go, which refuses known rubric and prior-result artifacts. The project does not publish a success claim until a dated, versioned fresh-session run is recorded. See evals/README.md.
Development
go test ./...
go test -coverprofile=coverage.out ./internal/protocol ./internal/security
go run ./scripts/scan-repository.go
go run ./scripts/validate-evals.go
go run ./scripts/prepare-eval.go --source /path/to/fixture --out /path/to/isolated-workspace
go build ./cmd/codex-handoff
Plugin and skill validation commands are documented in CONTRIBUTING.md.
Directories