ctx-handoff Claude Code mod: make Claude Code long sessions easier

ctx-handoff is a community mod by CabLate (cablate) for Claude Code long sessions. It bundles several chores that come up when a conversation runs for hours: it sends a tiny request while you are away so the prompt cache does not expire, it turns your repeated instructions into per-project notes that are loaded into new conversations, and it nudges Claude when it retries a failing tool or says "done" without running a check.

Two bigger features are less automatic. An optional handoff writes a summary of the work, clears the conversation and continues in a fresh one when the context reaches a threshold; it is off by default. Guards are tool-call checks the mod drafts from rules you keep repeating, and they only apply after you approve them. A panel above the prompt (/handoff panel) lists guards, memories, rules, the latest notes update and every setting.

The author's README targets Claude subscriptions and long, large-context sessions. On an API key, Bedrock or Vertex the cache lasts five minutes, so the author suggests /handoff refresh off.

The recording starts Claude Code with the mod loaded in the small demo project. The footer immediately shows ctx-handoff: 30 more messages until notes update, the countdown to the next background notes update. The clip then runs /handoff guard, which prints Guards: none with the conditions under which guards get drafted, and /handoff refresh, which prints Currently on. Usage: /handoff refresh on|off. No model request is made in the clip, and it does not open the panel because the panel shows the full path of the notes file.

Use any of the methods in the install block; they install straight from the author's own marketplace. Start a new session and run /handoff. The footer countdown appears once the session starts.

Everything is registered from one module, hooks/register.ts. Each finished turn restarts an idle timer. When it fires, and the context is above min_tokens, the mod sends a minimal fork request to read the cached conversation and then schedules the next one. This is the scheduling function, from hooks/register.ts:

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

By default the idle time is 50 minutes and at most 3 refreshes run, after which an away handoff is saved without clearing. Every 30 user messages, or before a handoff, a separate request without history sends only the new part of the conversation to a notes model (claude-sonnet-5-5, low effort). Its JSON actions are validated in code, user quotes must be found in your actual messages, and lines that look like secrets are dropped before anything is written. The notes are injected into new conversations through prompt.context.

The mod declares no userConfig. Settings live on the panel's Settings tab (/handoff panel, then key 5), and the mod also reads pluginConfigs["ctx-handoff@<marketplace>"].options from settings.json; the panel value wins. The settings include auto_handoff (default off), threshold (600000 tokens), idle_minutes (50), max_refresh (3), min_tokens (30000), distill_every (30), notes_model, retry_nudge, done_check, reply_language and language. Slash commands cover the rest: /handoff now, dry, distill on|off, refresh on|off, away pause|resume, guard, resume, continue and resend.

We read the manifest, hooks/hooks.json, hooks/register.ts in full, and the modules for settings, notes, handoff, guards, loops, language, promotion and the distill prompt. The remaining files, mostly the i18n strings, the panel view and small record helpers, were checked for side effects with searches rather than read line by line. The repo has no package.json, install script, binary or minified code. tools/ holds author-side scripts that the plugin does not load, and we did not run them. There are no hidden Unicode characters.

Findings you should know about:

• Model requests, no other network. There is no fetch, process call or network code. The mod calls $.model.fork and $.model.complete, which use your Claude quota. Conversation text is sent for notes and handoff summaries, the same way the conversation itself is.
• Writes outside its own store. $.fs.write creates and updates <claude config dir>/projects/<workspace>/memory/ctx-handoff.md, and writes a backup in .ctx-handoff-backup/ before deleting a note from the panel. Background notes updates are on by default, but they are skipped when the session starts in your home folder. It does not touch settings.json, shell files or LaunchAgents, and it reads HOME, USERPROFILE and CLAUDE_CONFIG_DIR.
• It injects text into the model. prompt.context adds your notes, an optional progress memo and guard questions to new conversations, tagged [ctx-handoff]. Tool results can carry nudges. Once a rule has been repeated 3 times in a git repo, the injected text tells Claude to write it into the repo (CLAUDE.md, .claude/skills, hooks) without asking first, but not to commit. The notes are model-written summaries of your conversations, so check the file now and then.
• Gating hooks. tool.call can deny a call only for a guard you approved. classic.Stop can block one "done" answer per turn when files were edited and no check ran (done_check, on by default). prompt.submit holds your messages while a handoff is running. If you turn auto handoff on, the mod runs /clear and submits the summary itself.
• No daemon, no telemetry. Timers live only in the Claude Code process. Usage statistics stay in the plugin's store.
• Managed setups. claude plugin validate notes that prompt.context and classic.Stop hooks do not run in a user-installed plugin where an organization manages Claude Code.
• License. MIT, with a LICENSE file.

claude plugin validate reported no errors. Its only warning is that the CLAUDE.md at the repo root is not loaded as plugin context. The author's 290 tests across 15 files passed on Claude Code 2.1.303.

Checked with Claude Code 2.1.303 on macOS (validate, tests and the recording). The author's README requires 2.1.287 or later. If /handoff does nothing:

• claude --version is 2.1.287 or later, and you started a new session after installing.
• Another /handoff command may exist; the mod then registers /ctx-handoff instead.
• The footer countdown is absent when notes updates are off or when you started Claude Code in your home folder.
• Cache refreshes help only where the cache lasts an hour, so turn them off with /handoff refresh off on API keys.
• Run /handoff for the current state, including the latest failure and the path of the notes file.