nocap · docs

Documentation

Install

Needs Node 20+ and a git repository. No account. Try it on a built-in scenario first.

npx @shankywho/nocap demo toothless
npx @shankywho/nocap check --summary summary.md

CLI reference

Generated from the commander help text. Exit codes: 0 pass, 1 contradicted, 2 usage or input error, 3 MIXED with --strict.

Usage: nocap [options] [command]

your agent says it's done. nocap checks.

Options:
  -V, --version                       output the version number
  -h, --help                          display help for command

Commands:
  check [options]                     verify an agent's summary against the repo
                                      in the current directory
  demo [options] [scenario]           build a fixture scenario in .cache and
                                      verify it with live output
  loop [options]                      closed repair loop: check, hand the repair
                                      packet to your agent, re-check
  hook <agent>                        agent hook entrypoint (stdin JSON).
                                      Currently: claude (Stop hook)
  init [options] [agent]              wire nocap into your agents: `init --all`
                                      detects them all; `init claude` installs
                                      only the Claude Code hook
  mcp                                 start the MCP stdio server (verify_claims,
                                      get_repair, bitecheck, check_scope, ...)
  bitecheck [options] <testFiles...>  prove specific tests bite: they must fail
                                      without the source change
  chain [chainId]                     print the proof-chain timeline (default:
                                      the latest chain)
  handoff [options]                   what the next agent can trust, must not
                                      rely on, and what is stale (from the
                                      ledger)
  scorecard                           per agent+model accuracy from local
                                      receipts
  repair [options] [receiptFile]      print repair instructions from the last
                                      (or a given) receipt
  publish [options] <receiptFile>     upload an existing receipt
  help [command]                      display help for command

Usage: nocap check [options]

verify an agent's summary against the repo in the current directory

Options:
  --summary <file|->           summary file, or - for stdin (default: stdin when
                               piped)
  --base <ref>                 base ref
  --head <ref>                 head ref (default: working-tree snapshot if
                               dirty, else HEAD)
  --agent <name>               agent name for the receipt
  --no-exec                    static checks only: never run tests or commands
  --offline                    never call an LLM
  --scope <concept=glob,glob>  map a concept to globs (repeatable) (default: [])
  --test-cmd <cmd>             custom test command with {files} and {out}
  --test-format <fmt>          jest|junit (with --test-cmd)
  --json                       print the receipt as JSON
  --md                         print the receipt as markdown
  --out <file>                 also write the rendered output to a file
  --publish                    upload the receipt to NOCAP_API_URL
  --no-hunks                   omit diff hunks when publishing
  --strict                     exit 3 when the result is MIXED
  --repair                     print repair instructions for contradicted claims
  --actor <agent>              acting agent
  --model <id>                 model id of the acting agent
  --role <name>                role of the acting agent
  --verbose                    narrate each step
  --chain <id|auto|new>        continue (or start) a proof chain across attempts
  --since-last                 judge only the delta since the previous receipt
                               (per-agent attribution)
  --scope-role <role=globs>    declare another role's scope (repeatable);
                               touching it raises cross_agent_overlap (default:
                               [])
  -h, --help                   display help for command

Usage: nocap demo [options] [scenario]

build a fixture scenario in .cache and verify it with live output

Options:
  --no-exec   static checks only
  -h, --help  display help for command

Usage: nocap loop [options]

closed repair loop: check, hand the repair packet to your agent, re-check

Options:
  --agent-cmd <cmd>        agent command; {repair_file} is replaced by the
                           repair packet path
  --summary <file|->       initial summary (default: stdin when piped)
  --summary-from <source>  where the agent's next summary comes from: stdout |
                           file:<path> (default: "stdout")
  --max <n>                maximum attempts (default: "3")
  --no-exec                static checks only
  --agent <name>           agent name for the receipts
  --base <ref>             base ref
  --verbose                narrate each step
  -h, --help               display help for command

Usage: nocap hook [options] <agent>

agent hook entrypoint (stdin JSON). Currently: claude (Stop hook)

