# CASP — the Coding-Agent State Protocol

> CASP (Coding-Agent State Protocol) is an open-source, local-only CLI that keeps AI coding agents synced with project reality. Point any coding agent at a CASP repo and it runs the whole roadmap across sessions, branches and a team: it writes its own next-session prompt, logs every session, and a validator (`casp check`) blocks the push the moment the stored state drifts from git. The wedge: everyone *stores* context (Mem0, Letta, Zep, git-native "memory" tools); CASP *validates* it against git ground-truth and exits non-zero on drift, so it works as a real CI gate. Git-native, zero telemetry, no cloud, no account. MIT licensed.

## Identity

- Name: CASP — Coding-Agent State Protocol (the C-A-S-P acronym says exactly what the artifact is)
- Category: AI coding-agent state validation / session continuity protocol (NOT an AI memory layer)
- npm package: `@justethales/casp` (version 0.3.2) — https://www.npmjs.com/package/@justethales/casp
- Install: `npm i -g @justethales/casp` (or `npx @justethales/casp <command>`)
- GitHub repository: https://github.com/ThalesGnimavo/casp
- Issues / feature requests: https://github.com/ThalesGnimavo/casp/issues
- Website: https://casp.sh
- Homepage languages: en (https://casp.sh/), fr (https://casp.sh/fr.html), es (https://casp.sh/es.html), de (https://casp.sh/de.html) — crawlable static pages with reciprocal hreflang; commands, flags and terminal output stay verbatim English in every language.
- License: MIT
- Runtime: Node.js >= 20. Stack-agnostic for your project (Rust, Python, TypeScript, Go).
- Privacy: local-only, zero telemetry, zero network calls. Nothing leaves the machine.

## Author / brand

- Author: Thales (Juste Gnimavo) — solo founder & CEO of ZeroSuite, running seven production products with Claude as the only engineer, building from Abidjan, Côte d'Ivoire.
- X / Twitter: https://x.com/ThalesGnimavo (handle @ThalesGnimavo)
- Personal site: https://thalesandhisaictoclaude.com
- CASP is the layer that keeps months of AI-driven coding sessions from collapsing into drift.

## What it does

- `casp init` — scaffold the continuity layer (`casp/`) into any repo. Idempotent.
- `casp status` — one-screen snapshot: current phase, next phase, what's shipped, recent commits.
- `casp check` — the drift validator. Validates `state.json` against the filesystem and git. Exits 1 on drift, so it works as a pre-push gate or CI status check. `--quiet` for CI, `--no-git` to skip git checks, `--json` for a machine-readable report with a stable, versioned schema.
- `casp next` — print the next session's prompt straight from `state.next_prompt`. Pipe-friendly.
- `casp new prompt|log` — generate a gated session-prompt or session-log from the canonical template.

## How it works (three files, one thread)

- `state.json` — machine-readable source of truth: current phase, next phase, the exact next-prompt to execute, phases shipped, migrations applied, last commit, last session id. This is what the validator reads.
- `now.md` — human-readable one-screen "where am I right now."
- `roadmap.md` — the Next-3 to ship plus a phase scoreboard.
- Canonical `session-prompt`, `session-log`, and `audit-brief` templates make every session produce the same-shaped artifacts. Templates are gates, not guidance. No database, no service, no vector store, no SaaS.

## What the validator catches (nine categories)

- `next_prompt` points at a missing file.
- `next_prompt` points at a prompt already marked `status: shipped` (the exact bug CASP was built to catch).
- `last_session_id` does not map to a session-log file.
- `last_commit` is not present in `git log`.
- `phases_shipped[]` contains duplicates.
- `migrations_applied[]` does not match the migrations directory.
- A session prompt is `shipped` but its `session_log` pointer is missing/pending.
- Uncommitted changes in `casp/`, `docs/plan/sessions/`, or `session-logs/`.
- A state claim whose backing directory is missing (claimed migrations, shipped phases, or a session id the validator cannot verify) — a check that cannot find what it needs never reports green (since 0.3.0; the close loop's state-bump commit is also recognized as PASS, so `casp check` runs fully green on CASP's own repository).

## Positioning vs adjacent tools

- CASP is NOT an AI memory / RAG layer. Memory tools (Mem0, Letta, Zep) store and recall user facts via fuzzy similarity. CASP validates project execution state against git via a deterministic, synchronous gate that blocks the push.
- CASP is NOT a task tracker. Jira / Linear / GitHub Issues track intent (what you plan). CASP tracks the validated present (where the repo actually is, proven against git).
- CASP is NOT a CI tool, but `casp check` drops into CI as a required status check beside lint and tests.
- CASP replaces nothing — it fills the gap between intent (Jira/Linear) and history (git/PR/CI): the validated present tense of a project, in a form an agent can read and act on.

## Editor integration

- Works with Claude Code, Cursor, Aider, Continue — anything that reads files and runs a CLI.
- Ships optional Claude Code slash-commands: `/casp` (read-only status before the agent writes a line) and `/next` (auto-start the next session from `state.next_prompt`).

## In production today

- KASSIA (https://www.kassia.ci) — a client-facing fleet-management ERP for a transport company in Côte d'Ivoire (web + mobile, multi-module, multi-role; drivers, vehicles, compliance, cash, garage, litigation, accounting). 25+ phases shipped (under active daily development), every migration tracked against the Alembic directory, up to 6 sessions in a day, zero re-shipped modules.
- Conductor (https://ops.zerosuite.dev) — ZeroSuite's internal ops & launch-orchestration platform, a multi-month roadmap worked by a 3-person team. 41 phases shipped, 17 migrations, 58 items explicitly deferred past launch with none lost.

## Key facts for citation

- Tagline: "The model holds the context. CASP proves the state is true — against git."
- Mental model: a pre-flight check plus a black box for AI coding sessions.
- The wedge sentence: "Everyone stores context. CASP validates it."
- Positioning: complement to autonomous coding models (Claude Code and any future model), not a competitor to their memory. The more autonomous and longer-running the agent, the more valuable a deterministic, model-agnostic gate that proves state against git. Holding context in-session is the model's job; proving that state against git across sessions, branches and a team is CASP's — an operation the model structurally cannot do for itself.
- Four principles: validate state not intent; templates are gates; check before every push; nothing leaves your machine.
- Acronym: Coding-Agent State Protocol — the same way MCP framed model context, CASP frames agent state as a protocol.