
claude-continuity
Zero-touch session rotation and supervision for Claude Code
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up claude-continuity (git-clone project) into my current project. Found on https://claudeers.com/claude-continuity Repo: https://github.com/pqant/claude-continuity Homepage/docs: — Detected install method: git-clone → git clone https://github.com/pqant/claude-continuity Category: other. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
git clone https://github.com/pqant/claude-continuity
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
cc-continuity
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 launchd watchdog 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.
How it works
The whole flow in one picture — the automatic session loop, the optional watchdog, and the opt-in notifications:

Requirements
- macOS (v1 — Linux/systemd is a documented seam, not yet implemented)
- Python ≥ 3.11 (standard library only at runtime)
- tmux, zsh, curl on PATH
- Claude Code ≥ 2.1.209
Quick start
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 green
From PyPI:
pip install cc-continuity
cc-continuity install
exec zsh
cc-continuity doctor
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.
Daily use
cd ~/anything
claude # auto-tmux, session named <project>-001
Watch 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.
Configuration
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.
Notifications (ntfy, opt-in)
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 off
cc-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.
Unattended mode (opt-in)
⚠️ 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 the declared safety valve, and 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.
When it blocks on you
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>"
Watchdog (opt-in)
A launchd daemon that keeps long runs recoverable: 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.
Security
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.
Limitations
See LIMITATIONS.md (an honest list).
Development
python3 -m pytest -q # unit + contract tests
Tests 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.
License
MIT — see LICENSE.
// faq
What is claude-continuity?
Zero-touch session rotation and supervision for Claude Code. It is open-source on GitHub.
Is claude-continuity free to use?
claude-continuity is open-source under the MIT license, so it is free to use.
What category does claude-continuity belong to?
claude-continuity is listed under other in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/claude-continuity)
// retro hit counter
[](https://claudeers.com/claude-continuity)
// reviews
// guestbook
// related in Other
Anti-AI-slop design skill for Claude Code, Cursor, and Codex.
Huashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 + 20 设计哲学 + 5 维评审 + MP4 导出 · Agent-agnostic
Open source Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents. Built for multitasking, organization, and programmability.