cc-lhc

cc-lhc is the production Claude Code host for Long Horizon Context. It wraps the closed claude CLI (in a PTY for interactive sessions, as a plain child process for -p one-shots), captures Claude's rollout JSONL into an LHC thread, runs derivation inference through isolated claude -p subprocesses, and rebuilds Claude's session when the served thread view changes — swapping the child mid-session for an interactive launch, and running Smart Compact before launch for a one-shot.

The integration was certified on 2026-08-10 against Claude Code 2.1.226. See test/fixtures/slice7-certification-evidence.md for the retained acceptance record.

Supported platforms are the six native targets in ../cc-lhc-native/targets.json — Linux, macOS, and Windows on x64 and arm64. Exact process identity (ownership/liveness) comes from the cc-lhc-native addon, delivered as prebuilt artifacts. The native-platforms GitHub workflow is required to build the addon and run this package's full suite with the compiled addon mandatory on every target. The six-target matrix and compiler-free package installation passed before the 0.1.0 package was prepared. The whole-product interactive certification above was performed on Linux, with subsequent Windows and macOS dogfood findings incorporated before the package build.

Install

Prerequisites are Node 24.3 or later and an installed, authenticated Claude Code CLI.

Install on Linux or macOS from the checksum-verified GitHub release:

curl -fsSL https://github.com/liminal-ai/long-horizon-context/releases/download/cc-lhc-v0.4.4/install.sh | sh

Install on Windows from PowerShell:

irm https://github.com/liminal-ai/long-horizon-context/releases/download/cc-lhc-v0.4.4/install.ps1 | iex

The installers detect x64 or ARM64, download the matching complete runtime bundle, and verify its SHA-256 before installation. The bundle includes all JavaScript dependencies, the target PTY runtime, and the native identity addon. The client does not invoke npm or a compiler. Node 24.3 or later and an authenticated Claude Code CLI remain prerequisites.

The ordinary npm installation remains available:

npm install --global cc-lhc
cc-lhc --lhc-help

The package includes prebuilt native identity addons for all supported targets. A supported client does not need a C++ compiler or node-gyp.

Upgrading and rolling back

Upgrade by re-running the installer or npm install --global cc-lhc@<version>. Records, threads and configuration are kept, and sessions already running stay on their old version until they exit. Use one install method per machine. What changed in each version, and anything to do before upgrading, is in docs/releases/.

Rolling back from 0.4.3 or later to 0.4.2 needs one extra step. 0.4.3 records a rebuilt session as not yet accepted before writing it, and 0.4.2 ignores that record, so after an interrupted Smart Compact a 0.4.2 launch can switch the thread onto the unused rebuild. After switching back to 0.4.2, run once (Python 3; a release asset, and scripts/rollback-unaccepted.py in the source):

python3 rollback-unaccepted.py           # dry run
python3 rollback-unaccepted.py --apply

It removes the unaccepted records, moves their transcripts to ~/.cc-lhc/abandoned-rebuilds/, and skips threads whose session is still running. It honours CC_LHC_HOME and CLAUDE_CONFIG_DIR.

Start and help

cc-lhc [cc-lhc flags] [claude args...]
cc-lhc [cc-lhc flags] -- [claude args...]
cc-lhc --lhc-help
cc-lhc --lhc-version

The documented subcommands are reserved by the wrapper. Ordinary Claude arguments, including --help and --version, are forwarded after safe session-selector normalization; --lhc-version reports the CC-LHC package version and its stamped source identity without launching Claude. Everything after the first standalone -- is forwarded unchanged, even --lhc-* lookalikes. Unknown --lhc-* flags before -- exit with status 2. CC_LHC_CLAUDE_BIN overrides the child binary. State defaults to ~/.cc-lhc; CC_LHC_HOME overrides it.

What is integrated

• Canonical capture. A versioned rollout parser maps recognized conversational records into the append-only LHC record. Harmless host metadata is counted as telemetry; only classified integrity failures mark capture degraded.

• Stable identity. Assistant model identity is frozen from the response record. Thinking signatures are opaque; empty-but-signed thinking is preserved in the canonical record and replayed verbatim (signature intact) in the rebuilt tail, so Claude keeps its recent reasoning after a Smart Compact. Unsigned thinking is dropped, never given an invented signature.

