claudeers.
// Other

claude-continuity

Zero-touch session rotation and supervision for Claude Code

// Other[ cli ][ api ][ claude ]#claude#other◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
100/100
last commit 2 days ago
last release 2 days ago
releases 53
open issues 4
// star history

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.
// or clone
git clone https://github.com/pqant/claude-continuity

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

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:

  1. the agent finishes the current step,
  2. cc-continuity makes it write a validated handoff,
  3. the git tree is snapshotted non-invasively (refs/continuity/* refs — no commits, no tags, no branches touched),
  4. the context is cleared and the session renamed,
  5. 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:

cc-continuity flow: session loop, watchdog, 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.

EventTitleMeaning
start▶ session starteda session registered itself (first hook or resume claim)
warn⚠ context warningratio crossed the warning threshold
pending◆ rotation pendingratio crossed the hard threshold; rotates at turn end
verified✓ handoff written & verifiedcheckpoint finalized, sha256 verified
complete🔄 rotation completethe successor session is running
resumed↻ resumedsuccessor consumed the checkpoint
blocked🛑 BLOCKED — waiting for youagent hit a needs-human point (urgent)
done✅ task completeagent finished the task you gave it
error✗ … faileda lifecycle step failed (urgent)
end■ session endedSessionEnd (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 (or config.json: "unattended": true for a whole project) spawns the session with claude --dangerously-skip-permissions: the agent edits files and runs commands without per-action approval. Use it only on machines/projects you trust with that. The needs-human mechanism (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.

7 views
★ 27 stars
unclaimed
updated about 1 month ago

// embed badge

claude-continuity on Claudeers
[![Claudeers](https://claudeers.com/api/badge/claude-continuity.svg)](https://claudeers.com/claude-continuity)

// retro hit counter

claude-continuity hit counter
[![Hits](https://claudeers.com/api/counter/claude-continuity.svg)](https://claudeers.com/claude-continuity)

// reviews

// guestbook

0/500

// related in Other

🔓

符合nature论文学术表达和科研绘图的Skill

// otherYuan1z0825/⟨Python⟩★ 54,085◷ Apache-2.0[ claude ]
🔓

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

// otherNutlope/⟨CSS⟩★ 49,642◷ MIT[ claude ]
🔓

Huashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 + 20 设计哲学 + 5 维评审 + MP4 导出 · Agent-agnostic

// otheralchaincyf/⟨HTML⟩★ 28,944◷ MIT[ claude ]
🔓

Open source Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents. Built for multitasking, organization, and programmability.

// othermanaflow-ai/⟨Swift⟩★ 28,842◷ NOASSERTION[ claude ]
→ see how claude-continuity connects across the ecosystem