Add Keep to Claude Code and Codex sessions

Keep session hooks support Claude Code and Codex. The start hook shows the agent a small index of recent project Notes. The end hook saves one Markdown session summary after non-empty sessions.

Prepare each client

Install the Keep CLI. Make sure the Claude Code or Codex CLI is also installed.

Connect each client that will use the hooks:

keep auth add claude
keep auth add codex

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

Install the hooks

Install hooks for both supported clients:

keep hooks install all

Install hooks for one client instead:

keep hooks install claude
keep hooks install codex

The installer asks for confirmation. The session end hook runs one additional request through the matching model CLI for each non-empty completed session. Use --yes for a non-interactive install after you have reviewed this access.

Keep preserves existing hooks. It creates a backup before it changes an existing hook configuration.

The Claude Code hooks are stored in ~/.claude/settings.json. The Codex hooks are stored in ~/.codex/hooks.json. Run the install command again to add a missing Keep hook. Existing Keep hooks are not duplicated.

Check the installation

Run these commands:

keep hooks status
keep hooks doctor

keep hooks status checks the hook configuration and Keep authentication. keep hooks doctor also checks that each model CLI is available.

Add claude or codex after either command to check one client.

What happens at session start

The start hook detects the Git remote and current directory. It asks Keep for a maximum of 20 matching Note titles and retrieval cues.

The hook does not load Note bodies. It does not make a model request. It does not write to Keep.

The hook stays quiet in these cases:

• the current directory is not a Git project
• Keep finds no matching Notes
• Keep is temporarily unavailable

The agent can use Keep search to open the Notes that matter.

What happens at session end

The end hook checks that the session contains user work. It then queues a local summary job and returns without waiting for the summary.

The matching model CLI prepares one Markdown Note. The summary can include decisions, completed work, changed files, checks, failures, and remaining work. Keep saves it with project context and a client tag.

Keep does not upload the raw transcript to Keep. It saves only the generated Markdown summary.

A stable session ID limits a completed session to one Note. Running the hook again or retrying a failed job does not create another Note for the same session.

Keep skips an empty session. It also keeps a generated summary local if it appears to contain a credential.

Check summary jobs

List recent jobs with:

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.

Check one job with:

keep session status <job-id>

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>

The retry uses the same session ID and request ID.

Prepare a summary without hooks

Print the session summary instructions with:

keep session prompt

This command does not save a Note. It returns a prompt and a write contract for the current agent.

Use JSON output when another tool needs the contract:

keep session prompt --json

Remove the hooks

Remove Keep hooks from both clients:

keep hooks remove all

Remove hooks from one client instead:

keep hooks remove claude
keep hooks remove codex

The command removes only Keep's SessionStart and SessionEnd entries. It leaves other hooks in the configuration.