--- title: "Keep session hooks for coding agents | Keep" description: "Connect Keep to Claude Code, Codex, Pi, Cursor, and OpenCode sessions." canonical: "https://keep.md/docs/session-hooks" language: "en" --- # Carry Keep context between coding-agent sessions Connect Keep to Claude Code, Codex, Pi, Cursor, and OpenCode sessions. Keep can load a small index of recent project Notes when a coding session starts and save one Markdown handoff when it ends. This is an optional advanced workflow. Normal Keep setup does not install session hooks. Existing hook installations continue to work. | Client | Start context | Session handoff | | --- | --- | --- | | Claude Code | Automatic | Automatic | | Codex | Automatic | Automatic | | Pi | Automatic | Automatic | | Cursor local | Start-only preview | Use `keep session prompt` | | OpenCode | Use Keep MCP or the Keep skill | Run `/keep-handoff` | ## Install the optional lifecycle Install the [Keep CLI](https://keep.md/docs/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: | Client | Location | Start event | End event | | --- | --- | --- | --- | | Claude Code | `~/.claude/settings.json` | `SessionStart` | `SessionEnd` | | Codex | `~/.codex/hooks.json` | `SessionStart` | `SessionEnd` | | Pi | `~/.pi/agent/extensions/keep.js` | `session_start`, then `before_agent_start` | `session_shutdown` | 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](https://keep.md/docs/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 ``` 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 ``` ## Prepare a handoff manually ``` keep session prompt keep session prompt --client 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](https://keep.md/docs/mcp). You can connect MCP for normal library access without installing session hooks.