Arjun0014/project-sentinel

Mission control for long Claude Code runs: context, run progress and the prompt cache at a glance, Autopilot handoffs before the context fills up, guardrails, and a calm view of what Claude did. For the terminal CLI and for local sessions in Claude Desktop's Code tab.

Project Sentinel was called Control Room until 1.4.0; its panel still is, and /cr still opens it. An existing install moves over by itself (see Coming from Control Room).

One plugin gives you:

• a calm status bar above the prompt, a mission HUD: what the run is doing or waiting for, in words, and only what needs a look; below it the run's instruments (work, context, the prompt cache, the plan's five-hour usage), each its own shape; above it, while subagents run, one line per agent
• the Control Room panel, docked beside the conversation
• Autopilot (Context Autopilot): Claude writes handoff notes, the context is cleared, and Claude carries on in a fresh one, before this one fills up; then Project Sentinel checks what the handoff left and what the fresh context picked up
• Cache Guardian: the prompt cache in view, why each rebuild happened and how to avoid the next, model switches confirmed before they throw a large cache away, and Keep warm, which holds the cache while you are away
• run progress that survives those handoffs, with evidence for each verified milestone (it says when a later change made a verification stale), and an Activity view that leads with what needs a look, with its own views: Summary, Operations, Agents and Tool calls
• Operations, the run over time: work you queue for Claude for later, decisions Claude leaves for you instead of stopping, watchers that park the run until a result is due and then wake it, a Cold Resume Guard that asks before a large conversation whose cache has lapsed is re-read, the agents actually running, and an optional run budget
• answer styles: brief, Simplified Technical English, mission-control status calls, or a quest log with XP for verified progress
• policies for effort, finishing the job, models, subagents, machine load and risky actions, with profiles that set everything at once. A fresh install starts opinionated (Autopilot at 70%, Frontier Max at Extra High) and says so once; an existing install keeps exactly what it had
• Kit, if you like: a small Claude-orange creature above the status bar that shows what Claude is doing, and answers a click

Status: 1.7.0. Project Sentinel is built on Claude Code's function-hooks plugin API ("mods"), which is still early access and may change between Claude Code releases. It is verified on Claude Code 2.1.289 (the minimum), 2.1.293, 2.1.295 and 2.1.296 (the CLI) on Windows 11. See Compatibility.

• Screenshots
• Features
• Requirements
• Install
• Using Project Sentinel
• Profiles
• How the systems interact
• Security and privacy
• Compatibility
• Limitations
• Development
• License

Further reading: Configuration · Troubleshooting · Design · Architecture · Security · Changelog · Contributing

Overview: the run, then its three lifecycles (work, context and the prompt cache), each with how it starts over.	Activity leads with the run: its milestones, where the turn's time went, and what needs a look, with the line of output that says why.
Context: when Claude hands off, and what happens when it does.	Further down Context, the prompt cache: what it holds and for how long, Keep warm, and each rebuild with what would have avoided it.
Further down Activity: each check's runs as dots, and every changed file by kind with its diffstat, each opening its diff in place.	Answer styles: how Claude writes to you, each with a line on what it means. The Quest log: XP only for progress Project Sentinel can count, never for lines or tool calls.

_{Control Room 1.3.0 in a 150-column Windows console (Claude Code 2.1.293), with the panel docked beside the conversation (the Answer style and Quest cards are from 1.1.0; they did not change). The work is a scripted turn played by the development-only demo driver: Claude Code ran every tool call in it for real (a test that fails and is fixed, new code with its test, a lint script that does not exist), but no model wrote the words, and the token counts are scripted, a model switch halfway through included. Claude Code reports no cost for them, so the cost reads $0.00 (with a + after a cleared session whose cost was not reported).}

Context, mid-run: one handoff behind it, $115.93 so far.	Behavior: each system on its own card.	Setup: exactly what changed since the profile.

_{Control Room 1.0.1 in Claude Desktop's Code tab, from real sessions. On Desktop the controls are native buttons and popups and the meters are drawn as graphics. What came after (the two-line status bar, Activity's charts, the answer styles, the Cache card and Kit) has not been photographed on Desktop yet.}

In the terminal: two items queued for the fresh context that watcher W-1 will start when it wakes the run at 17:41.	On Desktop, in the preview: a decision Claude left for you, a button per option and a field for your own words; below it the queue, the watcher form, the agents and a run budget.

