# Continuous Context Development

[![crates.io](https://img.shields.io/crates/v/ccd-cli.svg)](https://crates.io/crates/ccd-cli)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

CCD is the runtime-neutral continuity and governance kernel for AI coding.

It decides what context should carry forward across session resets and runtime
changes while keeping project truth canonical and local runtime state local.
Lifeloop is the lifecycle-normalization substrate below CCD continuity.
Runtime-native integrations or external Lifeloop adapters own harness lifecycle
facts; CCD owns what those facts mean for continuity.

The product boundary is simple:

- project truth in project files
- remembered guidance and policy in `~/.ccd`
- workspace-local handoff and active session state in local runtime state

## Core Separation

```text
repo/
  project truth
  AGENTS.md, README.md, specs, tests, source

~/.ccd/
  remembered guidance and policy
  policy, memory, project-local overlays

workspace-local state
  clone-local handoff and active session state
```

That separation is the product. CCD is not trying to be the best agent
runtime, the best IDE, or the best memory database, and Lifeloop is not a
tool, model, prompt-cache, memory, or recursive-inference layer.

- **Project overlay**: project-specific policy and remembered guidance under `~/.ccd/profiles/{profile}/repos/{project_id}/...`
- **Workspace state**: clone-local handoff and active session state for the current checkout

If a workspace loses its binding, use `ccd repo relink` to reconnect it to the right project overlay instead of rebuilding state from scratch.

## Supported Install Paths

CCD supports two installation paths today:

| Path | Use it when | Maintenance posture |
| --- | --- | --- |
| `cargo install ccd-cli` | First session, demos, routine adoption | Preferred and documented day-1 path |
| `git clone https://github.com/nantobv/ccd.git /tmp/ccd && cargo install --path /tmp/ccd` | Contributing or testing unreleased changes | Supported contributor path; you own staying in sync with current source |

Homebrew, curl installers, and OS packages are not supported distribution channels yet.

## Try It In 5 Minutes

Install the published CLI:

```bash
cargo install ccd-cli
```

If you want the shipped skills:

```bash
ccd skills install
```

Bootstrap one workspace:

```bash
ccd attach --path .
ccd start --activate --path .
```

`ccd start --activate` is the supported one-command raw CLI fast path. This is narrower than the old `#386` coalescing idea: startup can collapse into one call, but close-out still stays explicit.

Work normally. Use the two checkpoint surfaces intentionally:

```bash
ccd checkpoint --path .                       # lightweight mid-session pulse
ccd handover --path .                      # full wrap-up and continuity evaluation
ccd session renew prepare --path .           # prepare a runtime reset, then use the printed continuation command
ccd checkpoint --since-session current --path .  # delta-only output (unchanged surfaces collapsed)
ccd consistency --path .                      # targeted artifact-consistency audit
```

`ccd checkpoint` is a distinct lightweight command that carries the shared continuity foundation — session boundary, context health, behavioral drift, handoff refresh candidates, and surface digests — but omits the handover-only surfaces (full evaluation buckets, memory candidates, repo native checks, approval steps). `ccd handover` remains the full evaluation path for wrap-up.

When `session_boundary.action` is `renew`, run `ccd session renew prepare`,
reset the runtime session, then run the exact `ccd start --refresh
--continuation <token>` command printed by CCD. The continuation token preserves
the active thread across the reset.

For Codex, Lifeloop 0.3.0 ships an opt-in `ccd-renewal` profile that automates
that two-phase path through Lifeloop's host-hook broker. Render/install the
Codex assets with `lifeloop asset preview --host codex --mode native_hook
--profile ccd-renewal`; the broker observes CCD's `renew` boundary, calls
`ccd session renew prepare --adapter codex --reset-path wrapper`, stores the
continuation token out of band, and fulfills the lease after the runtime reset.
CCD reads Lifeloop's token-safe `renewal-status.json` ledger as external
evidence: `ccd start` and `ccd status` expose it under `lifeloop_renewal`,
while `ccd checkpoint` and `ccd handover` fold the latest state into
`session_boundary.evidence`. A pending continuation stops a normal start until
the runtime resumes through the renewal profile; failed or expired automation
stops startup with the Lifeloop retry posture instead of guessing from token
files.
If that profile is not installed, use the manual renewal command above.

Repeated `checkpoint`/`handover` calls may reuse a private, short-lived
`state.db` cache when the session, workspace, runtime inputs, and check
environment are unchanged. This is an optimization only: stale, corrupt, or
mismatched cache entries are ignored and recomputed.

The `--since-session` flag compares surface digests against the session-start baseline and collapses unchanged surfaces to `{"status": "unchanged"}`, reducing token cost for mid-session checks. JSON output also reports `session_delta.skip_stats`, `projection_telemetry.delta`, estimated token counts by surface and projection format, and narrative/symbolic/bundle cache cadence so runtimes can see what was actually refreshed.

CCD also carries an internal `CCD1` symbolic prompt model for compact,
validated agent-facing CCD surfaces. JSON remains authoritative, and CCD1 is
included by default on continuity JSON reports such as `ccd start`,
`ccd context-check`, `ccd checkpoint`, and `ccd handover` unless the caller
passes `--no-ccd1-prompt`. CCD1 is not a runtime or model-side integration
requirement; JSON/policy stays authoritative. See the
[Symbolic Prompt Dialect](docs/reference/symbolic-prompt-dialect.md).

Per-harness host integration left CCD in the Phase 3 + 5 slimdown
(issue #723). CCD no longer ships `ccd host`, `ccd host-hook`, `ccd hooks`,
or `ccd telemetry`. Harnesses that need lifecycle hooks or telemetry should
use their native adapter mechanism or an external Lifeloop adapter outside
CCD. Codex renewal automation is available through Lifeloop's opt-in
`ccd-renewal` profile; manual `/ccd-start` or `ccd start --activate` remains
the runtime-neutral entry point.

If you prefer the shipped skills, the core loop is:

```text
/ccd-attach
/ccd-start
/ccd-checkpoint
/ccd-radar
```

## What CCD Owns

- Continuity across sessions through workspace-local handoff and session state
- Governance through layered policy, fail-closed writes, and explicit mutation boundaries
- Runtime-neutral skill and CLI surfaces that survive IDE/runtime churn

## What CCD Does Not Own

- Agent orchestration UX: your runtime or IDE owns that
- Durable remembering as a product category: CCD is continuity-only and harness-agnostic. Memory left CCD in the Phase 4 slimdown — separate Lifeloop clients (e.g. Fixity) own memory evidence, promotion, and recall
- Semantic recall quality: external providers own that
- Shared project facts: project truth remains the source of truth

## Command Tiers

Implementation note: `src/main.rs` remains the canonical top-level CLI schema and command table, while domain-specific routing now lives in focused modules under `src/commands/dispatch/`. That keeps the public surface stable without leaving unrelated command wiring in one file.

**Core**

- `ccd attach`
- `ccd start`
- `ccd status`
- `ccd checkpoint`
- `ccd handover`
- `ccd doctor`

**Advanced**

- `ccd describe`
- `ccd scaffold`
- `ccd check`
- `ccd consistency`
- `ccd handoff *`
- `ccd repo *`
- `ccd session open`
- `ccd skills install` (active-harness native skill layout)

Git-backed `ccd session open` belongs to `/ccd-git-workflow` when you need worktree or branch isolation. It is intentionally outside the default day-1 kernel loop.

**Platform**

- `ccd context-check`
- `ccd escalation-state *`
- `ccd machine list`
- `ccd policy-check`
- `ccd state *`
- `ccd session-state gates *`
- `ccd thread list/show/name/resume/close`
- `ccd thread export/import/status`
- `ccd curl list/show/search/export`

Backlog/work-queue orchestration and codemap no longer ship from this repo.
Those surfaces now live in `ccd-extensions`.

## Read Next

- [Why CCD](docs/guide/01-why.md)
- [Quickstart](docs/guide/02-quickstart.md)
- [Cheatsheet](docs/reference/cheatsheet.md)
- [Runtime Startup Wrappers](docs/reference/runtime-startup-wrappers.md)
- [Symbolic Prompt Dialect](docs/reference/symbolic-prompt-dialect.md)
- [Session Liveness Contract](docs/reference/session-liveness-contract.md)
- [Skills](skills/README.md)
- [Kernel Contracts](specs/README.md)
- [Implementation Matrix](specs/IMPLEMENTATION.md)
- [Runtime Builders](docs/guide/09-runtime-builders.md)

## Safety

CCD's shipped skills and runtime integrations follow one contract:

- inspect read-only state first
- obey preview/apply or confirm-write metadata instead of guessing
- keep machine-readable stdout clean
- treat external queue snapshots as external context, not project truth
- keep Git workflow follow-through separate from startup and continuity loading

See [docs/reference/agent-safety-contract.md](docs/reference/agent-safety-contract.md) for the full contract.

Dependency hygiene is part of the CLI safety boundary. When a transitive crate
pulls an unsound dependency into `ccd`, prefer removing that transitive edge or
using the current stable dependency directly, then verify with `cargo audit`
before release.
