Zero-touch session rotation and supervision for Claude Code.
Why it exists. Long sessions die when the context window fills up, and local LLMs make it worse: their window is fixed and small, and the built-in compaction (/compact, auto-compact) is a lossy one-shot summary. With a small model it silently drops decisions, rejected approaches and the exact stopping point, and every compaction then summarizes a summary, so the drift compounds. cc-continuity exists to give long work room to breathe inside the window: at a safe threshold it rotates the session with a structured, validated handoff instead of a lossy summary.
The goal is to let an agent drive a planned project end-to-end, from 0 to done, with a human involved only when the agent is truly blocked. This repository is the proof of concept: it was developed with cc-continuity itself, and the full development history is in this git log.
cc-continuity watches the context ratio and, when it crosses a threshold, rotates the session with no user action:
- the agent finishes the current step,
- cc-continuity makes it write a validated handoff,
- the git tree is snapshotted non-invasively (
refs/continuity/*refs: no commits, no tags, no branches touched), - the context is cleared and the session renamed,
- a continuation prompt is injected and the successor session starts
with
Continuing from cp-<NNN> (<slug>-<NNN+1>).
An optional watchdog daemon keeps long unattended runs recoverable when the model server (for example a local vLLM box) dies or freezes, and optional ntfy pushes let you watch from your phone.
The five most recent updates, newest first. Each line links to its commit, so you can see what changed lately without digging through the log:
- 2026-11-19: A warned session no longer idles on its own handoff. After the c1 rotation warning the model could write its
handoff.draft.md, but drafts were only ever read in HANDOFF_REQUESTED, so the session waited at the prompt with a finished handoff on disk; the Stop hook now consumes a WARNED draft at turn end through the normal handoff path - a valid draft finalizes silently, an invalid one gets the usual guidance - and sessions that were never warned never rotate on a self-written draft (commit). - 2026-11-19: Two small observability wins for the push layer.
notify stop|notification --dry-runrenders the exact push (enabled state, title, priority and body) without sending anything or burning the one-push-per-minute bucket, andwatchdog statusnow ends with alast heartbeat: <local time> (<N>s ago)line so a stalled daemon is visible at a glance; a missing or corrupt stamp readslast heartbeat: never(commit). - 2026-11-18: The rotation gate can no longer invert silently.
doctorgained aconfig-sanitycheck that verifies0 < warn_ratio <= rotate_ratio <= hard_ratio < 1, a plausiblewindow_tokens(>= 32768) and an http(s)notify_endpoint, naming the offending values in its detail; a typo like warn 0.80 / rotate 0.75 used to make rotations fire late or never. The check is warn-only, the values stay the user's call (commit). - 2026-11-18: The session chain went machine-readable:
cc-continuity history --jsonprints it as one JSON array with stable keys (nnn,name,session_id,created,state). The state comes from each session'sstate.jsonwith the same fallback the status rotation line uses, a project without a record prints[], and the default human output is unchanged (commit). - 2026-11-17: The README now opens at a glance. A badges row sits under the title: live shields.io counters for forks, stars, open issues and the last commit (each links to the matching GitHub page), plus Code of conduct, Contributions and Security badges that lead straight into the community files (commit).
The whole flow in one picture: the automatic session loop, the optional watchdog, and the opt-in notifications:
A full recorded run: install → five chained sessions → four context
rotations → a completed task, captured end to end. It is a long,
video-style GIF, so it is offered as a download rather than embedded
in the page:
- demo-high-res.gif — 896x1920, 20 fps (~20 MB)
- demo-low-res.gif — 700x1500, 12 fps (~12 MB)
The demo itself is recorded by
tools/demo_gif.sh (it needs a local-model
endpoint in ANTHROPIC_* env); the cut list and the pipeline that
turned the recording into the GIFs are in
tools/demo_segments.txt and
tools/gif_from_video.sh.
- macOS, or Windows 10/11 with WSL (see Windows (via WSL))
- Python ≥ 3.11 (standard library only at runtime)
- tmux and curl on PATH; zsh on macOS (bash is fine on WSL)
- Claude Code ≥ 2.1.209
To verify your setup: cc-continuity doctor checks the Claude Code
version, and the WSL e2e script
(tools/e2e_wsl.sh) exercises the rotation/hook
path end to end.
cc-continuity runs inside a Windows Subsystem for Linux distro: the Linux side is unchanged — same rotation, same watchdog, same ntfy pushes — and only the daemon hosting differs. Where macOS uses launchd, the distro uses a detached tmux session (default) or systemd user units (WSL 2 with systemd enabled), plus one optional Windows logon task so the daemons come back when the WSL VM restarts.
- WSL 2 recommended; WSL 1 works too (minus the systemd option).
- Ubuntu 24.04 recommended; Ubuntu 22.04 works with
python3.11from deadsnakes. - Native Windows is out of scope — the distro is the runtime.
Full guide (requirements, install, watchdog, autostart,
troubleshooting): docs/WINDOWS.md. An end-to-end
test for the WSL install lives in tools/e2e_wsl.sh.
From Git:
git clone https://github.com/pqant/claude-continuity
cd claude-continuity
python3 -m cc_continuity.cli install --window 262144
exec zsh # reload the shell (claude() wrapper)
cc-continuity doctor # everything should be greenFrom PyPI (recommended: pipx, the standard way to install Python CLIs):
pipx install cc-continuity # or: uv tool install cc-continuity
cc-continuity install
exec zsh
cc-continuity doctorPlain pip install cc-continuity also works inside a venv or when
embedding it as a library; pipx/uv tool put the CLI on PATH without
touching your Python environment.
On Windows (WSL) the same steps run inside the distro (bash as the
login shell); the full WSL guide is docs/WINDOWS.md.
The installer touches (all as identifiable managed blocks, all reversible
via cc-continuity uninstall): hooks + status line in
~/.claude/settings.json, a managed block in ~/.claude/CLAUDE.md, the
claude() wrapper in ~/.zshrc, six /continuity-* skills, the
cc-continuity launcher on PATH, and the app copy in
~/.claude-continuity/app/. A timestamped backup of
settings.json is written before any merge.
cd ~/anything
claude # auto-tmux, session named <project>-001Watch the status line: the context ratio climbs (default thresholds
55% warn → 62% rotate → 72% hard ceiling). Rotation is zero-touch
(quick-start list above). After a crash, sleep, or reboot: just run
claude in the project and say "continue".
In-session commands: /continuity-status, /continuity-checkpoint,
/continuity-rotate, /continuity-off / /continuity-on,
/continuity-history. Full CLI reference: docs/USAGE.md.
Global: ~/.claude-continuity/config.json, start from
config.example.json (all keys, placeholder values). Per-project
override: .claude/continuity.json (e.g. {"enabled": false} to opt one
project out). CC_CONTINUITY=0 disables everything for one launch.
cc-continuity can push lifecycle events to any ntfy-compatible server, so you can watch long unattended runs from your phone:
cc-continuity configure --ntfy https://ntfy.sh/your-topic # or at install: --ntfy <url>
cc-continuity configure --ntfy offcc-continuity doctor sends a test message to verify the endpoint.
| Event | Title | Meaning |
|---|---|---|
| start | ▶ session started |
a session registered itself (first hook or resume claim) |
| warn | ⚠ context warning |
ratio crossed the warning threshold |
| pending | ◆ rotation pending |
ratio crossed the hard threshold; rotates at turn end |
| verified | ✓ handoff written & verified |
checkpoint finalized, sha256 verified |
| complete | 🔄 rotation complete |
the successor session is running |
| resumed | ↻ resumed |
successor consumed the checkpoint |
| blocked | 🛑 BLOCKED, waiting for you |
agent hit a needs-human point (urgent) |
| done | ✅ task complete |
agent finished the task you gave it |
| error | ✗ … failed |
a lifecycle step failed (urgent) |
| end | ■ session ended |
SessionEnd (rotation, /clear, or close) |
Privacy: a push is a title + a body of at most 200 characters
containing only the project slug, session number, context ratio, a short
reason/summary you control, and the hostname. No file contents, no
prompts, no secrets; recorded text is secret-redacted on the way out.
Messages only ever go to the endpoint YOU configure, and only when
notify_enabled is on.
⚠️ Loud warning:launch --unattended(orconfig.json: "unattended": truefor a whole project) spawns the session withclaude --dangerously-skip-permissions: the agent edits files and runs commands without per-action approval. Use it only on machines/projects you trust with that. Theneeds-humanmechanism (below) is a signal the agent sends, not a permission boundary: it enforces and blocks nothing. The default mode is unchanged; nothing skips permissions unless you opt in.
claude --unattended # via the zsh wrapper (one launch)
cc-continuity launch --unattended
cc-continuity configure --unattended # project setting (whole chain)Because a rotation is a /clear inside the same process, one flag (or
one project setting) carries the entire rotation chain: every successor
session stays unattended.
The agent signals you when it cannot safely continue (a destructive/irreversible operation, an ambiguous requirement, the same fix failing three times):
cc-continuity signal needs-human "<short reason>"That pushes an urgent notification and marks the status line
⛔ BLOCKED (machine-side truth, visible on any later attach). Remote
in to the pane, reply in the session; the block clears on your next
prompt. On completion the agent runs:
cc-continuity signal done "<one-line summary>"A daemon that keeps long runs recoverable (launchd on macOS; a tmux
session or systemd user unit on WSL): a health probe for
your model server (2-fail debounce), per-session liveness classification,
a bounded nudge state machine (the session is told WHY its turn stopped),
an exit-hang killer, frozen-turn escalation, and optional auto
power-cycle of the box + a log digest relayed into the active session.
Off by default; the health URL is yours to supply. Details:
docs/WATCHDOG.md.
Read SECURITY.md before installing. It states the trust model: what
code runs with your rights, what the installer merges and how it
uninstalls, and what data ever leaves the machine.
See LIMITATIONS.md (an honest list).
python3 -m pytest -q # unit + contract testsTests redirect all state through CC_CONTINUITY_HOME (a temp dir) and
use throwaway git repos; they never touch the real
~/.claude-continuity or ~/.claude. Architecture:
docs/ARCHITECTURE.md.
MIT, see LICENSE.