_{Project Sentinel 1.6.0. The terminal images are captures of Claude Code 2.1.295 in a 150-column Windows console, set up with /cr commands alone (/cr queue --handoff, /cr watch in 2h … --fresh, /cr budget $30), so no model turn ran. The Desktop images are drawn by tools/desktop-preview from the trees the plugin draws on the desktop surface, with the app's own layout rules; its font and colors are close guesses, and Operations has not been photographed in the app yet.}

Cost is shown only as Claude Code reports it, and "—" means it was not reported. Progress is milestones done of the total Claude listed. The cache's expiry, hit ratio and causes are derived from the token counts Claude Code reports, and the panel says so. Nothing is estimated.

• Claude Code 2.1.289 or newer with function-hooks plugins (mods). Check with claude --version.
• The terminal CLI, or Claude Desktop's Code tab for local sessions.
• Nothing else. Project Sentinel has no runtime dependencies and no build step, because Claude Code loads its TypeScript directly.

Add the repository as a marketplace, then install:

claude plugin marketplace add Arjun0014/project-sentinel

claude plugin install project-sentinel@control-room

The marketplace keeps its name, control-room; the plugin in it is project-sentinel. Or do both from inside a session (Claude Code 2.1.275 or newer): /plugin install project-sentinel --marketplace Arjun0014/project-sentinel.

A local clone works too: claude plugin marketplace add /path/to/project-sentinel. The terminal reads an installed folder marketplace straight from the folder, so after you pull changes, run /reload-plugins in a session. Desktop's Code tab may load the copy Claude Code made when you installed, so it needs claude plugin update project-sentinel@control-room after a new version, then a new session.

Installed as control-room@control-room before 1.4.0? Update the marketplace:

claude plugin marketplace update control-room

The marketplace maps the old name to the new one, so the update moves your install to project-sentinel@control-room (your enabledPlugins entry included), and the next session loads Project Sentinel. When it first loads it reads the store it kept as Control Room once (the one written last, where Claude Code kept more than one) and copies your settings, runs, Quest log and what it learned about the prompt cache into its own store; the old file is left as it was. Sessions that were open during the update keep Control Room until they restart; Project Sentinel stands by in them, so the two never act at once. Two things changed in behaviour: the Allow permission state is gone (a saved Allow reads as Default: in Bypass permissions mode nothing changes, otherwise prompts it answered come back unless your Claude Code allow rules cover them), and a click on Kit no longer opens the panel (the status bar's button does).

Each release raises the version, and Claude Code installs it when you ask:

claude plugin update project-sentinel@control-room

To get releases automatically, open Marketplaces in /plugin, select control-room and choose Enable auto-update. It is off by default for marketplaces you add yourself.

claude --plugin-dir /path/to/project-sentinel/plugins/project-sentinel

Nothing is installed. The plugin loads from that folder for that session, and edits to it reload live.

Desktop's local sessions run the same Claude Code engine and load the plugins installed above. To load a working copy without installing it, name the folder in the env block of ~/.claude/settings.json. Claude Code reads CLAUDE_CODE_PLUGIN_DIRS there for sessions that the Desktop app starts:

{
  "env": { "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/project-sentinel/plugins/project-sentinel" }
}

Use your platform's path-list separator (; on Windows, : elsewhere) for several folders. Remote (cloud) sessions have not been tested.

claude plugin uninstall project-sentinel@control-room

Settings and run history live in Claude Code's per-plugin store (see Configuration). Use /cr reset confirm first if you also want the settings cleared.

A mission HUD above the prompt: what is happening on top, the run's instruments below. Settings live in the panel.

◎ Linting · step 3 of 4                                                ▲ RAM 83%    ◆ Control Room
  WORK ●━●━◎─○ 2/4    CONTEXT ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇█▇▇▇▇▇ 47% · hands off 80%    CACHE ● rebuilt 446k      5H ▂▂▂▂▂▂ 63% · 2h14m

Width decides the detail. The names (WORK, CONTEXT, CACHE) show from 72 columns (5H names itself at every width), docked beside the panel included; the meter and the track shorten before the least important reading drops. The empty part of the meter and the HUD's top edge are drawn in the theme's quietest gray, the same in every terminal.

On Desktop the same readings sit in a row of five cells: Work, Context, Cache, Machine (CPU and memory as slim level bars with their percentages, amber near a ceiling and red at it) and the plan's 5-hour usage at the right edge (Plan usage — on an account with no five-hour window), each a quiet caption over its graphic and value, the button native. The columns are weighted by what they hold (Work and Context wider), and the five always keep their places, a dim word standing in for one with nothing yet (No milestones yet, —). Width decides the detail: the labels and what the cache holds in a wide band, CPU · RAM in a narrower one, the bars alone in a compact one. The graphics (the state's mark, the track, the meter, the level bars, the clock, Kit) are drawn as images.

(▸) Running tests · step 3 of 10                                           ✗ Lint failing   [ ◆ Control Room ]
Work                       Context · hands off at 70%    Cache              Machine                   5-hour usage
●━●━◉─○─○─○  2 of 10       ▬▬▬▬▬▬▬▬▬┃▬▬▬  24%             ◔ warm · 345k      CPU ▮ 34%  RAM ▮ 85%      ▂▂▂ 63% · 2h14m

When a handoff is about to happen, a line above offers Hand off now and Later; if a handoff ever waits for you, it offers Start fresh. A written handoff waiting for background work offers Hand off now (the work keeps running for the fresh context), Stop & hand off, Keep waiting (near the end of its wait, or once it stalled) and Call off; one the Handoff Supervisor finds stuck says what holds it and offers what fits. The same line asks about a watcher that waits for you (Check now, Start fresh when that is safe, In 30m, Dismiss), a message the Cold Resume Guard kept (Put back, Send now, Discard), the run budget holding automation (Continue anyway, Budget ›), and the Scout's suggestion (Claude seems to be waiting for a future result. Check the leaderboard again in two hours? Create watcher, Change time, Ignore). While subagents run, the agent band sits above all of it: a line per agent (up to three; more are counted by what they do, 5 agents · 2 reading · 2 editing · 1 checking), each opening Activity → Agents, and gone when none runs. With the companion on (Setup → Companion, /cr companion on), Kit lives in a lane above the headline: in the terminal it stands on the status bar's top edge, on Desktop it is drawn in finer pixels. Give it a click.

Claude Desktop's Git strip is the app's own: plugins can neither draw, hide nor move it, so Project Sentinel shows no Git UI on Desktop. In the terminal, Overview and /cr status carry the branch and the uncommitted files.

/cr (or /control-room) opens or closes it, and so does the status bar's button. In the fullscreen terminal from 110 columns it docks beside the conversation; otherwise it opens in a frame above the prompt. A wide frame (a wide terminal, or a Desktop pane at full size) keeps the page to 80 columns, centred. Opened by you, it seats at any width. If it opens on its own (Open at session start), it waits for 144 columns.

Click anything, or move with Tab, choose with Enter, and return to the prompt with Esc. Choosing a section starts its page at the top, and every page ends with ↑ Sections.

Every control is also a command. This is handy over Remote Control, for muscle memory, and on surfaces without the panel.

/cr is registered only if no other command already uses the name. /control-room always works.

A profile sets everything at once. Change anything afterwards and the profile reads Normal · edited, and Setup lists each change (Machine load Off › Medium). Save any setup as a profile of your own, or go back to the profile in one click.

New installs and updates. Only a fresh install gets the opinionated defaults (and one short Sentinel is on card, until Got it). An install that saved settings before 1.7 keeps every value; if it was on Normal, it now reads Classic, so it is not "edited" against the new Normal. An install that used Project Sentinel without ever changing a setting (settings are saved only when one changes; its runs, cache memory or Quest log show it is not new) is saved as Classic, so nothing changes for it either.

Conflicts are resolved in a fixed order (higher wins):

1. Organisation and engine safety: managed settings, deny rules, plan mode. Never loosened.
2. Permissions: apply to everything, including work the Autopilot or the guard asked for.
3. Your live actions: an interrupt cancels pending automation. A prompt you type while a handoff is pending is honoured, with a reminder. While a handoff is under way, an instruction about it ("handoff now", "keep waiting", "cancel the handoff") is acted on and never sent into the old context; any other message while a written handoff waits is asked about: hand off and give it to the fresh context, send it here, or keep it in the prompt box.
4. Autopilot: once a handoff is pending, the guard stands down, and no new large work is encouraged. Keep warm stands down only once the old context is about to be cleared (a waiting or stuck handoff keeps the cache warm). Queued work, answers and watcher wakes wait until the handoff is done (work queued for after the handoff rides the fresh context's first message).
5. Operations: Project Sentinel starts a turn of its own (queued work, an answer, a watcher's wake) only at a boundary, one at a time, and never while a turn runs, a handoff is under way, a question is open or background work will bring the turn back. A watcher never clears a run that moved since it was armed. At a run budget limit set to Ask or Finish, none of this (nor Autopilot's continuation) starts without your yes.
6. Machine load: constrains how (parallelism, heavy jobs), never whether. It applies under Frontier Max too.
7. Subagents: hard limits that Frontier Max and the router cannot exceed.
8. Frontier Max: vetoes router downgrades of the main conversation (unless the router is Custom).
9. Lazy-exit guard: subordinate to everything above and to its own caps.
10. Model router: acts only where nothing above constrains it, and never downgrades the main conversation while a prompt cache of 20k tokens or more is warm.
11. Focus view: presentation only. It never changes what Claude reads.

Overview shows each system's effective state, for example "Lazy-exit guard ● On Paused during the handoff".

Project Sentinel runs entirely inside Claude Code. It makes no network requests of its own, sends no telemetry, and nothing leaves your machine through it. It observes session figures (context, cost, each request's token counts), tool calls as they happen, and machine-wide CPU and memory totals (while the status bar shows them or a machine-load limit is on), and the plan's rate-limit windows Claude Code reports. In the terminal it runs one read-only git status after a turn and keeps only the branch and counts. When a milestone is completed it runs git hash-object --no-filters on the files that milestone's work changed (no filters, so no command a repository configures runs) and git rev-parse HEAD, and keeps only the blob ids, sizes and times. It writes only its own plugin store, and once, after the rename, reads the store it kept as Control Room to carry your settings over (it reads CLAUDE_CONFIG_DIR, USERPROFILE and HOME only to find it). Claude, not the plugin, writes the handoff file. Where Claude Code has no task list of its own, Project Sentinel offers Claude one small tool, milestones, whose answer only records the list for run progress; with the Decision Inbox on (the default) it offers decision_request, whose answer only records the question for you. It never answers a permission prompt for you.

The orchestration layer keeps what you give it with the run, in the same store: queued work in your words, Claude's decision questions and your answers, watcher labels and times, the run budget, and Claude Code's own cache-write price per model (for the Cold Resume Guard's figure). It submits prompts only of fixed kinds, at a boundary: your queued words, your answers, a watcher's wake, the first prompt of a fresh context it started. When you press them, Stop and Message on an agent use Claude Code's own TaskStop and SendMessage, and the Cold Resume Guard's Cancel puts your message back in the prompt box (Claude Code's $.prompt.fill); a message it could not put back is kept in memory only, never stored.

Three features send requests to your configured model through Claude Code's own client, as every turn does: the guard's optional smart check (the last request and answer); the Handoff Supervisor's one question about a background task it cannot recognise (that task's command and description only, never the conversation); and Keep warm, which is off by default and, when you turn it on, re-sends the conversation's last request with a one-word reply asked for, so the prompt cache stays warm. Each refresh costs tokens, mostly cache reads at a tenth of the input price.

What it observes, what it can change and what it never does is listed in SECURITY.md; the plugin folder's README says it in brief, as Anthropic's directory shows it.

• Advisory machine load. Project Sentinel informs Claude and holds back additional heavy commands. It does not and cannot enforce an OS-level CPU or memory quota, and it never stops or changes other programs.
• Pattern-based shell classification. Permissions narrow what Claude may do. They are not a sandbox.
• Run progress counts what Claude lists. With no task list (or Behavior → Run progress off) there is no work meter. A check passed when its command did; a command sent to the background has no outcome Project Sentinel can see, and says so.
• Model router, main conversation. Claude Code rejects a bare alias such as haiku on a model request. So the main conversation is only routed to a model whose full id Claude Code has already reported answering in this session (for example, after an Explore subagent ran on Haiku). Subagents take aliases, which Claude Code resolves.
• Headless runs. With no one to answer, a call set to Ask is refused. In CI or claude -p, set categories you need to Default. A plugin command such as claude -p "/cr status" given as the initial prompt goes to the model, because plugin commands register as the session starts. Use an interactive session, stream-json input, or the panel.
• Managed machines. Where your organisation seats Claude Code's managed policy guard, Project Sentinel's system-prompt section can be skipped. It detects this and delivers its policies as prompt context instead.
• No global sidebar and no pinned header. There is no API to change the Desktop application's own sidebar, or to pin a region inside a pane. The docked panel is the supported equivalent, and ↑ Sections brings the section bar back from the end of a page.
• The prompt cache is read, not reported. Claude Code reports how many tokens each request read from the cache and wrote to it, but no expiry, hit ratio or miss cause. Project Sentinel derives them: the expiry from the last request and the lifetime (as Claude Code is configured, by FORCE_PROMPT_CACHING_5M, CLAUDE_CODE_PROMPT_CACHE_TTL, promptCacheTtl or ENABLE_PROMPT_CACHING_1H; as it reports it at a model switch; or learned; a claude.ai plan otherwise starts at its one-hour default), the cause from the change it saw before a rebuild, said as proven, likely or unknown. A rebuild with nothing seen before it reads cause unknown, never put on the server without evidence. Only the main conversation's cache is watched; subagents start their own.
• Git in the terminal only. Desktop shows Git beside the session, and no plugin API reaches that strip, so Project Sentinel does not repeat it there.
• Watchers live in Claude Code's process. A watcher is a timer in the running Claude Code: closed (or the machine asleep), nothing wakes. It is kept with the run, and when that session is open again an overdue watcher waits for you (Watcher was due 43 minutes ago, Wake now); it does not wake by itself then. Project Sentinel installs no daemon, service or scheduled task. Claude Code's own CronCreate and ScheduleWakeup are session-only too; its cloud routines start other sessions, not this one.
• The Cold Resume Guard asks in Claude Code's dialog. Where no one can be asked (a headless run), it does not ask and the message goes. It knows a cache has lapsed from the lifetime it learned, an hour of quiet (longer than any lifetime), or Claude Code's own word at a resumed session; a cache that may still be warm (Claude Code's own requests while you are away count) is never called cold. It leads with tokens; a dollar figure is only Claude Code's estimate for that model (seen at a model switch or a resume), said as a floor: the reprocessing has cost more than the estimate.
• Background work across /clear. Claude Code keeps a background task running across /clear and hands its result to the fresh context (verified live), so a handoff never waits on a server and waits on finite work only so long (20 minutes by default). It cannot know what an unrecognised task is: it waits for it, asks a small classifier once, and you can always hand off now.
• Five-hour usage is Claude Code's last reading. It moves when a response brings a new one (and is read again each minute while a window counts down). Usage from other sessions or devices shows only when a response of this one reports it.
• Milestone evidence watches a milestone's own files. The files its work changed and the outputs Claude named; a file its checks depend on but its work never touched is not watched (that would mean hashing the repository). A file changed by a command whose changes Claude Code does not report counts as changed outside Claude's tools.
• Agents as Claude Code reports them. No cost per agent (Claude Code reports none); Stop and Message only where Claude Code's TaskStop and SendMessage take the agent (background agents and teammates). Decisions from subagents are not taken: the inbox is the main conversation's.

plugins/project-sentinel/       the plugin, and only the plugin (Anthropic's directory reads every file in it)
  .claude-plugin/plugin.json   manifest; icon.png beside it
  README.md, LICENSE           the directory's listing and disclosure; MIT
  hooks/hooks.json             { "modules": ["./register.tsx"] }
  hooks/register.tsx           the Host adapter and every hook registration (the only file that touches `$`)
  hooks/kit.client.tsx         Kit's surface module, drawn in the terminal and on Desktop
  hooks/app/                   Runtime (composition root), views and status wording, publisher, commands, persistence,
                               monitor, cacheGuardian (the prompt cache and Keep warm), formerStore (the rename)
  hooks/core/                  settings schema and defaults, profiles, policy, answer styles, formatting
  hooks/features/              autopilot, background (what a background task is), supervisor (the Handoff
                               Supervisor), intent (handoff-control words), chain, guard, router, subagents,
                               agents (the agent ledger), activity, plan (run progress), evidence (milestone
                               evidence), planUsage (the five-hour window), validation (checks), digest
                               (Activity's signal), quest (the Quest log), cache (the cache model), handoff
                               (Handoff Health, Continuity), companion (Kit), git, prompts, permissions/, resources/
  hooks/ui/                    design system (primitives, theme), status bar, Focus view rows, panel sections
  types/index.d.ts             the plugin's $.state contract
tests/                         claude plugin test suites (run on .build/mod: the plugin with tests/ beside hooks/)
tools/
  test/                        mod.mjs (assemble, type-check, test), source.mjs (the directory's source rules),
                               snapshot.mjs (a frozen cr-test copy for live tests)
  desktop-preview/             the status bar and the panel as Desktop lays them out, rendered as HTML
  console/                     Windows only: drive Claude Code in a real console, read the screen, save a PNG
  demo/                        development only: a scripted turn of real tool calls, no model, for screenshots

npm install

npm run check

npm run check runs tsc, claude plugin validate --strict (plugin and marketplace), the source rules and the test suites; CI runs the same on Linux, Windows and macOS. Claude Code writes the engine's type declarations into plugins/project-sentinel/.claude-plugin/types/ whenever a session loads the folder. Load it once (claude --plugin-dir plugins/project-sentinel, then /exit) before running tsc. See CONTRIBUTING.md for the rules the code follows and docs/DESIGN.md for the design system. On Windows, tools/console runs a session in a real console of a given width and reads the screen back, for checking the terminal UI.

This repository is a Claude Code plugin marketplace (.claude-plugin/marketplace.json, named control-room). The plugin folder is laid out for Anthropic's plugin directory (its listing text, licence and icon inside it); a submission is the maintainer's to make.

MIT