Coding-Agent State Protocol

The model holds the context. CASP proves the state is true — against git.

The new models run your whole roadmap for hours, even days, without losing the thread. That's exactly why state drift matters more, not less: the more an agent does between your checkpoints, the more its recorded state can quietly stop matching git. casp check is the deterministic gate that blocks the push the moment it does — with Claude Code today, and every model that ships next.

Pre-flight check + black box for AI coding sessions
$npm i -g @justethales/casp copy
View on GitHub
casp check — drift validator
01 / The thread you keep losing

A stale state file makes your agent confidently wrong.

You come back to a project after a week — or you juggle five at once. The agent reads a state file that no longer matches reality, confidently starts work that already shipped, and you burn an afternoon undoing it.

Boards, cards and spreadsheets don't save you: reconstructing context is manual, and the agent can't read any of it. The state needs to be machine-readable, git-native — and provably true.

CASP gives every project one thread that survives across sessions — and can't drift silently.
state.json ● DRIFTED
{
  "phase": "13 — camera streaming",
  "next_prompt": "phases/14-camera.md",
                  // shipped in v13.4
  "last_commit": "a1f3c9",
                  // not in git history
  "migrations": ["0001""0007"],
                  // git stops at 0006
}
02 / The wedge

Everyone stores context. CASP validates it.

The adjacent space — Mem0, Letta, Zep, the new git-native "memory" projects — all store what happened. Almost none verify that the stored state still matches git reality. That verification is casp check — and it's mandatory before every push.

next-prompt drift
caught

Your next_prompt points at a file that's already shipped — or doesn't exist. CASP refuses to start the wrong session.

git ground-truth
enforced

last_commit not in history, migrations list out of sync, uncommitted state — checked against git itself, not a guess.

push, blocked
deterministic

No fuzzy similarity scores. A hard, repeatable pass/fail gate that stops the push while the state is lying.

03 / Beside your existing stack

Git, PRs and CI don't know what ships next.

CASP replaces nothing in your workflow. It fills the one gap nothing else covers — the validated present tense of a project, in a form your agent can read and act on.

Jira · Linear
Intent
What you plan to do.
Drifts from reality, lives in the cloud, your agent can't reliably read it.
CASP
Validated present
Where the project stands right now — and the exact next move, proven against git.
Machine-readable, in-repo, deterministic. The single thread agents act on.
git · PR · CI
History & verification
What changed · is it reviewed · does it build.
A perfect record of the past — and silent about what comes next.
04 / Three files. One thread.

The whole protocol fits in your repo.

No database. No service. No vector store. Three plain files an agent can read on the first line of any session.

state.json
source of truth

Machine-readable, per project: current phase, next phase, the exact next-prompt to execute, phases shipped, migrations applied, last commit, last session id.

now.md
for humans

The one-screen "where am I right now." Open it, get the thread back in five seconds — no archaeology.

roadmap.md
what ships next

The Next-3 to ship plus a phase scoreboard. The agent always knows the order of work.

Templates are gates, not guidance.  Canonical session-prompt, session-log and audit-brief templates mean every session — human or agent — produces the same-shaped artifacts. Structure is enforced, not suggested.
05 / Built for big roadmaps

One ordered thread across forty phases — web and mobile.

A real product isn't one feature. It's dozens of phases across API, web client and mobile, shipped over weeks by rotating sessions and agents. CASP keeps a single validated order across all of it — so any agent knows which phase is next, and never re-ships a shipped one.

And the loop closes itself: at each session's end the agent writes the next session's prompt for you — you tweak a line, you don't author from scratch — appends a session log, and bumps the state. Open the next session and it picks up exactly where the last one stopped. The roadmap executes; you supervise.

roadmap.md — phase scoreboard 13 shipped 22 total
10apiRealtime sync engineshipped
11mobilePush notificationsshipped
12mobileOffline-first cacheshipped
13webTeam permissionsshipped
15apiPer-seat billingqueued
16mobileBiometric loginqueued
/ In production

