ContextSutra AI

05. User guide

60-second start

npx contextsutra demo --out contextsutra-demo

Open contextsutra-demo/report.html in a browser. You have just scanned the bundled sample repository and produced a capsule, a Claude-ready hand-off and a human report. Nothing left your machine.

Use it on your own project

cd your-project
npx contextsutra scan --root . --out .contextsutra/capsule.json
npx contextsutra review --capsule .contextsutra/capsule.json
npx contextsutra report --capsule .contextsutra/capsule.json --root . --out .contextsutra/report
npx contextsutra render --capsule .contextsutra/capsule.json --host claude --out .contextsutra/handoff.md

Add .contextsutra/ to your .gitignore. Open .contextsutra/report/report.html and read it before sharing anything.

Check that context is still fresh

npx contextsutra verify --root . --capsule .contextsutra/capsule.json

CURRENT means every captured document still matches. STALE lists what changed or is new; rescan and use diff to see the delta. Exit code 2 makes this easy to use in CI.

Fit a small context window

npx contextsutra render --capsule .contextsutra/capsule.json --host cursor --budget 4000 --out handoff.md

Instruction files and ADRs are kept first. The output says what was omitted.

Install the skills

npx contextsutra install --root . --host cursor
npx contextsutra doctor --root .

install refuses to overwrite existing files; add --force only after looking at them. Then reload your IDE and invoke a skill the way that IDE documents. ContextSutra cannot tell whether the IDE loaded it.

Reading the results

You seeIt meansYou do
HUMAN_REVIEW_REQUIREDNo residual secret pattern found; a person must still read itRead the capsule
BLOCKA secret-like or instruction-like string survivedFix the source, rescan
STALEA document changed, vanished or was addedRescan, run diff
quarantinedLines > 0Lines that looked like instructions to an AI were withheldCheck why they are in your docs
approved: false on a decisionNo explicit accepted statusAsk a maintainer

Do and do not

Troubleshooting

SymptomFix
--capsule is requiredPass the file path after the flag
Already exists ... rerun with --forceCompare the files, then add --force if intended
Refusing to install through symlinkReplace the symlinked directory with a real one
Capsule integrity digest mismatchThe file was edited; rescan
Scan finds 0 sourcesNo README, AGENTS, CLAUDE, ADR or similar file at the allowed paths