Carry Keep context between coding-agent sessions

Keep can load a small index of recent project Notes when a coding session starts and save one Markdown handoff when it ends.

Install the full lifecycle

Install the Keep CLI and the model CLIs you use. Connect each client, then install its integration:

Pi’s current official npm package is @earendil-works/pi-coding-agent:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Run each model CLI once and make sure it can answer a prompt before enabling automatic handoffs. keep hooks doctor checks that the executable is present; it cannot verify a provider login or API key without making a model request.

keep login claude-code
keep login codex
keep login pi
keep hooks install all

Each client receives its own named Keep credential. Its name appears in Note history.

all installs Claude Code, Codex, and Pi because they support both session start and session end. Install one instead with keep hooks install claude-code, keep hooks install codex, or keep hooks install pi.

The installer asks for confirmation. Each non-empty completed session uses one additional request through the matching model CLI to prepare its handoff. Use --yes only after reviewing that access.

Keep preserves existing hooks and backs up an existing JSON configuration before changing it. It writes these integrations:

Run the install command again to repair a missing Keep hook. Existing Keep hooks are not duplicated.

Hooks installed by older Keep versions under claude continue to work as Claude Code. They are never treated as Claude Desktop hooks.

Install the Cursor preview

Cursor currently offers a local start hook, but its IDE can drop the returned context and it does not provide a dependable end hook. Install the preview with:

keep login cursor
keep hooks install cursor

Keep writes a native sessionStart entry to ~/.cursor/hooks.json. Use keep session prompt --client cursor when you want the current agent to save a handoff manually.

Install the OpenCode handoff command

OpenCode does not currently expose a true session-close event. Its session.idle event means a response is ready, not that the session ended. Keep therefore installs an explicit command instead of treating every idle response as a handoff:

npm install -g opencode-ai
keep login opencode
keep hooks install opencode

This writes ~/.config/opencode/commands/keep-handoff.md. Run /keep-handoff in OpenCode when the session has useful work to preserve. The installer adds the command globally, but it does not run the command for you.

Check the installation

Run these commands:

keep hooks status
keep hooks doctor

keep hooks status checks the managed integration and Keep authentication. keep hooks doctor also checks the required model CLI and version. Add a client name to check only that client.

What happens at session start

The start integration detects the Git remote and current directory. It asks Keep for at most 20 matching Note titles and retrieval cues.

Claude Code and Codex return that index from their SessionStart hook. Pi fetches it on session_start, then injects it privately on before_agent_start. Cursor returns it as additional_context from its local sessionStart preview, subject to the Cursor IDE limitation noted above.

It does not load Note bodies, make a model request, or write to Keep. It stays quiet outside a Git project, when there are no matching Notes, or when Keep is temporarily unavailable. The agent can use Keep search to open the Notes that matter.

What happens at session end

The end integration checks that the session contains user work, queues a local summary job, and returns without waiting. The matching model CLI prepares one Markdown Note with decisions, completed work, changed files, checks, failures, and remaining work.

Keep never uploads the raw transcript. It saves only the generated Markdown summary. A stable session ID prevents duplicate Notes when an event repeats or a failed job is retried. Empty sessions are skipped, and a generated summary that appears to contain a credential stays local.

Check and retry summary jobs

keep session status
keep session status <job-id>

The command shows each job as pending, running, saved, skipped, or failed. A saved job includes the Keep Note URL. A failed job includes its error.

Retry a failed summary

1. Run keep session status.
2. Copy the failed job ID.
3. Fix the reported authentication or model CLI problem.
4. Run the retry command.

keep session retry <job-id>

Prepare a handoff manually

keep session prompt
keep session prompt --client <name>
keep session prompt --json

The command prints the summary instructions and write contract for the current agent. It does not save a Note by itself.

Remove an integration

keep hooks remove all
keep hooks remove cursor
keep hooks remove opencode

all removes the Claude Code, Codex, and Pi integrations. A targeted remove deletes only Keep’s managed entries or file and leaves unrelated configuration alone.

Session integrations are separate from Keep MCP. You can connect MCP for normal library access without installing session hooks.