Not a demo. Two live products run on CASP today.

Every number below is read straight from each project's state.json — the same file the agent reads, validated against git on the last push. No marketing math.

LIVE

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
20+
migrations tracked
6
sessions in a day

Every module is a validated phase. The agent reads the cockpit, runs the next phase from next_prompt, and has never re-shipped a shipped module — even on a six-session day.

LIVE

The internal ops & launch-orchestration platform for ZeroSuite — a multi-month roadmap worked by a real team, with launch-mode gating and a tracked post-launch backlog.

41
phases shipped
17
migrations
3
operators

One validated thread across 40+ phases and three people — plus 58 items explicitly deferred past launch, none of them lost. This is the "big multi-user project" case CASP was built for.

Same protocol, two very different products. The cockpit is the only thing they share.

06 / State, not memory

CASP is not an AI memory layer.

Memory tools remember who you are. CASP tracks where your project stands — and proves it. Different artifact, different operation, different failure it prevents.

CASP
Memory layers · Mem0 / Letta / git-native "soul"
What it holds
Project execution state
User facts & preferences
Core operation
Validates against git
Stores & recalls
On conflict
Deterministic check vs ground-truth
Fuzzy similarity guess
When it runs
Synchronous gate — blocks the push
Async / eventual recall
Leaves your machine
Never · zero telemetry
Varies / cloud
07 / The command deck

Five verbs. Trivially typed.

One syllable, no homographs, the same in English, French or Spanish.

casp initScaffold the continuity layer into any repo.
casp statusOne-screen snapshot: phase, next, what's shipped.
casp checkThe drift validator. Mandatory before every push.
casp nextAuto-start the next session from state.next_prompt.
casp new promptGenerate a gated session-prompt from the canonical template.
casp new logOpen a session-log in the shape every session shares.
08 / In your editor

Native slash-commands for your agent.

CASP ships Claude Code slash-commands so the state lives where you already work.

/casp

Read-only status — the agent reads the current thread before it writes a single line.

/next

Auto-start the next session straight from state.next_prompt. No copy-paste, no guessing.

Works with Claude Code · Cursor · Aider · Continue — anything that reads files.

09 / For engineering orgs

When agents run unattended, drift becomes a fleet problem.

One agent doing the wrong thing costs an afternoon. A hundred agents doing it across a hundred repos costs a quarter. CASP is the deterministic guardrail you drop into the automation loop — the same shape in every project.

A required CI status check

casp check sits in the same slot as lint and tests. A state that lies can't merge — drift is blocked at the org level, not left to anyone's discipline.

A guardrail for agent fleets

Autonomous agents multiply mistakes. CASP hands every one of them the same validated thread to read and the same hard gate before it pushes. Automation without the duplicate-work tax.

An audit trail, for free

Every state transition is a git commit. A complete, diffable, revertable record of how each project moved — git log is your compliance trail.

Passes infosec by design

Local-only, zero telemetry, no cloud, no account. Nothing to vet, nothing to exfiltrate. The security review is one line: it never leaves the machine.

.github/workflows/ci.yml
jobs:
  state-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # casp checks against full git history
      - run: npx @justethales/casp check       # ✗ fails the build the moment state drifts

One protocol, every repo. The same validated shape, org-wide.

10 / The contract

Opinionated on purpose.

A protocol earns adoption by being predictable. These don't bend.

P01

Validate state, not intent

CASP checks what your repo is, never what you meant to do. Facts against git, every time.

P02

Templates are gates

Canonical artifacts are enforced, not suggested. Every session comes out the same shape.

P03

check before every push

The validator is not optional. A lying state never reaches your remote.

P04

Nothing leaves your machine

Deterministic, git-native, local-only. Zero telemetry. No cloud, no account, no bill.

Ship in two minutes

Give every project a thread your agent can't lose.

Install, init, and your agent reads the truth on its first line.

  terminal
$ npm i -g @justethales/casp
$ casp init          # scaffold the layer
$ casp status        # where am I right now
$ casp check         # prove the state is true