npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

sentinel-cli

v3.6.0

Published

Minimalist AI coding assistant for the terminal (Pi-style). Multi-LLM, local tools, sessions, MCP — no servers, no telemetry.

Readme

◈ Sentinel

A minimalist AI coding assistant for the terminal — Pi-style. Multi-LLM, local tools, sessions, MCP. No servers, no telemetry, no bloat.

License: MIT

Sentinel is a coding agent that lives in your terminal. It streams answers from your choice of LLM, reads and edits your files through a sandboxed local tool set, manages chat sessions as plain JSON on disk, and optionally exposes itself to other AI tools over MCP. That's the whole product.

Why

Most terminal AI assistants either do everything (scanners, CI gates, dashboards, PR bots) or are a hosted service. Sentinel does one thing well: a fast, cheap, transparent coding chat in your terminal, in the spirit of pi.

  • No servers. The agent loop runs in-process. Sessions are JSON files.
  • No telemetry. Nothing leaves your machine except LLM API calls.
  • No build step. Plain ESM JavaScript + a thin TypeScript TUI, run via tsx.
  • Multi-LLM. One streaming client covers OpenAI-compatible endpoints (OpenAI, Groq, Mistral, DeepSeek, xAI, Together, Fireworks, OpenRouter, Ollama, LM Studio) plus native Anthropic and Gemini protocols.
  • Cost-aware. Every turn prints tokens and USD. Free models default to $0.

Install

git clone https://github.com/KunjShah95/SENTINEL-CLI.git
cd SENTINEL-CLI
npm install
npm link        # optional: puts `sentinel` on your PATH

Requires Node 20+.

Quick start

# 1. Give it a key — Groq's free tier is the zero-cost default
export GROQ_API_KEY=gsk_...

# 2. Chat
sentinel

# 3. Or one-shot from scripts/CI
sentinel ask "why is this test failing?"
sentinel ask -b "fix the typo in src/index.js"    # BUILD mode: may edit files

Local models (Ollama, LM Studio) need no key at all:

ollama serve                    # default host http://localhost:11434
sentinel                        # auto-discovers installed models

What's inside

bin/sentinel.js          entry point (TUI / ask / mcp / --version)
src/cli/main.js          headless command surface (ask, goal, agent run|serve, mini, race, onboard)
src/agent/               the agent: loop, providers, tools glue, cost, sessions, prompt
src/agent/run.js         one run, and the terminal consumer of its event stream
src/agent/serve.js       the same event stream over HTTP + SSE
src/shared/tools/        sandboxed local tools: read, write, edit, glob, grep, bash…
src/shared/connectors/   connector registry, models.dev catalog, credentials, health
src/shared/models/       model registry, effort variants, per-model preferences
src/config/              config store (~/.sentinel.json > $XDG > project-local)
src/tui/                 the Ink (React) terminal UI
mcp/                     MCP stdio server (health, ask, review-diff)
__tests__/               unit tests (node:test + jest)

Connectors, models, and resilience

sentinel auth — one credential store

Twenty-two connectors, one frozen registry, one key store. Adding a provider is a row in src/shared/connectors/registry.js, not twenty lines of copy-pasted discovery code.

sentinel auth                          # what is connected, and where from
sentinel auth login groq               # paste a key
sentinel auth login openai             # or export OPENAI_API_KEY and skip this
sentinel auth logout groq
sentinel auth --json                   # never contains a key — presence only

Keys live in ~/.sentinel/auth.json (mode 0600). Resolution is store first, environment second, so an exported variable is the zero-config path and a pasted key is the explicit one. sentinel auth --json reports source and connected, never the credential — a status listing ends up in scrollback and in bug reports.

sentinel models — what you can call right now

sentinel models                         # connected connectors, grouped, priced
sentinel models --all                   # everything in the catalog
sentinel models --connector anthropic   # one connector
sentinel models --search sonnet
sentinel models --json

Model metadata comes from models.dev, with live discovery against each connector layered on top. That is why prices are real for every provider: a /models endpoint returns ids, not money, so before this every connector except OpenRouter reported $0 and cost accounting was wrong.

Pinned entries win on id collision, so a release newer than the catalog still resolves offline.

sentinel health — is it actually answering?

sentinel health                  # probes every configured connector
sentinel health --connector groq
sentinel doctor --network        # same probes, inside the doctor report

The distinction this exists for: out of quota and rejected credential both fail your next turn, and they are fixed by opposite things — upgrade vs re-auth. Both used to surface as "provider error", which is why provider outages are slow to diagnose. A set key can also be expired or revoked, so key presence was never a health check.

An unconfigured connector is absent, not unhealthy. Anthropic exposes no listing endpoint, so it is reported as inference-only rather than probed with a request that cannot succeed.

Effort variants

A named reasoning level for the same model. Switching effort is not a model switch, so it does not cost you the thread.

sentinel ask "…" -m claude-sonnet-4-6#high
sentinel ask "…" -m claude-sonnet-4-6#fast

Levels: off fast standard high max. In the picker, v / V cycles the highlighted model. Stored per model — high for an architecture change and fast for a rename are different moments.

Budgets are clamped to what the API accepts. Anthropic rejects budgetTokens below 1024 with a 400 that reads like a malformed request, so the floor is enforced before the wire. max is capped at the model's own output limit, because thinking and visible output share one allowance and a budget equal to max_tokens returns an empty reply.

Failover chains

A named group of models that try each other in order when one fails.

# ~/.sentinel.yaml
failover:
  default: gpt-6-luna, claude-haiku-4-5, ollama/qwen3:8b
  gpt-6-astra: gpt-6-sol, claude-haiku-4-5      # a careful chain for the expensive one
SENTINEL_FAILOVER=gpt-6-luna,claude-haiku-4-5 sentinel ask "…"   # one run
SENTINEL_FAILOVER=off sentinel ask "…"                          # disable

