Connect Claude Code and Codex before the session you want to hand off

Decide what this server may store before enabling capture. The capture settings say Claude Code prompts are stored by default; --no-capture-prompts is an installation option, while ignore_paths is a lexical file-tool exclusion, not a general secret filter. The project's security guide allows no-auth loopback for a single-user laptop. Enable authentication when untrusted local processes share the machine, the stored history is sensitive, or the server binds beyond loopback. For LAN or remote access, use an HTTPS reverse proxy; authentication alone does not encrypt tokens. The maintainer recommends HTTPS for multi-user setups too.

Install ai-memory using the instructions for your operating system before running the commands below. For the native macOS setup, they assume the binary is on your PATH. In one terminal, initialise its data directory once and leave the loopback server running:

ai-memory init
ai-memory serve --transport http --bind 127.0.0.1:49374

In a second terminal, confirm that server responds before installing the integrations. The documented GET check returns 405 because the MCP endpoint does not accept GET. A connection error means the server is not reachable at that address.

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:49374/mcp
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
ai-memory install-mcp --client codex --apply
ai-memory install-hooks --agent codex --apply

Run the installers where you launch each CLI. MCP gives the agents ai-memory tools; hooks capture session events and deliver the pending handoff at the next session start. Both integrations are documented for Claude Code and Codex CLI in the support matrix. On native macOS, ai-memory versions before 1.39.0 may fail to find the hooks bundle when install-hooks runs through a symlink on PATH; use the extracted binary directly or upgrade if you hit that error, as the installation guide explains.

Start a fresh Claude Code session after wiring the hooks. Confirm it can call memory_status, note the observation total from ai-memory status, then check the total again after a substantive Claude turn. A higher total is a capture signal, though a shared server may include other sessions. A nonzero total by itself could be old data and does not prove a handoff exists.

End the Claude Code session with a useful handoff

In the maintainer's example, Claude Code is investigating broken JWT rotation and considering session cookies. That alternative is a proposal, not a code change. Before leaving Claude, record the checkout path and inspect both unstaged and staged changes:

pwd -P
git rev-parse --show-toplevel
git status --short
git diff --stat
git diff --cached --stat

If an attempted fix or decision would be hard to recover from captured events, ask Claude Code to create an explicit handoff with memory_handoff_begin. Include what it actually tried, the observed result, changed files, and the question for Codex. A manual handoff takes precedence over an automatic one. Merely asking Claude for a final prose summary is less reliable because assistant Stop text is not captured by default.

The installers above create static MCP connections, which cannot attach the current hook session ID to a tool call. The ai-memory scope rule says to pass exact workspace and project names on project-scoped calls. Find them in the nearest .ai-memory.toml or the operator's server configuration, then replace the two placeholders below. An unscoped call can reach the wrong project when several projects use the server; do not guess the names from the checkout directory.

Create a manual ai-memory handoff for Codex. Call memory_handoff_begin with workspace=YOUR_WORKSPACE and project=YOUR_PROJECT. State the JWT-rotation bug, what we actually tried and observed, which files changed here, whether the session-cookie idea is still untested, and the next decision Codex should make. If no fix was attempted, say so. Show me the handoff ID before I leave.

For the automatic route, leave an ordinary Claude Code CLI session with /exit; its SessionEnd hook is the relevant boundary. Merely switching windows does not make a session-end handoff. There is a narrower case in Claude's command documentation: /exit in an attached background session detaches while that session keeps running. If that is how you work, use a deliberate manual handoff or confirm that the session actually ended. Hooks can also fail; do not treat an issued /exit command as proof that Codex received anything.

Four-step diagram: Claude session ends, ai-memory stores a handoff, Codex starts, and Codex checks repository state
The automatic handoff depends on a completed session-end and a matching receiving session. Credit: Original Grow AI Skills editorial diagram. Open full-size image.

Start Codex in the intended checkout and reconcile the evidence

cd /path/to/your/repo
codex

Use the same absolute checkout path you recorded in Claude Code. ai-memory's automatic handoff is matched to the receiving directory by path boundary, while Codex CLI reads the working tree from its launch directory. A second Git worktree is not the same set of files: OpenAI's worktree guide describes worktrees as separate checkouts with shared Git history. Even if memory routes relevant context to a different worktree, uncommitted edits in the first checkout do not appear in the second one.

On the new Codex session's first turn, ask it to identify the received handoff and reconcile it with the repository:

State the ai-memory handoff you received, including its source task and open question. If none appeared, tell me before editing. Run pwd -P and git status --short; inspect unstaged and staged diffs and any untracked task files. Separate Claude Code's proposals from changes actually present here, and identify relevant tests that still need to run.

For the JWT example, Codex should identify the broken rotation task and the still-open session-cookie question, then report only code changes that the checkout actually contains. If it claims the cookie approach was implemented but Git shows no such change, stop before editing.

If no handoff appears, find where the chain broke

If Codex has no handoff block, check the link that could have failed. A 405 from the GET check only shows that the server responds. Compare ai-memory status before and after the Claude turn; an old nonzero total is inconclusive. Confirm that the Claude session actually ended: a lifecycle-only session may create no handoff, and /exit can merely detach an attached background session. If you installed hooks after a CLI was already open, start a new session so its startup hook can run. If Codex cannot call memory_status, check its MCP installation.

If no block appeared but MCP works, ask Codex to call memory_handoff_list with the configured workspace and project pair. Listing does not consume a pending record. Check each ID's source and open question before using memory_handoff_accept, which claims the chosen ID once. Pass the same scope pair when accepting or cancelling a handoff.

Automatic handoffs match the receiving directory by path boundary, while manual handoffs are project-wide and take priority. Handoffs are owner-private on a multi-user server unless deliberately shared. A pending record for another operator or an unrelated checkout therefore may not be available to this session. These are the project's routing rules.

If Codex did receive the wrong task, do not act on the injected note. Check its ID and source against the Claude task and checkout before editing. An old manual handoff can outrank the automatic one. If that manual record is still pending, cancel its exact ID with memory_handoff_cancel before starting another Codex session; cancellation cannot undo a handoff already claimed at startup. In that case, have Claude create a correct manual handoff and start a fresh Codex session. The usage guide documents claim-once acceptance and cancellation of open handoffs.

Diagnostic diagram distinguishing server reachability, new Claude observations, receipt in a fresh Codex session, and checkout verification
A reachable server and old observations do not prove Codex received the right handoff. Credit: Original Grow AI Skills editorial diagram. Open full-size image.

Choose a short handoff or a managed workstream

For one switch, direct claude and codex launches with hooks provide the shorter session-end handoff. If Codex needs a more detailed trail of visible messages and completed tool calls, the opt-in managed-workstream route is different:

cd /path/to/your/repo
ai-memory run claude
# Finish the Claude Code workstream, then:
ai-memory run codex

The launcher can wire missing hooks or MCP connections and carry a bounded ledger of visible messages and completed tool calls into Codex; hidden reasoning is excluded. If Claude has already established a managed workstream, switching to Codex starts a fresh native Codex session with that portable context. Returning to Codex later resumes its linked session. An otherwise empty managed workstream can also interactively adopt a matching native session from the same checkout. For older material beyond the bounded transfer, use ai-memory workstream-search from inside the managed session. The current checkout remains the source of truth for file changes. These limits are specified in the managed-workstream guide.