# 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.

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.

- **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/dusk-network/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 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.

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
runtime projections. JSON remains authoritative, and runtime injection is still
opt-in only; see the [Symbolic Prompt Dialect](docs/reference/symbolic-prompt-dialect.md).

If you want repo-local runtime integration assets, scaffold them explicitly:

```bash
ccd init --path .
```

Runtime posture is now tiered deliberately:

- Codex: human-driven `/ccd-start` or `ccd start --activate` remains the supported baseline; the launcher wrapper is optional convenience/eval harness only
- Claude Code: native project hooks are the preferred path; manual `/ccd-start` or `ccd start --activate` is fallback only when those hooks are not installed
- OpenClaw and Hermes: use explicit reference-adapter configs that call `ccd host-hook` at lifecycle boundaries

Use `--diagnostics` or `ccd telemetry report --output json --path .` only when
you need payload analysis, projection-cache cadence, provider-cache correlation,
or prompt-cost diagnostics.

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
- Narrow remembered guidance only where it sharpens future continuity
- 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: runtimes or providers may help, but CCD is not trying to be a general memory backend
- Semantic recall quality: providers like Mem0/OpenMemory and Graphiti own that
- Shared project facts: project truth remains the source of truth

CCD integrates with those systems through an optional read-only recall provider seam. External providers can use the optional `command-session` transport to amortize cold-start cost across sequential recall operations within a single command. See the [Recall Provider Setup Guide](docs/guides/recall-provider-setup.md) for configuration.

## 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 init`
- `ccd start`
- `ccd status`
- `ccd checkpoint`
- `ccd handover`
- `ccd doctor`
- `ccd sync`

**Advanced**

- `ccd describe`
- `ccd scaffold`
- `ccd check`
- `ccd consistency`
- `ccd hooks *`
- `ccd host apply`
- `ccd handoff *`
- `ccd memory *`
- `ccd remember`
- `ccd repo *`
- `ccd session open`
- `ccd skills install`
- `ccd telemetry report`

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 migrate from-pod-layout`
- `ccd policy-check`
- `ccd runtime-state *`
- `ccd session-state gates *`

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)
- [Continuity and Remembered Guidance](docs/guide/05-memory-architecture.md)
- [Memory Recall Providers](docs/reference/memory-recall-providers.md)
- [Recall Provider Setup Guide](docs/guides/recall-provider-setup.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.