• Canonical segments. One long native turn is closed into bounded canonical segments as it runs: at a tool-result line with no call outstanding once the SDK's open-turn estimate reaches half the full-fidelity share of the active lower target, and always at the assistant's terminal line. Segments are bookkeeping in the record only; the native turn, its lifecycle and the running Claude process are untouched. Already-recorded turns are not re-segmented. A single atomic exchange may exceed the soft size.

• Retrieval. Claude can invoke get-turns and get-messages through Bash. A wrapper-owned runtime descriptor binds each invocation to the exact live session and LHC thread. Stale ownership, malformed state, and session mismatch fail closed before archive access or impression writes. When the served view leaves out older turns, it says so with a turns tA–tB not in view; use get-turns line, so Claude retrieves them instead of assuming they never happened.

• Capability-limited context governance (LIM-64). Provider-reported input usage is authoritative and includes input + cache creation + cache read. Predicted next-request pressure adds a source-labelled estimate for content captured after that provider request (never double-counted as provider usage). Missing or invalid latest usage falls back to the last known provider reading plus that estimate, labelled last_known so an older measurement is never read as fresh — a session at 900k does not become healthy because one usage line went bad. One thing decides an automatic Smart Compact: measured pressure against the trigger. Capture health, descriptor readiness, receipt storage, and typed-ahead input are diagnostics and have no say, and nothing turns Smart Compact off. Classification uses explicit named states and durable receipts. Threshold crossing during an open agentic turn is observed and receipted but not mutated mid-turn — Claude Code cannot replace the in-flight request the way Codex full continuation can. At the next Claude-safe settled seam, policy may run Smart Compact and the wrapper-owned spawn-first handoff below. A Claude native Compact summary is captured as one bounded closed turn and reported loudly; nothing latches and LHC compaction continues. Capture that is degraded or still catching up does not block the seam: the wrapper rebuilds capture state from the persisted transcript and re-evaluates the moment it is ready. Built-in policy targets 180k, triggers at 360k, reserves 50k runway, and leaves automatic prune off.

• Forward-only construction. The settled seam is read once, before any SDK work, and never re-read: input arriving, a turn opening, or capture changing generation appends to a thread whose settled history the snapshot already holds, so none of them can cancel a Smart Compact that is under way. The rebuilt rollout is written under bounded retries from the durable installed view. From the moment Smart Compact owns the settled session, bytes bound for Claude are dropped rather than delivered — never buffered, never replayed — and one line says input typed during compaction was not delivered — please resend.

• Background work is carried across Smart Compact. A swap replaces the Claude child; work that child started asynchronously is carried into the replacement rather than killed:

  • Background shell commands keep running as their own processes, and their results are delivered on the next prompt.
  • Workflows and a pending ScheduleWakeup continue from a manifest in the rebuilt rollout.
  • Monitors are relaunched by the wrapper. Their events are delivered once each on the next prompt, they stay the same process through later compactions, and they are stopped when the session ends. A monitor that cannot be relaunched is recorded as failed.
  • A background agent runs inside the old Claude process and cannot survive the swap. On the next prompt cc-lhc reports its final result if it had finished; otherwise it tells Claude the agent was interrupted and can be resumed with SendMessage(<id>).

  The wrapper derives the open set from the rollout it already reads: a launch acknowledgement opens an item, and only matching terminal evidence (completed, failed, killed, stopped, or an explicit TaskStop) closes it. If an open item has no way to be carried, that seam is skipped and the current session kept.

• A too-long rejection continues once. If the API rejects a turn as too long (for example many PDF pages read as images in one turn), cc-lhc compacts at the next settled seam and then sends one message marked [runtime note], asking Claude to continue and naming the tool calls that already ran. Input typed in that moment is dropped with the usual resend notice. A second rejection stops with a note to split the task. One-shots never auto-continue.