Not the same as sentinel race: race runs N models in parallel and keeps the best answer, costing N times the tokens for a quality decision. Failover costs one call and only spends more when a call fails.

What continues and what stops is the design. A malformed request (400) fails identically on every model, so retrying it three times just triples the latency of an error you have to fix — 400 and abort are terminal. 402, 429, 5xx, network failures and 404 move on. 401/403 move on too, because a chain usually spans connectors and a stale key on one should not end a turn a healthy second key could serve.

Two rules the tests pin: no retry after partial text or a tool call (replaying output the user already saw is worse than showing the error), and the chosen model is reported in the turn's finish event so cost stays explainable.

Per-connector spend caps

A single engagement ceiling cannot tell you which key is burning it. Caps are independent ceilings, not a partition of the total.

sentinel budget --connector openai --usd 10    # cap one connector
sentinel budget --connector openai             # what it has spent
sentinel budget --connector openai --usd 0     # clear

Checked after every model call like the engagement budget, and only when the turn opted into the engagement guard.

Bench-verified models

npm run bench and npm run bench:security measure real task completion. Those numbers now surface in /models and the picker as measured evidence.

A score describes this repo, on this machine, at this commit — so it informs a human choosing from the picker and never reorders what autoSelectBestModel picks. Absence of a benchmark is not evidence of a bad model, so unbenchmarked models print nothing rather than an empty column you learn to ignore. Scores from another commit are shown as stale rather than hidden.

Record one with sentinel bench -m <model-id>, and read them back with sentinel bench --scores.

The agent loop

src/agent/loop.js is the whole brain: one turn of user input → stream from the provider → execute tool calls in-process (sandboxed to the project directory) → feed results back → repeat until done or the turn ceiling. It yields typed events (text, reasoning, tool_call, tool_result, receipts, goal, finish, error, and more) that the TUI, the CLI and an HTTP server all consume.

A run stops for exactly one reason at a time, and says which: end_turn, a budget ceiling (usd, tokens, turns, engagement), interrupted, deadline, or an error. That stoppedBy is on the finish event, so a consumer never has to infer why a run ended.

sentinel agent run — one primitive, three consumers

sentinel agent run "add a --json flag to the bench command"
sentinel agent run "find every caller of executeLocalTool" --plan --max-turns 8
sentinel agent run "find the flaky test" --budget 0.50 --time 300

The agent owns the loop, the history, the tools, the budget, and exactly one cancellation source. sentinel agent run embeds it in-process and prints the event stream: the answer streams delta by delta, and every tool call is printed before it runs and its result after it finishes.

Ctrl-C is not a process kill. It asks the run to stop, finishes the tool call in flight, prints what was spent, and exits 130, the same number a shell means by an interrupt. That signal reaches the model stream, every tool call and every HTTP request, so a cancelled run leaves nothing running behind it. --time fires the same signal, so a deadline and a Ctrl-C stop a run by one mechanism and are reported differently.

Budgets are explicit and all four are optional: --budget (USD), --max-turns, --max-tokens, --time (seconds). Hitting a ceiling is a successful exit: the run did what it was told and stopped at the line you drew. A deadline or an error is not.

sentinel ask, swe, goal and the skill runner are all this same consumer, so Ctrl-C works the same in every one of them.

sentinel agent serve — the same run over HTTP

sentinel agent serve --port 8787

curl -N -X POST localhost:8787/runs \
  -H 'content-type: application/json' \
  -d '{"task":"add a --json flag to bench","mode":"PLAN","maxTurns":8}'
# {"runId":"rmv7gqnz1dcu9c"}

curl -N localhost:8787/runs/rmv7gqnz1dcu9c/events     # SSE, live
curl -X POST  localhost:8787/runs/rmv7gqnz1dcu9c/cancel # stop it

A second consumer of the same event stream, and the test of whether that stream is an interface or merely a refactor that suited one caller. It needed nothing added underneath it: no new loop option, no new event, no budget reimplemented. POST /runs/:id/cancel routes to the same controller Ctrl-C uses. A client that connects late still receives the whole run, replayed from the start.

The server binds loopback and refuses a non-loopback bind without --allow-remote, because a process that can run shell commands should not be reachable from the network by accident. It has no authentication, so a non-loopback bind is only correct behind a proxy that does the auth. Request bodies are filtered to a whitelist of run knobs: runTurn and onPermissionRequest are how a caller gets code executed, so an HTTP caller cannot set them.

Tools

readFile, writeFile, editFile, batchEdit, listDirectory, glob, grep, bash, diffFile, undoLastChange, redoLastUndo, searchWeb.

Every tool call is validated against its input schema before it runs, so a malformed call comes back as a readable error the model can correct rather than a partial side effect.

Browser: webSession, webRead, webProbe, webAct — see below. Observation and commitment are separate tools, and webAct cannot run without naming what it is about to affect.

Shared skills and web search

Sentinel discovers standard SKILL.md packages in project-local and global Sentinel, Claude Code, Codex, Agents, and OpenCode skill folders — plus a skills/ directory at the repo root, which is where the skills that ship with Sentinel live. This means a skill installed with skills.sh for one of those assistants is also listed to Sentinel and can be loaded on demand with its skill tool.

Web search is available to the agent through searchWeb. It uses DuckDuckGo by default; set SEARCH_WEB_ENDPOINT to use a compatible internal search endpoint.

  • Writes are sandboxed to the project root (path traversal rejected).
  • bash runs with a timeout and output cap.
  • PLAN/REVIEW modes refuse non-read-only tools; BUILD mode allows everything.
  • Every write creates a checkpoint — /undo and /redo work across turns.

Modes

| Mode | File edits | Shell | Use for | | ------ | ----------- | ------- | --------- | | BUILD | ✓ | ✓ | actually making changes | | PLAN | ✗ | ✗ | questions, code review, exploration | | REVIEW | ✗ | ✗ | diff review with review-focused prompt |

Use /mode inside the TUI. /mode toggles BUILD and PLAN; /mode build, /mode plan, and /mode review select a mode explicitly.

