Skip to main content

Circinus docs

Alpha · v0.0.0 · not production security software

Circinus is a local-first Agent Trust Runtime for Claude Code. This page covers installation, the quickstart, how the runtime is put together, what it supports today, and what it deliberately does not do yet.

Installation and quickstart​

Circinus is not yet published as an installable package — there is no uv tool install circinus-runtime today, and this page will not pretend otherwise. The only supported path right now is running it from a source checkout with uv, and the source repository is currently private — during this Alpha, git clone below only works if you already have access. If you don't, this is exactly what the Try/Install CTA on this site is for: it's a request for access, not a command you can run yet.

git clone https://github.com/horonomy/circinus.git
cd circinus
uv sync                              # install the project and its dev dependencies
uv run circinus install claude-code  # register Circinus's hooks into .claude/settings.json
uv run circinus start                # start the local runtime (circinusd)
uv run circinus status               # installed? daemon healthy? shadow or enforce? hooks connected?

circinus install claude-code writes only the minimum hooks Circinus needs (PreToolUse, PostToolUse, PostToolUseFailure) into .claude/settings.json — project scope by default, --scope user for ~/.claude/settings.json — and preserves every other key and hook already there. It is safe to re-run; install and uninstall (uv run circinus uninstall claude-code) are both idempotent. uv run circinus install claude-code --print shows the change without writing anything.

Once installed, Circinus starts in shadow mode: hooks fire, events are recorded, and every PreToolUse decision is allow — nothing is blocked by this MVP. If the daemon is down, the hook fails open (shadow mode) or closed (enforce mode) explicitly, and logs the gap rather than staying silent.

Local-first architecture, summarized​

Full detail lives in docs/architecture.md in the repository (the repository itself is not yet public); this is the shape of it.

Circinus records where content came from (provenance) and what it may cause (authority), durably, on your machine, before anything asynchronous happens. While the agent keeps working, cheap-tier semantic analysis runs in the background — ahead of any sensitive action — and only escalates to a stronger analysis tier when needed. When the agent then attempts a sensitive action, a fast synchronous local gate reads that already-computed evidence plus a deterministic policy from a local SQLite database — no network call, no remote database round trip — and returns ALLOW, REVIEW, or BLOCK with an explanation of which source, which transformation, and which rule drove the decision.

The invariant this exists to defend: transformation must never silently expand authority. An artifact's verdict only gates an action it actually influenced, not everything that happens afterward in the same session — a single adverse artifact does not become a session-wide kill switch.

No context leaves your machine unless you configure your own model provider key (BYOK). There is no Circinus-operated service, no telemetry endpoint, and no account required to run the runtime itself. See Privacy for what a future, opt-in telemetry channel will and will never collect.

Supported Claude Code workflow​

This MVP integrates with exactly one agent host: Claude Code, via its PreToolUse, PostToolUse, and PostToolUseFailure hooks. circinus install claude-code registers those hooks; from then on, every matched tool call in your Claude Code session is observed and durably recorded, and (in shadow mode) reported on without changing the outcome. There is no support yet for other agent hosts or frameworks.

Limitations​

Circinus is deliberately not:

  • a SaaS product or a hosted control plane
  • an identity system — no SSO, no SCIM, no RBAC
  • a SIEM or a log-shipping pipeline
  • a runtime for every agent framework — Claude Code only, today
  • a global threat-intelligence network
  • a custom-trained model or a model-training effort
  • a dashboard or a web UI
  • a replacement for OPA, Cedar, or existing prompt-guard libraries

And concretely, right now:

  • Shadow mode is the default and nothing is blocked by this MVP. Enforcement is opt-in, per-decision-class, and reversible — you read the decisions Circinus would have made before anything of yours is interrupted.
  • It is an MVP (v0.0.0), not production security software. It does not claim prompt-injection immunity: inferred provenance resolution catches literal reuse of an artifact's content in a later argument, and misses transformed reuse — re-encoding, splitting, base64, paraphrase, and homoglyphs all evade it. That is a floor, not a guarantee.
  • It does not claim enterprise readiness, support for agent frameworks beyond Claude Code, or proven product-market fit.