Start here — when to use Circinus
What this product does, in one paragraph
Circinus watches what an AI agent reads (a web page, a file, a command's output) and what it's about to do (run a shell command, write a file), and keeps a record of which pieces of content actually influenced which action. When you ask "did an untrusted source just determine a dangerous command?", Circinus can answer from that record — in shadow mode, today, without changing what happens. Today's MVP runs on Claude Code only; see Limitations.
When to reach for it
- You run Claude Code (or another agent) against real repositories and want visibility into which tool calls were influenced by content the agent fetched or read, not just what the agent says it did.
- You want to see, concretely, whether a "the agent read an install guide, then ran a command from it" pattern would have been flagged — before deciding whether to turn on any enforcement.
- You're evaluating whether an authority/provenance-tracking approach (as opposed to a prompt-injection text classifier) is the right shape for a problem you have.
- You want a local, auditable trail of
PreToolUse/PostToolUsedecisions for a session, without sending session content anywhere. - You're debugging "why did my agent do that" after the fact and want the actual lineage, not a guess.
- You maintain Claude Code hooks yourself and want a reference implementation of a hook-based decision engine to learn from or extend.
When NOT to reach for it
- You need actual enforcement today, out of the box. Shadow mode is what
every install actually gets — no command turns enforcement on. See
Limitations for exactly what reaching
enforcewould require. Circinus will tell you what it would have blocked; by default, it will not stop anything. - You use an agent host other than Claude Code. There is no other adapter.
- You want a general prompt-injection classifier or content filter. Circinus deliberately does not classify text as "malicious" — it tracks where an argument's value came from and what authority that source holds. See Architecture for why that distinction is the whole point.
- You want to gate
WebFetchcalls specifically. OnlyBashandWrite/Edit(thefs_writeaction class) are gated end to end today (below). - You need a hosted, multi-user, or team-shared decision log. Everything here is local, single-machine, single-user.
- You're looking for a persistent contact/address-book-style feature, or a way to receive a handoff artifact from another product. Circinus can ingest a specific kind of external artifact in code (see the maturity table below), but there is no CLI or hook path to trigger that today — nothing you can actually run.
Maturity — what's real today
| Capability | Status | Notes |
|---|---|---|
Shadow-mode observation (Would-Allow/Would-Review/Would-Block) | SHIPPED | The only mode that changes nothing while still recording a real decision. Default and effectively only mode. |
Bash gating (content-aware, authority-based) | SHIPPED | Gated end to end via the deterministic policy engine. |
Write / Edit gating (fs_write action class) | SHIPPED | Gated end to end as of MVP 2.1, on file_path only — file content is never read for authority purposes. |
WebFetch hook observation | PARTIAL | Matched by the PreToolUse hook and ingested for provenance, but not run through the same content-aware gate Bash/fs_write are. |
circinus explain (decision/artifact lineage reconstruction) | SHIPPED | Verified in the scenarios below against real output. |
circinus authorize (explicit scoped trust grant, with expiry and revoke) | SHIPPED | Only the instruct authority dimension is wired. --scope-kind, --expires-at, and --revoke <grant-id> are all supported. |
circinus doctor / circinus repair | SHIPPED | Verified in Scenario C below. |
circinus feedback (override / adjudicate / outcome / inspect) | SHIPPED | Records human/execution learning signals, distinct from authority — never writes an AuthorityGrant. See CLI Reference. |
Origin evidence class + provenance coverage in circinus explain | SHIPPED | Every decision/artifact explanation now shows origin_evidence= per edge and a provenance coverage: complete|partial|unknown line — not a trust score, a statement about evidence completeness. |
| Enforce mode (real blocking) | NO SUPPORTED WAY TO ENABLE IT | The daemon can run in enforce mode and will really block — but no shipped command ever writes anything other than shadow into the install manifest. See Limitations. |
Policy profiles other than balanced (realtime/strict/critical) | NOT USER-SELECTABLE | Exist in code; nothing sets one at runtime today. |
Ophiuchus Context Capsule ingestion (circinus.adapters.ophiuchus_capsule) | INTERNAL-ONLY | A real, tested adapter that ingests an Ophiuchus capsule as an untrusted artifact — but there is no CLI subcommand and no hook-payload path that reaches it. Reachable only by importing the Python module directly. Not a usable feature today; see the CLI Reference and HORO-646 for the pending product decision on whether to expose it. |
| MCP server/tools of Circinus's own | NOT IMPLEMENTED | Circinus exposes no mcp__* tools. It only ever treats another server's tool-call result as untrusted input, same bucket as a fetched web page. |
| Hosted service (telemetry/billing/fake-door) | SHIPPED, off by default | Local enforcement never depends on it. See Privacy. |
The first thing to try
Install, start the daemon, and send one real decision through it — five commands, about two minutes: Scenario A.
Where to go next
- Scenarios — three realistic, source-verified walkthroughs.
- Quick Start — the bare install/start/status reference.
- Architecture — how the decision path actually works.
- CLI Reference — every subcommand and flag.