• Spawn-first handoff. On an interactive launch, Smart Compact/prune rebuild a new rollout, then spawn claude --resume <new-id> off-route — a real child owning no terminal, no stdin, and no capture generation. Once it has proven observable viability (it rendered and survived a stabilization window; session-file growth is recorded when it appears and never required), input routing, output routing, the retrieval descriptor, and the capture generation switch in one step, and later old-child output is ignored. The old child is killed last, best effort, and a survivor is left running and named loudly by PID. A working session exists at every moment and nothing ever rolls back to the oversized one. This is not same-agentic-turn continuation: there is no synthetic tool-tail preservation and no Codex parity claim.

• One-shot seats run Smart Compact before they launch. A one-shot seat (cc-lhc --resume <id> -p <prompt>) is one prompt and an exit, so it runs Smart Compact at the start of the next invocation, before any Claude process exists. The wrapper reads the last authoritative provider count from the persisted transcript — catching LHC up from that file first when capture is stale — adds a source-labelled estimate of the prompt it is about to send, and, over the trigger, runs Smart Compact and writes the rebuilt session before launching Claude once on it with the original prompt. Smart Compact needs a settled snapshot LHC actually holds: capture that has not reached ready inside the catch-up bound, and a transcript left mid-turn by a previous invocation, both stand the seam down — the prompt launches on the resumed session with capture still catching up behind it, and the next invocation runs Smart Compact. The thread's current session advances only once the rebuilt session is observed accepting the prompt, and the wrapper settles that acceptance before handing the thread lease back; a launch that fails before then keeps the old pointer, and nothing is ever resent automatically. A turn that grows past the trigger while it runs finishes and the next invocation runs Smart Compact.

  A one-shot runs Claude as a plain child process, not in a PTY. Claude inherits the wrapper's stdin, stdout and stderr, so the reply, exit code, --output-format json/stream-json and piped stdin behave as with claude -p, including Claude's own ~3 second wait and warning when stdin is a pipe that sends nothing (add < /dev/null). cc-lhc's own lines go to stderr. Claude is tied to the wrapper's lifetime: on Linux through setpriv --pdeathsig, elsewhere through a watchdog; on Windows the whole process tree is closed with taskkill /T /F. A second one-shot on a thread that is already running exits 2 without queuing.

• When replacements repeatedly will not run. Each nonviable swap costs the session nothing and is retried at the next settled seam. After a bounded number of them, two things happen instead of another quiet retry, and both persist: a standing alarm — cc-lhc rebuilt sessions are not loading — likely a compatibility problem with the installed Claude version — and a survival relaunch of the old session without the injected DISABLE_AUTO_COMPACT, so Claude native Compact can keep it alive in degraded form. The alarm is cc-lhc's best guess from observable viability, not proof Claude rejected the file; the terminal is never parsed to find out. Nothing ends: the old session stays live and captured, retrieval keeps working, and manual Smart Compact still runs — only the automatic swap stops.

• Runtime continuity. Wrapper-owned handoffs preserve the latest confirmed Claude effort and permission mode from the rollout. Unknown values are not inferred, and permissions are never broadened by guesswork.

• Single ownership per thread. Launch resolves the host-qualified session alias (claude-code:<uuid>) through the LHC registry to a thread, takes a process-identity lease on that thread, and re-reads the thread's current alias under the lease before choosing a session. Every alias of one thread contends for one lease, so two wrappers can never both drive it — including across PID reuse. A launch through an older alias resolves forward onto the thread's current session. An accepted swap whose registry pointer could not be written is recorded host-side with the pointer it observed, and reconciled into the registry at the next launch under the lease — repairing only that exact predecessor, so a later successful acceptance is never rolled back.

Recovery after a crash or kill

• Killed during Smart Compact. The rebuilt session is recorded against its thread as not yet accepted before its transcript is written. If the whole process tree dies before the switch, the next launch (-c or --resume) returns to the thread's accepted session and moves the unused rebuild to ~/.cc-lhc/abandoned-rebuilds/.
• Orphans from 0.4.2 or earlier have no such record and are not linked by guesswork. The launch prints cc-lhc --resume (the picker) and lists threads that share text with the orphan as unverified possible matches. A one-shot prints this on stderr and exits 2 before starting Claude.
• Torn last transcript line. Before resuming, cc-lhc checks the session file's last line. An incomplete fragment is saved under ~/.cc-lhc/torn-lines/ and trimmed; a complete record missing only its newline gets the newline. This runs only when no other process has the file open (checked through /proc on Linux, lsof on macOS, and the Restart Manager plus an exclusive-open probe on Windows); when the check cannot prove the file unheld, the file is left alone. The live watcher waits on an incomplete last line rather than stopping capture. Corruption earlier in the file still stops capture for that session.
• Stale runtime files. Launch removes runtime descriptors whose owning process is gone.
• Interrupted background summaries. A process that exits cleanly hands its unfinished summary work back; work left by a crash or kill is retried by the next process, and a second crash on the same item marks it failed (claim_expired_repeatedly, with a warning in the thread log).