Keybinds — opencode-compatible

Action IDs and default chords mirror opencode v2, so muscle memory carries over: leader is Ctrl+X, the palette is Ctrl+P, Esc interrupts.

| Chord | Action | | ----- | ------ | | Enter | Send. Shift+Enter / Ctrl+J insert a newline — the prompt is multi-line | | ↑ ↓ | Walk prompt history | | Ctrl+A Ctrl+E | Start / end of line (Ctrl+U / Ctrl+K delete to them, Ctrl+W a word) | | Ctrl+P | Command palette | | PageUp / PageDown | Scroll the transcript a page (Ctrl+Alt+U/D half a page, Ctrl+Alt+Y/E a line) | | Ctrl+G / Ctrl+Alt+G | Jump to the first message / back to the live edge | | Ctrl+L | Session log viewer | | Ctrl+/ | Help | | Ctrl+X then… | m models · n new session · b sidebar · l sessions · s status · c compact · u/r undo/redo · x export · e editor · t/d thinking/details · q quit |

Press Ctrl+X on its own for a live cheat sheet of whatever is currently bound. The transcript scrolls and follows the live edge: streaming fills the view on its own, a message that arrives while you are reading history leaves your place, and sending a message returns you to the bottom. The footer shows ⇅ N when you are N lines up. Overrides go in cli.keybinds in ~/.sentinel.json; see src/tui/keybinds.ts for the full action list and src/tui/components/dialogs/help-dialog.tsx for the in-app reference.

sentinel outcome — vague ask in, judgeable contract out

A request like "the sync is flaky" is not a goal: nothing can verify it, so any agent working on it is guessing. outcome turns it into a contract:

CURRENT STATE   what happens today, with the file:line that proves it
TARGET          one measurable delta, not a list of wishes
VERIFICATION    the exact command, and what its exit code means
BLAST RADIUS    what a rollback would touch
ROLLBACK        the concrete undo
UNKNOWNS        what the model had to assume — asked, not guessed
sentinel outcome "the sync is flaky" --plan   # write the contract only
sentinel outcome "the sync is flaky"           # write it, then work to it
sentinel outcome "..." --no-save               # do not touch .sentinel/

The contract is persisted to .sentinel/outcome.json. The worker is briefed with the whole contract including the unknowns it inherited, so it knows which parts of the plan were shaky going in. Then goal.js's tool-less evaluator judges the work against the contract rather than a sentence.

The evaluator has a third verdict, unknown, for when the contract itself cannot be judged — an unmeasurable TARGET, or VERIFICATION never run. That verdict is terminal: retrying identical work cannot make an unjudgeable condition judgeable, so the turn ends and says which field is the problem.

sentinel watch — the standing FDE

Everything else here runs once and ends. An FDE is there on Tuesday when the thing they shipped on Monday starts failing. watch is that difference:

sentinel watch "keep the sync green" \
  -t "command:npm test" -t git --goal "npm test exits 0"

# from another terminal, mid-run:
sentinel steer "also check the retry path"

| Trigger | Fires when | | ------- | ---------- | | command:<cmd> | the command exits non-zero — you are woken by breakage, not by green | | command:<cmd> --when always | regardless of exit code | | file:<path> | its mtime moves | | git | HEAD moves | | interval:<ms> | time passes | | once | immediately, then never |

Steering is the part that makes this a presence rather than a cron job. The queue is a file (.sentinel/steer.jsonl), so sentinel steer works from another terminal, in another process, and the instruction lands on the next tick as a priority over the original task. That is roadmap item #16.

Three guards make an unattended loop safe to leave running:

  • The engagement budget is checked before every single wakeup. A standing loop that ignores its ceiling is just a way to spend money quietly.
  • Backoff. A tick that does not make progress doubles its wait, up to 15 minutes, and five in a row stops the loop. "Progress" is deliberately weak: the goal was met, or the agent said it wrote something. A tick that only read files has not moved the engagement.
  • Failures are recorded, not fatal. A provider that throws ends that tick, not the watch.

State lives in .sentinel/watch-state.json (ticks, backoff, last trigger).

Blast-radius gate

A forward-deployed engineer does not decide a change is safe because the tool said yes. On a path they do not own, they state the file and line that justifies the change and name the rollback before touching anything. Sentinel now does that automatically for the paths where being wrong is expensive:

| Challenged | Why | | ---------- | --- | | db/migrate/**, *.sql | a migration is rarely undone by reverting it | | .github/workflows/** | this gates every merge | | prisma/schema.*, *schema.json | changing a schema changes everything under it | | package-lock.json, yarn.lock, … | a lockfile edit is invisible in review | | src/auth/**, src/billing/**, **/rbac* | the code you cannot roll back | | Dockerfile, docker-compose*, Makefile | build and deploy definitions | | infra/, terraform/, k8s/ | infrastructure definition | | .sentinel/config.yaml | the project's own permission config |

The gate blocks once per path per turn. The first write is refused with the requirement spelled out — the file:line that justifies it, and the exact rollback — and the agent's next move must include both before the write lands. After that the path is open for the rest of the turn.

That is deliberate, and it matches the Stop hook's forced-verification pattern. A gate that blocks forever trains people to disable it; a gate that asks once and records the answer is a habit.

The trade is explicitly toward over-asking: lib/auth-utils.js gets challenged even though it is a utility, because the cost of a false positive is one prompt and the cost of missing real billing code is not recoverable.

sentinel budget — spend that outlives the process

maxCostUsd guards a single turn and cost.js totals are in-memory, so neither can answer the only question a buyer asks: what has this cost so far. An engagement is the FDE-shaped unit — a budget, a deadline, a stop condition — persisted per project so a week's work is still measured on Friday.

sentinel budget --usd 25 --deadline 2h --condition "npm test exits 0"
sentinel budget            # active  ░░░░░░░░  $12.40 of $25.00 (50%) · 1h 59m left
sentinel budget --history  # recent turns and their spend
sentinel budget --clear    # remove the ceiling; spend history is kept

