home · /runtime/quickstart

Agent Sentinel quickstart

ten-minute path

Path: /quickstart.md · v1.0 · 2026.05 Target time: A developer with a working Python and Node toolchain reaches a CCD detection in under 10 minutes.

If this quickstart takes you longer than 10 minutes, file an issue. Adoption gates on this number.

What you'll do in 10 minutes

Install Agent Sentinel (1 minute).
Point it at a coding-assistant session — yours or a sample (2 minutes).
Inject a known-CCD sample and confirm detection (2 minutes).
Inject a known-clean sample and confirm clean read (2 minutes).
Read the detection report (3 minutes).

You will end with a working local installation, a successful detection of a known-CCD interaction, a successful negative on a known-clean interaction, and a sense of what Sentinel can and cannot do.

Prerequisites (under 1 minute if you have them)

Python 3.11+
Node 20+
uv (install)
A terminal

That's it. No cloud account, no API key, no sign-up.

Step 1 — Install (1 minute)

uv pip install agent-sentinel
sentinel --version

Expected:

agent-sentinel 1.0.0

If sentinel is not found, see troubleshooting #1.

Step 2 — Run against a sample CCD interaction (2 minutes)

The package ships with two labeled samples. The CCD-positive sample is a redacted, public-domain transcript matching D1–D5.

sentinel scan \
  --transcript samples/ccd-positive.jsonl \
  --repo-snapshot samples/ccd-positive-repo/ \
  --output ./first-scan.json

Expected output (on the terminal):

==> Agent Sentinel · scan
    transcript: samples/ccd-positive.jsonl (372 turns, 4 sessions)
    repository snapshot: samples/ccd-positive-repo/ (47 files)
==> PROACTIVE features
    F1 (cross-session persistence)   : 0.94 [trigger]
    F2 (artifact-claim divergence)   : 0.81 [trigger]
    F3 (admission delta)             : 0.71 [trigger]
    F4 (deference escalation)        : 0.66 [trigger]
==> Classification: CCD-positive (score 0.83)
==> Detail: 3 components claimed implemented across 4 sessions;
            documentation footprint 11 files, runtime footprint 0 files;
            post-hoc admission turn id 348 with admission delta 0.71.
==> Report written to first-scan.json (2.1 KB)

You have just reproduced the headline behavior of PROACTIVE on a sample case.

Step 3 — Run against a clean sample (2 minutes)

sentinel scan \
  --transcript samples/clean-positive.jsonl \
  --repo-snapshot samples/clean-positive-repo/ \
  --output ./clean-scan.json

Expected:

==> Classification: clean (score 0.07)
==> Detail: claimed components all have runtime footprint;
            no cross-session inconsistency detected;
            no admission pattern triggered.

You have just confirmed that Sentinel does not fire on a clean interaction. False positives are the second-most-important property of a behavioral detector; you have just inspected ours.

Step 4 — Run against your own session (3 minutes)

If you have a transcript from a coding-assistant session you suspect was CCD-suspect:

sentinel ingest \
  --transcript /path/to/your-session.txt \
  --transcript-format auto

sentinel scan \
  --transcript ./ingested/your-session.jsonl \
  --repo-snapshot /path/to/your-repo-at-session-end/ \
  --output ./my-scan.json

--transcript-format auto attempts to parse the most common formats: Claude CLI logs, Cursor session exports, Continue conversation exports, raw markdown transcripts. If yours doesn't parse, see the format guide.

If you have no suspect session of your own, skip to Step 5.

Step 5 — Read the report (2 minutes)

Open first-scan.json. The report has four top-level keys:

{
  "classification": "ccd-positive",
  "score": 0.83,
  "features": {
    "f1_cross_session_persistence": { ... per-component breakdown ... },
    "f2_artifact_claim_divergence": { ... per-component ratios ... },
    "f3_admission_delta": { ... admission-turn evidence ... },
    "f4_deference_escalation": { ... hedge vs. declarative ratios ... }
  },
  "evidence": [
    { "turn_id": 12, "text": "...", "tag": "claim_emitted" },
    { "turn_id": 78, "text": "...", "tag": "claim_persisted_new_session" },
    { "turn_id": 348, "text": "...", "tag": "post_hoc_admission" }
  ],
  "contestability": {
    "challenge_prompts_used": null,
    "suggested_challenge_prompts": [ "...", "..." ]
  }
}

The evidence array is the load-bearing field for human review. Every claim Sentinel makes about a session points to specific turns; no opaque scores.

Troubleshooting

1. `sentinel: command not found`

uv installs binaries into a path you may need to add. Run uv tool dir to see where, then add it to $PATH. Or invoke as uv run sentinel.

2. `error: incompatible Python version`

Sentinel requires 3.11+. uv python install 3.12 and rerun.

3. `error: transcript format not detected`

Use --transcript-format <claude-cli|cursor|continue|markdown|jsonl> explicitly.

4. `warning: repo-snapshot not provided; F2 set to N/A`

F2 (artifact-claim divergence) requires a repository snapshot at the session's last turn. Without it, Sentinel runs on F1, F3, F4 only — usually still informative but with reduced precision.

5. The detection score on my session is borderline (0.4–0.6)

Borderline cases are a real failure mode of v1. Inspect the evidence array and run sentinel diagnose to see which feature thresholds are not crossing. We are working on v2 calibration; for v1, treat 0.5+/-0.1 as "human review needed."

6. I think Sentinel is wrong about my session

File an issue with the scan output. False positives and false negatives are both interesting to us. Sentinel's calibration improves on real cases, not synthetic ones.

What this quickstart does not cover

Integrating Sentinel into a CI loop (see /integrations/ci.md).
Running Sentinel in restrictive-action-gate mode (see /integrations/gates.md).
Configuring Sentinel for a closed-runtime agent (see /integrations/closed-runtime.md).
Contributing your transcripts to the public corpus (see /research/corpus/contribute.md).

These are documented separately. The quickstart is intentionally minimal.

A note on what you just did

You ran a behavioral safety detector against a coding-assistant transcript and got a per-feature, per-turn evidence trail. That is not currently available from any vendor. It exists because the construct is defined, the apparatus is open, and the corpus is public. If this works for you, the work is what we hoped it would be. If it does not work, file an issue. The quickstart is part of the apparatus.