Retrieval and migration commands

cc-lhc get-turns [--from TOKENS] <tN>...
cc-lhc get-messages [--from TOKENS] <mN>...
cc-lhc backfill-labels <thread-id-or-prefix> [--dry-run]
cc-lhc rollout write --thread-id ID --session-id UUID [--cwd DIR] [--projects-root DIR] [--envelope-from ROLLOUT]

Retrieval is model-callable and uses the inherited CC_LHC_RUNTIME_DESCRIPTOR; users should not set it manually. The service computes a whole-stdout ceiling of at most 24,000 bytes, reserves envelope overhead, and gives the remainder to the SDK as its byte budget. This keeps the complete recalled-history envelope within Claude's certified inline-output limit. Continuation receipts provide the next token offset.

backfill-labels is an operator command. It recomposes legacy stored turn_rendering derivations with stable <tN>/<mN> labels for one explicit thread. It does not use inference, alter canonical events, queue work, or change source versions; --dry-run reports the planned changes.

rollout write is the fork entry point (lhc thread fork --host cc-lhc first, then this). It writes the thread's served view as a Claude Code rollout under a fresh session id (~/.claude/projects/<cwd>/<uuid>.jsonl, cwd from the registry unless --cwd), records the replayed-prefix lineage so the first cc-lhc --resume <uuid> skips it instead of re-intaking it, and makes the session the thread's current alias. It refuses (exit 2) when the rollout exists, the session id is bound to another thread, or the view is empty; no inference, no PTY, no receipt line (a fork's identity note is already tail text).

Control panel

Press ctrl-] while Claude is running. The wrapper opens an alternate-screen panel so it never writes diagnostics into Claude's input box. Override the key with CC_LHC_LEADER. The panel recognizes raw, kitty CSI-u, xterm modifyOtherKeys, and Windows Terminal win32 input events.

| Command | Effect | | --- | --- | | /status | Capture, retrieval, and context-policy status | | /stats | Current capture counters | | /smart-compact | Smart Compact and controlled child handoff | | /smart-prune [tokens] | Advance the visibility boundary and hand off if changed | | /export | Write rollout and served-view transcript dumps | | /bounds <target> <trigger> | Change Smart Compact target/trigger for this wrapper lifetime | | /allocation | Select Default, Balanced, or Historical for this wrapper lifetime | | /details | Show retrieval state, configuration sources, Claude native Compact status, the running operation, and the last action | | /help | List every panel command and its scope | | /introduction | Explain LHC, fidelity bands, and Smart Compact |

Commands are lowercase and slash-prefixed. Type / for suggestions; Tab or a partial Enter completes without execution. Panel edits are session-scoped. Persistent policy is configured below.

The advisory lifecycle-command notifier warns on high-confidence user-entered /resume, /clear, and /compact; it never blocks or rewrites input and is not a correctness mechanism. Disable it for one launch with --lhc-no-notifier. A real session mismatch still revokes retrieval and capture through the authoritative rollout/session checks.

Thinking replay after compact

After each compact the rebuilt rollout replays the tail's thinking blocks with their signatures (SELECTED_THINKING_REBUILD_ARM = signed_verbatim in src/rollout/thinking-ladder.ts). The API binds a thinking block to the exact history it was produced over; a compact rewrites that history. Accounts created on or after 2026-08-31, and later models for all accounts, reject that shape with a prefix-mismatch 400 on the first request after a compact. Older accounts accept it today. If a thread hits that 400, flip the arm to omit and rebuild; no data is lost. Reference: https://platform.claude.com/docs/en/build-with-claude/preserved-thinking

Context policy