Once set, ask, goal, and outcome all honour it — you set it once and every later run is gated. The loop checks after each model call and stops hard at the ceiling rather than letting one more call land first.

State lives in two gitignored files: .sentinel/budget.json (the ceiling) and .sentinel/spend.jsonl (one append-only line per turn, so a crash mid-write loses one row, not the log).

Two deliberate choices: spend recorded before the budget was set does not count against it, and a turn that finishes in the same millisecond the budget was created does — a ceiling should fail toward charging you, not away.

sentinel handoff — the runbook, not the diff

Every turn is already recorded to .sentinel/trajectories/*.jsonl. That data has been write-only. handoff turns a recording into the artifact an engagement is actually judged on — something the customer's team can pick up:

sentinel handoff --list          # runs that can be handed off
sentinel handoff <runId>         # write .sentinel/HANDOFF.md
sentinel handoff <runId> --stdout
sentinel handoff a b c --stdout  # several runs, merged

The runbook has five sections: what changed, what was verified, what was tried and rejected, claims to distrust, and what is still fragile.

The second and third are the point. "A green test does not prove the fix is the right one" and "we tried patching the parser incrementally and it broke on nested arrays" are exactly what the next person needs and exactly what nobody writes down. Dead ends are derived mechanically: any command shape that failed, or that ran three or more times, plus any claim the receipts system could not back with a passing command.

No model, no API key. The model already ran once; asking it to summarize its own run again is how confident, unverifiable prose gets into a runbook. A run where nothing exited 0 says so in bold.

Risk ledger — permission by novelty

"Allow bash for this session" is one grant covering git status and npm publish alike, which is either uselessly strict or uselessly loose. The ledger records command shapes per repo in .sentinel/risk.json and grades each one:

| Level | Meaning | | ----- | ------- | | green | provably read-only, or a shape already approved in this repo | | yellow | a new shape that is not destructive → asked, with the shape named | | red | destructive, or reaches outside the workspace → always asked, never remembered as safe |

sentinel risk                     # list approved shapes
sentinel risk "npm publish"       # how would this grade here?
sentinel risk --forget "npm publish"

Two properties matter more than the grading itself:

  • Flags are kept, values are not. git commit -m "a" and git commit -m "b" are one shape, so the second does not ask. But git push --force is a different shape from git push, and --force is never collapsed into a placeholder.
  • The subcommand is part of the verb. git commit and git push never share a shape, so approving a commit cannot authorize a push. Same for npm run vs npm publish, docker build vs docker push.

A missing or corrupt ledger is treated as empty, which grades everything novel as yellow. An approving ledger that does not exist is not consent.

The lead still sees a shell command the first time — the ledger narrows what is asked, it does not remove asking.

sentinel audit — was the thing that ran the thing you approved?

Every harness rests on an assumption nobody checks: that the action a human approved (A) is the action that gets executed (A'). When they differ, nothing notices at the time. sentinel audit replays a recorded run and reports the gap, split into the classes it can actually distinguish:

| Class | Example | | ----- | ------- | | Scope | approved a read, a write ran; or a worktree was not the one approved | | Argument | same command shape, different arguments — the cost of shape matching | | Temporal | the grant went stale: writes landed between approval and execution | | Tool | a different tool ran than the one granted | | Delegation | a subagent executed above its parent's rung | | Semantic | not assessable from recorded fields — reported as such, never as clean |

sentinel audit                     # the most recent run
sentinel audit --last 5           # five runs, newest first
sentinel audit --list             # what has a trail
sentinel audit <runId> --json

Exit 2 when a gap is found, 0 when clean, 1 when there is no trail. The distinction between 0 and 1 matters: "audited and found nothing" and "nothing to audit" look identical otherwise, and only one of them is evidence.

Every approved tool call is recorded in .sentinel/audit/<runId>.jsonl as a paired grant and dispatch, keyed by tool call id. The grant is written before the tool runs — a crash mid-dispatch then leaves a record of an action nobody approved, which is the finding this is for.

Read-only over recorded JSONL: no model, no network, no credentials. Semantic is named in the taxonomy with a count of zero because those divergences leave every recorded field unchanged — the tool states the limit of its own coverage rather than implying a clean result it cannot support.

Browser tools — reading, resolving, then committing

Every safety primitive above works because a file action has a nameable target. risk.json grades a command shape, audit compares workdir, the blast-radius gate matches a glob. A browser click has no such name: click(selector) is the same verb whether it opens a settings page or confirms a charge. Novelty is not the risk variable there — context is — so a shape-based ledger would just learn from repetition and eventually green-light whatever it saw most often.

So the browser path does not add a computerUse tool. It splits observation from commitment, exactly as the file tools already do:

| Tool | Does | Prompts | | --- | --- | --- | | webSession | open/list/revoke/close a leased browser session | on open | | webRead | navigate and read a page | no | | webProbe | resolve what a click would do — role, accessible name, form target, endpoint, and a suggested reversibility class | no | | webAct | perform a probed action, given an effect descriptor | yes, always |

webProbe is the one that matters. Without it the agent clicks blind and infers what happened from the resulting page, which is what makes browser agents unreviewable. With it, it resolves first, reads what the button actually calls itself and where it would submit, and asks.

sentinel webeffect grades a proposed action without a browser at all:

$ echo '{"action":"send invoice 9","origin":"https://billing.example.com/invoices/9",
         "resourceId":"/api/invoices/9/send","reversibility":"external",
         "recipient":"[email protected]"}' | sentinel webeffect -f -

external  send invoice 9
Affects someone else — [email protected]. They will see this and cannot un-see it.

The effect descriptor

webAct will not run without one. This is the mechanism that makes the Semantic gap class checkable: audit reports Semantic as unverifiable precisely because those divergences leave every recorded field unchanged, so the fields it needs are made to exist before the effect instead of being recovered afterwards.

{ action, origin, resourceId, reversibility, recipient?, compensatingAction? }

Irreversibility is a currency, and it is spent against a ceiling the way money is in sentinel budget:

| Class | Means | Required | | --- | --- | --- | | reversible | in-product undo exists | — | | compensable | a compensating action exists | compensatingAction | | absorbing | cannot be undone | — | | external | a third party will see it | recipient |

An undeclared class is not treated as mild — it grades unknown, which outranks external, and the action is refused. A session's irreversible ceiling defaults to 0: irreversible actions are something you opt into per session.

Three refusals stand between a descriptor and a click, and none is skippable:

  • Drift. The action is re-probed immediately before it fires. A page that re-rendered since the probe, a selector that now points elsewhere, or an action that landed on a different origin is refused.
  • Wrong account. If the descriptor names an account and the page shows a different one, the action is refused. The right page under the wrong identity is the failure no URL reveals.
  • Rung. A readonly subagent may read and probe but never act, and absorbing/external effects are denied at every rung below inherit — a teammate works in its own worktree, and there is no worktree for a sent message.

A granted descriptor and the descriptor that actually acted are recorded separately, so sentinel audit gained an Effect class: an action that fired on a different resource than it was approved for is now a finding rather than an invisible one. Reversibility maps onto the existing intent ladder (reversible → read_only, absorbing → state), so a click that mutated under a reversible grant also trips the existing Scope check.

Containment

Sessions are single-purpose and leased. Opening one requires an explicit origin allowlist — an agent holding a logged-in session and the whole internet is not a browsing tool. Each gets a dedicated, empty profile under .sentinel/web/profiles/; your credentials are never imported, so if the task needs an identity you log that profile in while watching it happen. Leases expire, and revoke cuts a session off mid-task. Driving is CDP over a Node-22 global WebSocket, so there is no browser-automation dependency and no Chromium download; when no browser is found, that is reported as a capability failure rather than an empty page.

Deliberately absent: pixel/screenshot targeting (a pixel diff cannot answer whether a click hit Delete or Edit), type as a standalone action (keystrokes are cheap; the submission is the irreversible part, so that is what needs a descriptor), and self-verification of a browser action — webAct returns a verification note pointing at an authoritative endpoint, because a page rendering "done" is not a receipt.

sentinel onboard — the week-one survey

A new engineer's first days go to comprehension, not commits. onboard answers the questions a new joiner actually asks, from files already on disk:

sentinel onboard                       # print the survey
sentinel onboard --json                # raw structured data
sentinel onboard --remember            # store a project memory record
sentinel onboard --todos               # seed .sentinel/todos.json with the gaps
sentinel onboard -o ONBOARDING.md      # write it to a file to commit

It reports entry points, what gates the merge (workflow names and triggers), test topology, churn hotspots from git history, ownership per directory, and risk areas — source files that change constantly with no test covering them. Generated files (lockfiles, bundles) are reported separately rather than crowding out real source, and deleted-but-churned files are shown as history rather than as places to go make changes.

Exit code is non-zero when the survey finds anything a new engineer should know first, so it works as a CI check.

No model, no API key, no network. The survey is deterministic filesystem and git log analysis, so it runs anywhere and gives the same answer twice.

sentinel memory — cross-agent memory

Sentinel keeps its own Markdown records in .sentinel/memory/. It can also read and write the cross-agent store (agentmemory), which every assistant on the machine shares — a decision made in Cursor is recallable from SENTINEL, and vice versa.

sentinel memory                                  # is it reachable?
sentinel memory "how do we do auth"              # recall
sentinel memory --remember "auth uses jose" \
  --concepts auth,jwt                            # store

The server is optional. Start it in its own terminal with:

npx -y @agentmemory/agentmemory@latest

Set AGENTMEMORY_URL if it is not on localhost:3111, and AGENTMEMORY_SECRET if you put it behind auth.

Two tools back this: memoryRecall is read-only (available in PLAN and REVIEW), memoryRemember is a write. Recall results are injected into the system prompt as their own trailing section, capped and relevance-ordered — and when the server is down, that section is simply absent rather than an error. Recall is time-boxed at 2.5s and never blocks a turn.

Point AGENTMEMORY_URL at a remote instance to share memory across machines.

sentinel heal — detect and repair drift

Things break quietly. An assistant upgrades and rewrites its config, dropping the SENTINEL entry with no error anywhere. A memory index stops matching the records it summarizes. A half-written todos.json makes the todo tool fail on every call. heal finds all three.

sentinel heal              # report only — read-only, always safe
sentinel heal --fix        # repair (every removal is quarantined, not deleted)
sentinel heal --fix --dry-run

Three classes of repair:

| Problem | Repair | | --- | --- | | Assistant config lost or changed the SENTINEL entry | re-merge it, with a backup | | MEMORY.md disagrees with the records on disk | rebuild the index | | Corrupt todos.json / outcome.json / budget.json / risk.json | quarantine to .corrupt-<ts> | | Memory record with no name: frontmatter | reported, not auto-fixed | | Config that isn't valid JSON | reported, never rewritten |

The last two are deliberate. A record with no name: might be a hand-written note worth keeping, and a config we can't parse may hold settings we cannot reconstruct — silently replacing either would destroy user data. Repairs are idempotent, so a second heal reports clean.

sentinel update — check for updates

Reports drift across three independent things, then installs only on --yes:

sentinel update              # report: package, assistants, MCP servers, skills
sentinel update --yes        # install the newer SENTINEL if one is published
sentinel update --skills --yes   # refresh skills via the skills.sh CLI

sentinel update --yes runs npm install -g sentinel-cli@latest. Nothing is installed without that flag, and a registry failure is reported rather than treated as an update. The package swap only applies to a globally installed copy — a npx-invoked one is ephemeral and will not change.

TUI commands

/help /model [id] /models /session [list|switch|delete] /commit /diff /undo /redo /export /health /compact /setup /editor /thinking /details /clear /new

Plus ! <cmd> for shell passthrough and @agent <msg> for agent personas. Ctrl+X opens the leader-key menu; Ctrl+S toggles the session panel.

MCP server

Expose Sentinel to Claude Desktop, Cursor, or any MCP client:

sentinel mcp

Tools: sentinel_health, sentinel_ask, sentinel_search, sentinel_skills, sentinel_mcp_servers, sentinel_review_diff. Transport is stdio — add it to your client config:

{
  "mcpServers": {
    "sentinel": { "command": "npx", "args": ["-y", "sentinel-cli", "mcp"] }
  }
}

Connect to your assistants

sentinel connect detects installed assistants and registers the MCP server with each one, merging into their existing config without touching other entries:

sentinel connect --list          # what's detected
sentinel connect --dry-run       # show the change, write nothing
sentinel connect                 # apply to every detected assistant
sentinel connect -t cursor       # just one
sentinel connect --scope project # write ./.mcp.json instead of user config
sentinel connect --remove        # undo

Understood targets: claude-code, cursor, windsurf, zed, opencode, codex, vscode-copilot. Each write takes a .sentinel-backup first.

Use external MCP servers

Sentinel is also an MCP host. Configure servers in ~/.sentinel.yaml:

mcpServers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
  linear:
    url: https://mcp.linear.app/sse
    type: sse

Their tools are exposed to the agent as <server>__<tool> (e.g. github__create_issue) — namespaced because different servers commonly expose the same tool name. A server that fails to connect is skipped, not fatal.

sentinel mcp-status              # what's reachable, and what it exposes
sentinel mcp-status --refresh    # reconnect

External tools are treated as read-only and never receive a write grant.

Web search

searchWeb uses a provider chain — the first healthy provider wins, and a failing one is skipped rather than surfaced:

| Order | Provider | Key | | --- | --- | --- | | 1 | Exa (semantic, good for code/docs) | EXA_API_KEY | | 2 | Tavily (agent-tuned) | TAVILY_API_KEY | | 3 | Brave | BRAVE_API_KEY | | 4 | DuckDuckGo | none |

With no keys set, search still works via DuckDuckGo. fetchUrl retrieves and extracts a page's readable text (scripts, styles, and nav stripped) so the model isn't billed for markup.

Skills

Skills follow the skills.sh SKILL.md convention. Sentinel reads skills/ at the repo root first (where its own shipped skills live), then .sentinel/, .claude/, .codex/, .agents/, and .opencode/ — project and global — so a skill installed by any other assistant is available without copying it.

sentinel skills list
sentinel skills install mattpocock/skills     # delegates to `npx skills add`
sentinel skills find "tdd"
sentinel skills run reproduce-fix-verify auth.js   # start a turn with it loaded
sentinel skills run review --print                # show the expansion, no model call

skills run is /name for anywhere you are not typing into a composer — a script, a shell, a CI step. Defaults to read-only PLAN mode; pass --build to allow edits.

The skill listing injected into the system prompt is capped and relevance-ranked against your request, so a large library doesn't dominate every turn.

Invoking one. The model reaches for a skill automatically when it matches your request. You can also type it: /review auth.js works for skills and for prompt templates, with the same argument parsing — a template wins if both exist, so an older project never has /review change meaning underneath it.

Arguments. A skill body can take $1, $ARGUMENTS, ${1:-default} — the same placeholders /name prompt templates use. The model fills them from the args field of the skill tool call, and you fill them by typing after the slash command. argument-hint in the frontmatter tells both of you what to pass, and shows up in the listing and in sentinel connect --skills --list.

<!-- .sentinel/skills/review/SKILL.md -->
---
name: review
description: Review a diff against a focus area
argument-hint: <file>
disable-model-invocation: false
---
Review $1 (or $ARGUMENTS if none given), focusing on error handling.

disable-model-invocation: true keeps a skill out of the model's system-prompt listing while leaving it reachable as /review. Use it for a workflow you want to run deliberately rather than have triggered by an unrelated request.

Restricting a skill's tools. allowed-tools narrows the rest of that turn:

---
name: audit
allowed-tools: readFile, grep, codeMap
---

While the skill is loaded, a call to anything else is refused with the reason and the permitted list — the tool is not silently removed, because the model was already shown it and a vanished tool reads as a broken agent. Two loaded skills intersect, so an unrestricted skill cannot undo a restricted one's declaration. skill itself is always permitted, so a skill can always load another.

Delegating one. spawnAgent and spawnTeammate both take skills, so the agent you delegate to follows the workflow instead of describing it back to you:

{"tool": "spawnAgent", "prompt": "audit the auth layer", "skills": [{"name": "audit", "args": ["auth.js"]}]}

Bundled scripts. A skill may ship scripts/ alongside SKILL.md, and the skill tool lists them when it expands the body. Running one is a separate tool, runSkillScript, because it executes a file that came from a registry directory rather than from you:

// the model calls: runSkillScript({ name: 'review', script: 'scripts/diffstat.sh', args: ['--stat'] })

Traversal outside the skill directory is refused at path resolution, before the shell. runSkillScript is classified as shell, so it is refused in PLAN, REVIEW, SCAN and FIX modes and defaults to asking — the same treatment bash gets. That separation is the point: a read-only tool that could run code would hand every planning turn the ability to execute installed code.

Configuration

Keys resolve in order: env var → ~/.sentinel.json → project .sentinel.json.

| Provider | Env var | | ---------- | --------- | | Groq (free tier) | GROQ_API_KEY | | OpenAI | OPENAI_API_KEY | | Anthropic | ANTHROPIC_API_KEY | | Gemini | GEMINI_API_KEY | | DeepSeek | DEEPSEEK_API_KEY | | Mistral | MISTRAL_API_KEY | | xAI | XAI_API_KEY | | OpenRouter | OPENROUTER_API_KEY | | Together / Fireworks / Perplexity | TOGETHER_API_KEY / FIREWORKS_API_KEY / PERPLEXITY_API_KEY | | Ollama / LM Studio | OLLAMA_HOST / LMSTUDIO_HOST (no key needed) |

The TUI /setup dialog writes the config file for you. See .env.example.

Cost control

  • Default model is a free-tier model (openai/gpt-oss-20b via Groq).
  • Context auto-compaction keeps long sessions under the 40k-token budget.
  • sentinel ask prints in/out tokens · $ · model after every run; -q silences it.
  • Tool results are truncated hard (20k chars) before they hit your context.

Development

npm run lint         # eslint
npm run typecheck    # tsc over the TUI
npm test             # node:test suites + jest suite
npm run release:check  # all three

Changelog

v3.5.0 — Connectors, failover, and a skills system that can restrict itself

60 files, ~8.1k lines. Two themes: the provider layer stopped assuming one provider, and the skills layer stopped assuming one registry.

Providers and connectors

  • One connector registry for providers, the models.dev catalog, and the auth store — previously spread across a provider table, a discovery module and a per-provider key check.
  • sentinel health performs live connector probes that distinguish a bad key from no quota left, which are the two failures a 401-vs-429 conflation hides.
  • Named model failover chains: if a provider dies mid-turn the turn moves to the next model in the chain instead of ending.
  • Effort variants per model, per-connector spend caps, and bench-verified badges on models whose numbers were actually measured.

Skills

  • skill({names: [...]}) stacks several workflows in one call, in the caller's order. Two separate calls used to return as unordered parallel results, so which body landed first was a race.
  • allowed-tools is enforced. A skill may narrow the rest of its turn; the call is refused with the binding skill named rather than the tool silently disappearing, because a skill loads mid-turn and a vanished tool reads as a broken agent. Two loaded skills intersect, so an unrestricted one cannot undo a restricted one's declaration.
  • A skill may bundle executable scripts, run with runSkillScript. That is a separate tool classified as shell — a read-only skill tool that could run code would hand every PLAN-mode turn the ability to execute installed code.
  • spawnAgent and spawnTeammate both accept skills, so a delegated agent follows the workflow instead of describing it back to you.
  • /name args resolves prompt templates and skills through one syntax and one argument parser, and sentinel skills run <name> does the same from a shell, a script, or CI.
  • disable-model-invocation withholds a skill from the model entirely while leaving it reachable by name. This needed hyphenated frontmatter keys — the old parser silently discarded every one of them.
  • Skills ship in skills/ at the repo root, tracked and in the npm tarball.

Correctness

  • Tool inputs are now validated before dispatch. toolInputSchemas had ~200 lines of validators that were written, exported, referenced from every contract, and never invoked. Turning them on immediately exposed a real bug: the string validator projected the bare string rather than { [field]: value }, so every readFile would have received 'src/x.js' where it expected { path }.
  • The skill listing no longer overflows its own character cap. The overflow note was appended after the last count, so a real 208-skill install produced 2113 chars against a 2000 cap while every individual measurement was correct.
  • git failures are no longer printed to the user's terminal: running Sentinel outside a git checkout printed fatal: not a git repository once per turn.
  • providerOptions is threaded to the wire; thinking was configured and never actually sent.

Tooling

  • npm run verify:stages — asserts all 13 stages of the CodeCrafters "Build your own Claude Code" syllabus against the live code. Kept out of release:check because two stages shell out and would assert something about the host too.
  • npm run check:version — the version lived in six places, five of them copies. Now one source (src/version.js); this resolves every surface and fails if any disagrees. The previous check-by-grep reported package.json's own dependency versions as mismatches, so it asks what each surface reports instead.
  • scripts/tree-quiet.mjs — waits for file writes to pause before declaring a tree committable, for when more than one agent is working in one checkout.

v3.4.0 — Context.dev web context + cheaper turns

New

  • searchWeb / fetchUrl can now use Context.dev: it renders JavaScript and bypasses bot walls, so client-rendered sites return real content instead of an empty app shell. Opt-in via CONTEXT_DEV_API_KEY; with no key, search still falls back to DuckDuckGo (no account) and fetchUrl fetches directly.
  • fetchUrl gained prefer: "direct" to force the free local fetch and spend no credits.
  • The hosted Context.dev MCP server can be registered with your other assistants: sentinel connect --mcp context. Writes only the URL — no secret is ever put into an assistant config.
  • sentinel contextdev — status of the integration: key presence (length only, never the value), available search providers, MCP sign-in state, and --check / --url for a live probe.
  • /contextdev slash command in the TUI.
  • Sentinel's own MCP client now supports OAuth for remote servers (mcp-oauth): tokens stored 0600 under ~/.sentinel/mcp-auth, never in a repo or assistant config, with --logout.

Fixed / cheaper

  • The skill listing was 96% of the system prompt — every installed skill's full description, re-sent on every model call. It is now capped (SKILL_LISTING_CHAR_CAP) and ranked by relevance to the request. Measured on a 208-skill machine: 14,375 → ~529 tokens per iteration.
  • trimMessagesForBudget re-serialized the whole conversation inside two nested loops (103 full JSON.stringify passes, ~94ms per model call). It is now incremental and byte-identical: ~1.3ms.
  • The usage fallback no longer serializes the full conversation on every iteration; it is memoized per turn.
  • git rev-parse for the environment section ran a subprocess per turn build (~52ms); it is now cached per directory, and the assembled system prompt is memoized.
  • A bad/expired CONTEXT_DEV_API_KEY is reported as an auth problem, not as "no match".

Benchmarks

  • npm run bench:context reproduces all of the above.

v3.3.0 — sentinel doctor

  • sentinel doctor — pre-flight checks before the first turn: Node runtime (against the Node 20 floor), working directory, data-dir writability, provider credentials, host memory, and the shell tool layer (including that destructive patterns are still classified)
  • Exits non-zero only on a real failure; warnings are information for a human, so the Windows PATH note does not make the command useless
  • Offline by default — --network opts into probing local model servers, because a health check that needs the internet to tell you the internet is down is useless
  • --json for scripting
  • Provider check counts the config store as well as the environment, since that is what the runtime actually reads; key values are never printed, only provider and variable names
  • engines.node >= 20 is now declared in the package manifest

Website

  • /series courses with an episode pager, plus a batch of keyword-mapped posts

v3.2.1 — TUI overlays were broken

The bug: dialogs (provider setup, model picker, theme picker, logs, help, permission) and the command palette were rendered as a normal-flow sibling after the session. The session filled the terminal, so every one of them was pushed off the bottom of the screen. Worst case was first run: with no provider key set, the setup dialog opened invisibly while the prompt was already disabled, so the app looked completely frozen — nothing you typed did anything.

Fixed

  • Dialogs and the command palette are now absolutely positioned overlays sized to the terminal, painted over the session (opencode's modal behaviour) instead of below it
  • The root is pinned to the terminal size, so the prompt and footer stay put instead of being pushed off by a long conversation
  • Toasts render as a pinned strip; previously every success and error message was drawn underneath the app and never seen
  • The provider picker and model picker window their lists to what fits, so entries are no longer squeezed or clipped out of a short terminal
  • Esc no longer stops the running turn while a dialog or the palette is open
  • Dialog context value is memoized; a fresh identity every render drove a setState loop ("Maximum update depth exceeded")
  • Removed the duplicated dialog title (the overlay already frames it)
  • Added npm run tui:probe, a headless harness that renders the real TUI and prints the frame a user sees — this is what caught the above, since the snapshot tests only render a fixture

v3.2.0 — The forward-deployed engineer

New commands

  • race — best-of-N: N agents solve the task in parallel git worktrees; your --check command picks the winner
  • watch / steer — a standing agent that keeps working when tests fail, a file changes or a commit lands, steerable from another terminal
  • goal — work in BUILD mode until a shell condition is verified (e.g. "npm test exits 0")
  • outcome — turn a vague ask into a verifiable contract (CURRENT / TARGET / VERIFICATION / BLAST RADIUS / ROLLBACK)
  • replay — re-run recorded turns against the current harness and model, then diff behavior
  • handoff — generate a runbook from recorded runs: what changed, what was verified, what was rejected
  • budget — set the engagement budget, deadline and stop condition
  • risk — grade a command against this repo, backed by a ledger that learns
  • onboard — deterministic repo survey: entry points, what gates the merge, churn, ownership, risk
  • mini — one-tool bash-only agent for small, scriptable tasks
  • webeffect — grade a proposed browser action: reversibility class, rollback, and whether a session permits it

Agent

  • Blast-radius gate: a risky write is blocked or re-asked based on measured impact
  • Harness ports: skills, todos, subagents and hooks
  • Stop hook fires only when the project actually has tests (no more "run the tests" in a repo with none)
  • A solo lead can no longer message itself; it answers the user directly

TUI

  • Theme picker, shared chat components and a render-snapshot harness
  • GFM tables render correctly in markdown
  • Provider errors are one readable line with a next step (401 → /setup, 429 → wait or /model, …)
  • Working-directory recovery: the TUI runs its tools in your project even when its own package.json is malformed
  • Session files written by older builds no longer crash the session panel

Website

  • Docs refresh, SEO foundation and a keyword-mapped blog

v3.1.0 — Bug-fix release

Provider fixes

  • Ollama models no longer get a 404 — ollama/model:tag prefix is stripped before the API call
  • Anthropic input token count was always 0 — now captured from message_start event
  • sentinel_ask MCP tool no longer throws Unsupported model: undefined when model param is omitted

TUI / slash commands

  • /help was silently ignored — now registered and works
  • Slash command autocomplete rewritten: ↑↓ navigate, Tab complete, Esc dismiss, single-match Enter executes immediately
  • !shell commands now clear the input bar after execution
  • /diff file.ts now correctly passes the path as a file, not a branch
  • /export and /share no longer overwrite each other (unique timestamps in filenames)
  • /commit no longer races the mode toggle against the running stream
  • /redo now correctly restores the post-edit state (was restoring pre-edit — effectively a no-op)
  • Model picker j/k vim keys no longer block typing in the search box
  • Model picker navigation stays highlighted past item 17 (scroll window added)

Agent loop

  • diffFile schema field renamed newString → newContent to match the implementation
  • SWE mode: assistant messages with tool_calls but empty text content are no longer dropped (broke multi-turn loops)
  • SWE mode: assistant messages with undefined/null content but valid tool_calls now preserved correctly
  • spawnAgent subagent no longer silently fails with Unsupported model: undefined
  • batchEdit uses pre-validated file content for each operation — no more stale reads mid-batch
  • Tool messages with missing tool_call_id in SWE mode are skipped instead of sending a bad API request

Permissions & security

  • ask policy now correctly blocks tools in headless CLI mode instead of silently allowing everything
  • Tool permission priority was inverted (category defaults overrode per-tool policies) — fixed
  • FIX mode was blocking searchWeb instead of runTests — fixed

Sessions & state

  • Messages with null or undefined id no longer collide in the session store (silent message loss)
  • autoCompact interval no longer resets every time the agent starts/stops streaming
  • Compaction loop guard added — setMessages no longer re-triggers compaction immediately
  • microcompactMessages moved from render-time to useMemo (eliminates O(n²) per-render cost)
  • submit callback no longer re-created on every streamed delta

Dialogs

  • DialogProvider no longer double-handles Escape (called close() twice alongside child dialog)
  • Stop button (Escape while loading) now wired and functional

License

MIT © Kunj Shah. See LICENSE.


Case study

The full write-up of SENTINEL CLI (problem, architecture, trade-offs and results) lives at kunjshah.in/projects/sentinel-cli.

Built by Kunj Shah, AI engineer.