ccd-cli 1.0.0-alpha.8

# 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 host-neutral continuity and governance kernel for AI coding.

It keeps the parts that should survive host churn, model churn, and session resets:

- project truth in the repo
- operator policy and durable memory in `~/.ccd`
- clone-local handoff and session state in workspace-local runtime state

## Core Separation

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

~/.ccd/
  operator state
  policy, durable 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 host, the best IDE, or the best memory database.

- **Project overlay**: project-specific policy and durable memory 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 |

If you need backlog commands in the installed binary, add `--features extension-backlog` to either install command.

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.

In JSON output, `extension_dispatch` is extension-owned context. Treat it as an opaque extension payload rather than a kernel-owned backlog or assignment contract.

Work normally. Use the two checkpoint surfaces intentionally:

```bash
ccd checkpoint --path .                       # lightweight mid-session pulse
ccd radar-state --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 skips the expensive evaluation, candidate, and approval phases while still computing session boundary, context health, and surface digests. `ccd radar-state` 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 hosts can see what was actually refreshed.

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

```bash
ccd init --path . --host claude
ccd host install claude --path .
```

Host 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 clone-local handoff and session state
- Governance through layered policy, fail-closed writes, and explicit mutation boundaries
- Durable operator memory with promotion and compaction rules
- Host-neutral skill and CLI surfaces that survive IDE/runtime churn

## What CCD Does Not Own

- Agent orchestration UX: your host or IDE owns that
- Semantic recall quality: providers like Mem0/OpenMemory and Graphiti own that
- Shared project facts: the repo remains the source of truth

CCD integrates with those systems through its 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 radar-state`
- `ccd doctor`
- `ccd sync`

**Advanced**

- `ccd describe`
- `ccd scaffold`
- `ccd check`
- `ccd consistency`
- `ccd hooks *`
- `ccd host install`
- `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 backlog *` (requires a build with `--features extension-backlog`)
- `ccd codemap *`
- `ccd context-check`
- `ccd escalation-state *`
- `ccd pod *`
- `ccd policy-check`
- `ccd runtime-state *`
- `ccd session-state gates *`

## Read Next

- [Why CCD](docs/guide/01-why.md)
- [Quickstart](docs/guide/02-quickstart.md)
- [Cheatsheet](docs/reference/cheatsheet.md)
- [Host Startup Wrappers](docs/reference/host-startup-wrappers.md)
- [Session Liveness Contract](docs/reference/session-liveness-contract.md)
- [Memory Architecture](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)
- [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 host 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.