@kodexity/sentinel

Sentinel — by Kodexity

A trust layer for coding agents. Sentinel runs deterministic checks on every change a coding agent makes and — wired into Claude Code as a Stop hook — won't let the agent call itself "done" until the change actually holds up.

The agent is finished when its work is verified, not when it says it is.

Why

Coding agents (Claude Code, Cursor, Codex, …) move fast and occasionally:

• reference APIs/imports that don't exist,
• silently break something three files away,
• ship a change that doesn't even type-check or pass tests.

Sentinel catches these the moment they happen and feeds the failures back into the loop so the agent fixes them before stopping.

How it works

agent finishes a turn
  → Claude Code Stop hook fires → `sentinel hook`
  → detect what changed (git diff, incl. new/untracked files)
  → profile the project (TS / Python / generic)
  → run deterministic verifiers on the changed surface
  → if anything blocks → tell the agent to keep working and fix it
  → otherwise → allow the stop

Verifiers in v0:

| Verifier | What it catches | Needs | |---|---|---| | typecheck | type errors (tsc / mypy / pyright) | a typecheck command | | tests | regressions (your test runner) | a test command | | unsafe-edit | added eval(), hardcoded secrets, deleted error handling, @ts-ignore/# type: ignore | nothing — pure diff heuristics |

It auto-detects your project's own commands from package.json, tsconfig.json, and pyproject.toml. Deep is TypeScript/JavaScript and Python; everything else falls back to whatever build/test commands the project already defines.

Install

npm install -g @kodexity/sentinel

Quick start

In your project:

sentinel init      # writes sentinel.config.json + installs the Claude Code Stop hook

That's it — from now on, when Claude Code finishes a turn in this project, Sentinel verifies the change and keeps the agent working until it passes.

You can also run it standalone (great in a pre-commit hook or CI):

sentinel verify    # exit 0 if clean, 1 if there are blocking findings

Commands

• sentinel verify — verify the current working-tree changes; prints a report, exits 1 on blocking findings.
• sentinel hook — Claude Code Stop-hook entrypoint (reads the hook payload on stdin, emits a block/allow decision). You normally don't call this directly; sentinel init wires it up.
• sentinel init — write a default config and install the Stop hook into .claude/settings.json (idempotent, never clobbers existing hooks).

Configuration

sentinel.config.json in your project root:

{
  "verifiers": ["unsafe-edit", "typecheck", "tests"],
  "maxIterations": 3,
  "severityOverrides": {},
  "commands": {},
  "include": [],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/.venv/**"]
}

• verifiers — which checks to run (drop tests for a faster loop).
• maxIterations — after this many consecutive blocks in one session, Sentinel stops blocking and lets the agent stop, so you're never trapped (default 3).
• severityOverrides — force a verifier's findings to block / warn / info, e.g. { "tests": "warn" }.
• commands — override the detected typecheck / test commands.

Escape hatch

SENTINEL_SKIP=1   # set in the environment to bypass Sentinel entirely

Roadmap

• Deep hallucinated-API detection — precise symbol/import resolution via the TypeScript compiler API and pyright, catching invented functions even with no typechecker configured.
• More languages; an optional AI judge for semantic gray areas; team policies & history.

License

MIT © Kodexity