Policy precedence is:

builtin < user config < project config < launch flags / panel edits

User config is $XDG_CONFIG_HOME/cc-lhc/config.json (or ~/.config/cc-lhc/config.json); project config is .cc-lhc.json. Supported persisted fields are lowerBoundTokens, upperBoundTokens, profile (default, balanced, or historical), pruneEnabled, pruneThresholdTokens, pruneTargetTokens, and minRunwayTokens.

Two token measures appear in /status, the Control Panel, and receipts, and they cover different domains. Provider-reported context is Claude's own usage count for the last request (input + cache creation + cache read); it is the only measure Smart Compact's trigger is judged against, and when no request has been observed yet it is shown as not observed rather than as zero. LHC estimated tokens are CC-LHC's estimate of content it constructs or stores — the rebuilt view, history captured since the last Smart Compact, eligible tool results, retrieval slices. Estimates use a general tokenizer over text CC-LHC holds, so they may differ from what the provider counts for the same content (and may coincidentally be equal); the two are labelled wherever they appear, and no fixed ratio or direction between them is assumed.

There is one built-in policy: 180k target, 360k trigger, 50k minimum runway. cc-lhc assumes a 1M-window model. Override it through user config ($XDG_CONFIG_HOME/cc-lhc/config.json or ~/.config/cc-lhc/config.json), project config (.cc-lhc.json), launch flags, or /bounds. Explicit user, project, and session values keep their precedence over the built-in.

Bad configuration never disarms the product. An unknown field, a malformed value, an unreadable file, or an incoherent pair of bounds falls back to the built-in default for the fields involved, naming the field and its source; automatic Smart Compact stays on and has no off switch. The fallback is announced at startup, in the wrapper log, in the control panel, and in the Smart Compact message written to the rebuilt session, and it says: Invalid compact configuration. Default configuration used. Please fix or update the configuration.

Run cc-lhc --lhc-help for the wrapper's launch flags and operative environment surface.

State and diagnostics

