Sentinel

Walk away while an autonomous coding agent does the work, safely.
A persistent Codex coder writes the code. A separate supervisor owns approvals, steering, restarts, and the final quality gate.

Why Sentinel

Today you run an autonomous coding agent in one of two ways, and both are bad:

• You babysit it: approve every command by hand. Safe, but you can't leave.
• You give it full permissions: it runs unattended, and one hallucination away from deleting the wrong directory, faking a passing test, or pushing something it shouldn't.

Sentinel is the third way: the coding agent works autonomously, while an independent supervisor, a separate model with a small clean context, judges every risky action, steers the coder when it drifts, restarts it when it stops absorbing correction, and refuses to accept "done" until the work actually survives review. You leave. It works. You come back to a final report.

[SYSTEM]     settings: task=task.md coder-mod=gpt-5.6-sol runtime-mod=gpt-5.6-sol completion-mod=gpt-5.6-sol adversary-mod=gpt-5.6-sol
[CODER]      Logic tests are green. Running the browser smoke check next.
[TOOL]       command completed: node --test  exit=0
[APPROVAL]   accept: headless browser run against the local page is exactly the validation the task asks for
[DENIED]     decline: nothing in the task or project state calls for reaching an external host
[SUPERVISOR] steering coder: the last validation masked its exit status; rerun it unmasked
[CODER]      SENTINEL_READY_FOR_REVIEW
[SUPERVISOR] completion review: return, one required behavior lacks fresh validation evidence
[CODER]      Fixed and re-validated. SENTINEL_READY_FOR_REVIEW
[ADVERSARY]  running pre-complete adversarial tester (1/1)
[SUPERVISOR] accepted by completion_review after clean adversary report
[SYSTEM]     final report written: .supervisor/FINAL_REPORT.md

Measured results

Supervision is not just safety. It is measurably more finished work from the same underlying model:

• SWE-bench Pro: 20–30% more tests passed than the same model running unsupervised.
• SpecBench (complex, long tasks): up to +37% more hidden tests passed versus the same model's unsupervised single pass.
• The adversarial tester regularly finds real defects in work that already passed multiple reviews: bugs nobody would have caught until production.

Honest fine print: the deep mode is slower than a raw agent run. Hard tasks take hours, so start it in the evening and read the final report in the morning. Supervisor turns also consume tokens on top of the coder's work.

Use cases

Sentinel is configurable, but these are the main ways people should think about using it:

Deep work and everyday are recommended presets, not the limits of how Sentinel can run. Every run keeps the runtime supervision: fail-closed approvals, steering, health tracking, and restarts. Everyday removes the final exam, not the guardrails.

Why it works

Long-context degradation is well documented: models get measurably worse as their context window fills, long before the nominal limit (Lost in the Middle, RULER, NoLiMa, Context Rot). An agent that has been grinding for an hour is exactly the agent most likely to hallucinate, and in the full-permissions setup, nobody is watching when it does.

Sentinel's design attacks that directly:

• The supervisor never accumulates context. Every decision is a fresh, stateless turn over a compact packet of durable state, so it judges with a clean head every time.
• The coder gets restarted before it spirals. When a generation stops absorbing correction, the supervisor restarts it with a structured handoff: what was done, what went wrong, what to do next.
• Completion review runs in a fresh thread with the full task and the validation ledger, and certifies behavior against the task, not the coder's claims about it.
• The adversarial tester knows nothing about how the code was written. It gets a disposable snapshot of the workspace and tries to break the result with its own probes before the run is allowed to finish.

How it works

flowchart LR
    You(["You"]) -->|"task.md"| S["Sentinel"]
    S <--> C["Codex coder<br/>(persistent thread)"]
    C <--> W["disposable workspace<br/>network off"]
    C -->|"sandbox boundary<br/>request"| P{"policy"}
    P -->|"safe"| OK["auto-approve"]
    P -->|"dangerous"| NO["auto-deny"]
    P -->|"gray zone"| J["supervisor turn<br/>(fresh context)"]
    C -->|"ready"| G["completion review<br/>+ adversarial tester"]
    G -->|"defects"| C
    G -->|"clean"| A["validate + apply patch"]
    A --> R["project + FINAL_REPORT.md"]

• Sandbox first: by default the coder works in a disposable copy of the project with network access off. Normal edits and local commands stay inside that copy, while the real project remains unchanged during the run.
• Deterministic policy at the boundary: requests to leave the sandbox are checked immediately. Secrets, grading paths, broad deletes, and deploy/publish/git-force operations are denied.
• Judgment where it belongs: everything in between goes to a stateless supervisor turn that judges the action against the task and project state: the same command can be legitimate in one project and cheating in another.
• Fail closed: if the supervisor can't be reached or returns garbage, the action is declined, never waved through.
• Checked handoff: after acceptance, Sentinel validates the final paths and symlinks, applies the patch to the real project, and verifies the result. Work from an interrupted or rejected run is kept under .supervisor/recovery/ instead of being silently discarded.

