Keep Codex work portable across machines, repos, and sessions.
codex-handoff watches repo-related Codex sessions, builds repo-scoped handoff
memory under .codex-handoff/, and syncs that state to a remote backend so you
can resume on another machine with the right context already in place.
Codex is OpenAI's coding agent. OpenAI describes Codex as "a coding agent that helps you build and ship with AI—powered by ChatGPT" and the Codex app as "a command center for agentic coding." Download and learn more at openai.com/codex or read Introducing the Codex app.
codex-handoff is built for repo-scoped, one-person handoff across machines.
It keeps pulled thread state under .codex-handoff/synced-threads/, keeps
local pushable thread state under .codex-handoff/local-threads/, and can run
background sync while Codex is open. It can also keep a compact repo-level
memory file at .codex-handoff/memory.md so new sessions can start from a
short summary before drilling into synced thread detail.
Open the Codex app in the project you want to manage, make sure that project is
the current workspace/cwd, and paste one of these prompts into the Codex chat.
Use the same setup-and-start prompt on another PC. Plain setup already
decides whether this repo should pull remote state or push local state.
Install if needed, then set up and start:
Install or upgrade `@brdgkr/codex-handoff` with npm if needed, then set up codex-handoff for this repository and start the agent.
Finish only when setup has completed and the agent is running.
Set up and start when the package is already installed:
Set up codex-handoff for this repository and start the agent.
Finish only when setup has completed and the agent is running.
Set up this repo without starting the agent yet:
Set up codex-handoff sync for this repository, but do not start the agent yet.
The first supported backend is Cloudflare R2.
After the npm package is installed, setup needs valid R2 credentials for the
current repo. The two simplest auth paths are:
Prompt-friendly auth path:
codex-handoff remote login r2 --from-clipboard
codex-handoff setupFile-based auth path:
codex-handoff remote login r2 --dotenv ./.codex-handoff/.env.local
codex-handoff setup- Set up one repo and start background sync.
Use a Codex prompt or run
codex-handoff setup. - Run a one-shot sync without relying on the background agent.
Use
codex-handoff sync now. - Inspect or rebuild repo context when you need to understand current handoff
state.
Use
codex-handoff status,codex-handoff sync status,codex-handoff resume, andcodex-handoff search. - Update the optional repo-level memory summary.
Use
codex-handoff memory summarize. - Stop managing the current repo without deleting its cached data.
Use
codex-handoff detach. - Remove local handoff files from
.codex-handoff/while keeping credentials. Usecodex-handoff purge-localandcodex-handoff purge-local --apply. - Delete one repo's remote backup from Cloudflare R2.
Use
codex-handoff remote purge-repo --repo-slug <slug>and add--applyto execute it. - Stop or disable the background service on this machine.
Use
codex-handoff agent stopandcodex-handoff agent disable.
The repo-local state is intentionally simple:
.codex-handoff/synced-threads/pulled thread payloads used for default restore reads, includingcurrent-thread.json,thread-index.json, andthreads/.codex-handoff/local-threads/local thread payloads prepared for push.codex-handoff/repo.jsonrepo-local control-plane state- optional derived files such as
.codex-handoff/memory.mdmanually generated repo memory artifacts that are not part of the default bootstrap read path. The current format keeps a stable repo summary near the top and appends timestamped conversation updates when new synced thread activity arrives.
For quick orientation, read .codex-handoff/memory.md first when it exists.
For detailed restore reads, stay inside .codex-handoff/synced-threads/:
start with current-thread.json, then use thread-index.json to decide which
specific bundle under threads/ to inspect next.
MIT