Options:
  -h, --help  display help for command

Usage: nocap init [options] [agent]

wire nocap into your agents: `init --all` detects them all; `init claude`
installs only the Claude Code hook

Options:
  --all       detect every installed agent and configure MCP + hooks + AGENTS.md
  --write     apply the changes (default is a dry run)
  --user      allow writing user-level config (needed for Codex)
  -h, --help  display help for command

Usage: nocap mcp [options]

start the MCP stdio server (verify_claims, get_repair, bitecheck, check_scope,
...)

Options:
  -h, --help  display help for command

Usage: nocap bitecheck [options] <testFiles...>

prove specific tests bite: they must fail without the source change

Options:
  --base <ref>  base ref
  -h, --help    display help for command

Usage: nocap chain [options] [chainId]

print the proof-chain timeline (default: the latest chain)

Options:
  -h, --help  display help for command

Usage: nocap handoff [options]

what the next agent can trust, must not rely on, and what is stale (from the
ledger)

Options:
  --to <role>  role of the agent receiving the work
  -h, --help   display help for command

Usage: nocap scorecard [options]

per agent+model accuracy from local receipts

Options:
  -h, --help  display help for command

Usage: nocap repair [options] [receiptFile]

print repair instructions from the last (or a given) receipt

Options:
  --json      print the repair packet as JSON
  -h, --help  display help for command

Usage: nocap publish [options] <receiptFile>

upload an existing receipt

Options:
  --no-hunks  omit diff hunks
  -h, --help  display help for command

Claude Code hook

A Stop hook checks the agent's final message. It reports by default. Set NOCAP_BLOCK=1 to block the agent on a ✗ (at most twice per session).

npx @shankywho/nocap init claude --write          # project .claude/settings.json
npx @shankywho/nocap init claude --write --user   # ~/.claude/settings.json

Codex and Gemini CLI have hooks too (payload shapes unverified; see docs/decisions.md). Codex runs notify with the JSON as its last argument and cannot be blocked, so nocap only reports. Gemini's AfterAgent hook can deny, and does so with NOCAP_BLOCK=1.

# ~/.codex/config.toml
notify = ["npx", "-y", "@shankywho/nocap", "hook", "codex"]

# Gemini CLI settings: AfterAgent hook command
npx -y @shankywho/nocap hook gemini

MCP server

Seven tools over stdio: verify_claims, get_repair, bitecheck, check_scope, ledger_facts, ledger_check, scorecard.

{ "mcpServers": { "nocap": { "command": "npx", "args": ["-y", "@shankywho/nocap", "mcp"] } } }

One command wires every agent it finds: npx @shankywho/nocap init --all (dry run by default; add --write).

Alan plugin

Add plugins/nocap to your Alan workspace. The agent calls ledger_facts at the start of a multi-agent task, bitecheck after writing tests, verify_claims before saying done, and get_repair after a fail. Results map to Alan's test report: PASS, FAIL and MIXED become pass, fail and mixed.

PR mode

Paste a public PR on the landing page or POST /api/verify-pr. PR mode is static: CI status stands in for the test run, and tests_added, bug_fixed and build_pass are marked ! because proving them needs execution. Run npx @shankywho/nocap check locally for the full proof.

Configuration

Optional .nocaprc.json at the repo root.

{
  "scope": { "auth": ["src/auth/**", "src/middleware/session.ts"] },
  "roleScopes": { "backend": ["src/server/**"] },
  "testCommand": "pnpm test --reporter=json",
  "testFormat": "jest"
}

Privacy

Only the summary and file paths go to the model, never file contents. Tests and Bitecheck run locally in a throwaway git worktree. Published receipts are public by link; delete one with the token returned at publish time. There are no accounts.

FAQ

Why ! and not ✗? A claim nocap cannot check is never called false. It is marked ! and says what would prove it.

Can an agent game it? Deleting a failing test or dropping a claim without retracting it is flagged repair_by_weakening and fails the chain.