Requirements

• Codex CLI installed and authenticated (Sentinel drives codex app-server; your Codex account provides the models).
• Python 3.11+ and git.
• macOS or Linux.

Verify your environment at any time with sentinel doctor.

Install

Option A: Codex plugin (recommended if you work inside Codex):

pipx install sentinel-supervisor
codex plugin marketplace add AlexeyKulaev/sentinel-codex-marketplace --ref main
codex plugin add sentinel-supervisor@sentinel-marketplace

Then open Codex in your project folder and ask it to run Sentinel on your task file. The plugin checks for updates and launches the run for you.

Option B: standalone CLI

pipx install sentinel-supervisor
sentinel doctor

Sentinel checks for updates at startup and offers to install them; run sentinel update to update explicitly.

Quick start

cd your-project
echo "Build a CLI tool that ..." > task.md
sentinel --task task.md

That's it. Sentinel starts the coder, supervises the run, and writes .supervisor/FINAL_REPORT.md when it finishes: status, changed files, validations that were run, and remaining risks.

While a run is active you can type into the terminal; your message is routed to the supervisor, not the coder:

Everything the run does is written to inspectable files under .supervisor/ in your project: PROGRESS.md (what has happened), DECISIONS.md (standing decisions), HANDOFF.md (restart context), events.jsonl (full event stream), and FINAL_REPORT.md (the result).

Configuration

Open the interactive editor from your project folder:

sentinel config

It creates and edits .supervisor/config.json. Every value is saved as you press Enter; future runs in this folder use these settings automatically.

Coder, runtime supervisor, completion reviewer, and adversary are configured independently. For each role, select the GPT-5.6 family first and then use its variant row to choose Sol, Terra, or Luna. GPT-5.5 remains available; older model families are not offered.

Resolution order: CLI flag → project config → built-in default. Flags apply to one run and never rewrite the saved config.

Mode recipes:

# Deep work (defaults): completion review + adversary, run it overnight
sentinel --task task.md

# Everyday: finish on the coder's validated readiness, no final exam
sentinel --task task.md --completion-review=false

# Deep work on a big task: give the adversary a second pass
sentinel --task task.md --adversary-runs 2

Command reference

sentinel                 # run the configured task in the current folder
sentinel --task TASK.md  # run a specific task file
sentinel config          # open the interactive config editor
sentinel doctor          # check Python, git, Codex, auth, app-server support
sentinel update          # update Sentinel to the latest version
sentinel update --check --json  # machine-readable update status
sentinel --version       # installed version, latest version, update status

Run flags (each overrides the saved config for one run):

Environment variables: SENTINEL_SKIP_UPDATE_CHECK=1 skips the startup update check; SENTINEL_PROMPTS_FILE=/path/to/prompts.toml points Sentinel at an alternative prompt file for experiments.

Under the hood

For the curious. None of this needs configuring:

• Terminal lanes: [SYSTEM] runtime state, [CODER] coder messages, [TOOL] completed actions, [APPROVAL]/[DENIED] approval outcomes, [SUPERVISOR] decisions and steering, [ADVERSARY] the final tester.
• Isolation and approvals: the coder runs in a disposable workspace-write sandbox with network access disabled. Codex app-server routes requests that cross that boundary to Sentinel. Deterministic policy answers the clear cases; gray-zone requests get a fresh stateless supervisor turn; supervisor failure or timeout fails closed. Network approvals are one-shot rather than persistent command-prefix rules. App-server uses a run-local rule store, so command prefixes previously approved in ordinary Codex sessions cannot bypass Sentinel; authentication, config, skills, and plugins remain shared. The adversarial tester runs in a disposable workspace snapshot with the same fail-closed rules.
• Restarts: a restart interrupts the coder, writes a structured HANDOFF.md (objective, what went wrong, known evidence, next step), and starts a fresh coder generation. After 5 restarts Sentinel writes an honest stuck report and exits instead of burning tokens forever.
• Preflight: before real work starts, Sentinel verifies Codex version, app-server schema, auth state, model availability, and structured-output support, and exits early with a clear report if anything is missing.
• Prompts: all supervisor and coder prompt text lives in one TOML file (supervisor/prompts/prompts.toml), loaded at runtime.
• State: everything durable lives in .supervisor/ as plain markdown and JSONL, inspectable during the run and after it. Recovery workspaces from runs that did not apply cleanly are retained in .supervisor/recovery/.

License

Sentinel is released under the MIT License. See LICENSE.

Contributions require signing the project CLA; a bot will prompt you on your first pull request, and you only sign once.