| Path under ~/.cc-lhc | Purpose | | --- | --- | | registry.sqlite | Thread registry and alias map (session alias → thread, one current alias per thread) | | cc-lhc.sqlite | Host-local session detail (rollout paths, prefix proof, replay signatures, pending-acceptance recovery) and durable governor receipts (cc_governor_receipts) | | threads/<uuid>.sqlite | Per-thread LHC record, derivations, views, and impressions | | owners/*.json | Exclusive thread-ownership leases (keyed by thread hash) | | runtime/*.json | Per-wrapper retrieval capability descriptors (mode 0600 on POSIX; on Windows cc-lhc refuses a CC_LHC_HOME outside the user profile, so these inherit the profile's default ACLs — no POSIX modes and no bespoke DACL there); stale ones are removed at launch | | continuity/ | Output of relaunched monitors and saved results of carried background work | | torn-lines/ | Fragments trimmed from torn transcript tails before resume | | abandoned-rebuilds/<cwd>/ | Rebuilt transcripts from interrupted Smart Compacts, moved out of Claude's projects folder | | recovery/* | Only pre-rewrite artifacts, cleared at launch by the thread that owns them | | wrapper.log | Append-only wrapper diagnostics (no rotation yet) |

Runtime descriptors live in a private runtime directory and are capabilities, not durable state. Rebuilt Claude rollouts remain under Claude's normal ~/.claude/projects/ layout. The original rollout is never rewritten.

Capability boundary vs Codex full continuation

Authoritative cross-host certification (frozen heads, invariant receipts, and gate commands): docs/compact-continuation-certification.md.

| | cc-lhc (capability-limited) | Codex (full state machine) | | --- | --- | --- | | Mid-agentic-turn request replacement | No — closed CLI, no injection seam | Yes — in-place next-request install | | When Smart Compact may run | Claude-safe settled seam only | Settled model-turn seam inside an open agentic turn | | Open-turn threshold | Classify + durable receipt; wouldMutate=false | May compact / preserve tool tail / force continuation | | Continuation marker / context_compact_continue | Not fabricated | Typed marker + forced boundary when applicable | | Handoff | Rebuild rollout + claude --resume (new session id) | Serve compacted view into the same agentic turn | | Native writer | Claude native Compact disabled per child; a summary is captured as one bounded turn | One-writer rules with native conflict refuse | | Receipts | Structured rows in cc-lhc.sqlite + rollout operation note | compact-continuation receipt in thread DB | | Live post-measurement pressure | Real watcher lines: provider output_tokens when valid, else host canonical-payload bytes/4; cumulative until next sampling | Full runtime estimate path |

v1 accepts this difference honestly. Shared LIM-60/61 strings and pressure accounting are reused where they remain truthful; cc-lhc does not claim effects Claude Code cannot perform.

Durable receipts (production): every classification is receipted, and active background work never delays the seam. Receipts are write-behind — they record the Smart Compact, they never decide whether it runs. When the receipt store is unavailable the operation proceeds against an in-memory receipt id with a loud warning (restart recovery is degraded for that attempt; the session still runs Smart Compact). Exact native replay is idempotent (unique replay_key); a replayed receipt whose outcome was a deferral is retried, because no mutation had started, while an existing scheduled receipt after restart is not re-run. Outcomes attach only to that exact receipt id (never “latest wouldMutate”), so old-session → new-session handoff and manual Smart Compact cannot rewrite an unrelated automatic classification.

Operational boundaries

• Fresh capture launches with a wrapper-assigned session ID. Explicit --resume <id> binds that session; bare --resume uses the wrapper-owned cwd picker, and --continue is resolved before Claude is spawned. Ambiguous or conflicting capture selectors fail before spawn.
• Launch-time resume and wrapper-controlled handoffs preserve the LHC thread. Resuming any older session of a thread lands on the session that thread currently accepts; the current pointer advances when a swap is accepted. User-issued in-app /resume is unsupported; the advisory warning appears first, and any resulting mismatch fails closed.
• The initial prompt a launch carries belongs to that launch. A wrapper-owned replacement child inherits the launch's options and continues the conversation, never the prompt, so a prompt is never re-executed. -p and --print are not inherited either, in any form the installed parser accepts (-p, --print, -p=<v>, --print=<v> — all of which name a one-shot seat), because a print child would exit at once. Options whose value boundary the argv does not establish — optional-value, variadic and unknown options in their space form — are left out of the replacement and named in the wrapper log; their =value form carries through. No launch form disables compaction.
• Signed-thinking replay re-emits captured blocks exactly as recorded; whether the provider honours a replayed signature after a rebuilt prefix is provider behaviour, verified by diagnostics rather than promised by the wrapper.
• Claude Code hooks are not required. The wrapper's lifecycle events come from the authoritative rollout stream; PTY handling is limited to terminal transport, the panel, child-liveness proof, and advisory notification.
• Automatic prune remains off by default. Every managed Claude child launches with DISABLE_AUTO_COMPACT=1, so Claude native Compact never runs on a managed session; manual /compact stays available. An explicit user --autocompact passes through unchanged and cc-lhc does not inject the disable for that launch. The Control Panel then shows one nonblocking advisory that Claude native Compact may run before Smart Compact, and /details names the detected argument and the supported way back (relaunch without --autocompact). Omission is all the wrapper claims: inherited environment and Claude's own settings still govern whether Claude native Compact then runs, and cc-lhc cannot observe them.

Verification

# --config.verify-deps-before-run=false works around the open pnpm 11.8.0
# pre-run crash (long-horizon-context-52k); direct tsc/vitest also works.
pnpm --config.verify-deps-before-run=false --filter cc-lhc run typecheck
pnpm --config.verify-deps-before-run=false --filter cc-lhc run test   # CC_LHC_NATIVE_REQUIRE_ADDON=1 makes the compiled addon mandatory

First-load Control Panel copy and layout are tuned against the production renderer only: pnpm run preview:panel (after build) draws the nine named fixtures at normal, narrow, and 20x5 geometry in a disposable home, and cc-lhc preview --fixture <name> --geometry <name> --raw prints one exact frame. The preview never launches Claude.

Certification includes the real installed artifact in SSH → tmux → PTY, automatic Smart Compact twice, unpiped labeled retrieval and impression recording, prune, clean exit/relaunch, explicit resume, deliberate in-app mismatch, legacy label backfill, and production-state isolation.