Circinus docs
Circinus is a local-first Agent Trust Runtime for AI agents. It tracks where content came from (provenance) and what it may cause (authority), and gates a sensitive action at the moment it's attempted — so a summarized, stored, or re-read piece of untrusted content is never silently treated as having gained more authority than it started with. Today that gate runs in shadow mode by default (see below) and reports what it would have done rather than stopping anything — see Limitations for what actually reaching real enforcement takes in this build.
This page is the map. Use it to find the right next page rather than reading top to bottom:
| If you want to... | Go to |
|---|---|
| Know when (and when not) to use Circinus, and what's actually shipped | Start Here |
| Install it and see it running in under 5 minutes | Quick Start |
| Follow a realistic, copy-pasteable walkthrough with real output | Scenarios |
| Understand how the runtime is put together | Architecture |
| Look up a CLI subcommand and its flags | CLI Reference |
| Fix a daemon/hook/provider problem | Troubleshooting |
| Know exactly what this MVP does not do yet | Limitations |
The problem, in one paragraph
When a coding agent reads a GitHub issue, a web page, a dependency changelog, or a teammate's pasted log, that content is untrusted input. But once it has been summarized, written to memory, or handed to another agent, it stops looking like input and starts looking like instruction. Several hops later, a privileged action — writing a file, running a shell command, opening a PR — gets taken on authority the external content was never granted. The invariant Circinus exists to defend is: transformation must never silently expand authority.
Scope of this MVP
Claude Code only. One agent host, one adapter, one set of hooks. Circinus is not attempting to be framework-agnostic at this stage — breadth would buy compatibility at the cost of ever learning whether the core idea works.
Shadow mode is the default
Circinus starts in observe-and-report mode. It watches the agent session
and records what it would have done — Would-Allow, Would-Review,
Would-Block — without changing the outcome of a single action. You get to
read the decisions and judge whether they are right before anything of yours
is interrupted. Enforcement is opt-in, per-decision-class, and reversible —
see Limitations for exactly what "opt-in" means in this
build today.
No context leaves your machine unless you configure your own model provider
key (BYOK — bring your own key). There is no Circinus-operated service and no
account required to run the runtime itself. A telemetry channel exists in
code but is disabled by default — nothing is sent unless you explicitly
set CIRCINUS_TELEMETRY_ENABLED=true. See Privacy for exactly
what it will and will never collect when enabled.
Not sure this is the right tool for what you're trying to do? Read Start Here first. Ready to try it right now? Jump straight to Scenarios.