Occasio

Local-first audit chain and identity gate for AI coding agents. Your prompts, your tool calls, your audit log; all on your machine, cryptographically verifiable later — and an agent may request an identity (ssh / cloud / root), not silently assume one.

Occasio is a local proxy that sits between your AI coding agent (Claude Code, Cline, or anything that talks to the Anthropic API) and whichever LLM endpoint you configured. Every tool call passes through one human-readable policy file you control. You can see what is leaving your machine in real time, block what should not happen, and end up with a tamper-evident hash-chained log that a third party can verify offline months later if you ever need to prove what your agent did.

Nothing about Occasio sends data to a third party. There is no Occasio cloud, no Occasio account, no telemetry. Read docs/WHY-LOCAL.md for the architecture, docs/COMPARE.md for how this differs from cloud-hosted AI observability tools, and docs/SUSTAINABILITY.md for how a local-first product is funded under Apache 2.0.

Screenshot: occasio eyes --demo against synthetic data — no real paths, no real traffic. The "(demo)" badge top-left is always shown in demo mode.

npm install -g @occasiolabs/occasio

occasio demo audit       # Auditor scenario: signed attestation + cross-verifier proof (10s, no API key)
occasio demo attest      # End-to-end attestation pipeline against a synthetic chain
occasio demo anomalies   # Live EDR detection on a synthetic adversarial chain
occasio harness          # Real Claude Code attacking a denied path — defense holds

The first three demos run against synthetic data so you can see the full pipeline in seconds with no external dependencies. The fourth spawns a real Claude Code subordinate under your Anthropic login (bundled auth — no API key required) and proves the defense end-to-end. Start with demo audit — it answers the only question that actually matters: "prove what your AI agent did in CI."

Identity gate — request, don't assume

The incident this was built for: an agent is asked only for a deploy command, but on its own it sshes into the server and reads env. The strict policy stops exactly that — an AI agent may request an identity, it may not silently assume one.

• Exfiltration is denied, tool-agnostically. printenv, cat .env, /proc/self/environ, private-key reads, grep-for-secret-names — blocked no matter which command or tool reads them; the output never reaches the model.
• Identity borrows need a human. ssh / scp, az / the cloud control plane, sudo / systemctl — a fail-closed BLOCK with a "requires human approval" refusal the agent cannot satisfy on its own.
• The handshake distinguishes who is who. The agent requests; you authorize once, out-of-band, from your own terminal:

occasio init --template strict          # the identity-gated posture
# agent runs `ssh deploy@host`  →  BLOCKED, pending apr_…
occasio approvals approve apr_… --once  # you, single-use, short TTL
# the agent's retry passes through once — then it's blocked again

The agent cannot self-approve: the approval control plane is in its deny-zone and the token is HMAC-signed. The chain records actor=ai_agent · delegator=you · approved_by=you. A second, non-proxied enforcement point — a PreToolUse hook (occasio hook --install) — covers execution that doesn't pass through the proxy.

Full design, threat model, and the honest residuals (runtime indirection, egress): docs/identity-gate.md.

Two ways to use it

Most people land here for one of these — pick the column that fits and skim accordingly.

Both views read the same underlying log. You don't have to pick one — running the proxy gives you both for free.

Quickstart

New here? The 5-minute Getting Started guide walks the identity-gate flow end to end — install → init --template strict → run your agent → approve a borrow → verify the log. Every command in it is tested against the published release.

Requires Node.js ≥ 18. Works on Windows, macOS, Linux.

npm install -g @occasiolabs/occasio   # Install
occasio doctor                          # Verify setup (Node, claude CLI, port, profile)
occasio init                            # Write ~/.occasio/policy.yml (dev-default)
occasio init --template strict          # …or the identity gate: deny secrets, gate ssh/cloud/root behind approval
occasio register                        # Add 'claude' shell alias (one-time)
claude "read package.json and tell me the version"

After the alias is registered, every claude invocation routes through Occasio transparently. Audit-chain rows accumulate at ~/.occasio/pipeline-events.jsonl.

Inspect the run:

occasio status                  # Session totals
occasio replay --detail         # Run-level audit
occasio audit verify            # Re-walk the hash chain end-to-end
occasio anomalies               # Run EDR detectors over the last 15 minutes
occasio attest --run-id <uuid>  # Build a behavioral attestation for one session
occasio explain <event-id>      # Why was this blocked? — the matched policy rule + how to unblock

Command matrix

Grouped by what you're doing. (stable) = load-bearing with test coverage; (beta) = works end-to-end, narrower; (alpha) = scaffold. Full list: occasio help.

Evidence workflow

Produce one file an auditor or CI receives and checks in a single command:

occasio attest --run-id <uuid> --sign          # behavioral attestation (Sigstore optional)
occasio bundle --run <uuid> --out run.occasio.json   # pack attestation + chain slice + policy + manifest
occasio verify run.occasio.json                 # 6 offline checks; exit ≠ 0 on tamper

verify checks the schema, the manifest hashes, the chain slice integrity, the policy binding, the git-state vs chain cross-check, and the Sigstore signature when present — all against data embedded in the file (never the producer's machine). The run is bound to the concrete code it touched via git_state rows (HEAD + diff hash + changed files). Signing is optional; an unsigned bundle still verifies everything else. Bundles embed absolute producer paths — an internal-audit artifact; review before sharing publicly. → docs/VERIFY.md

Policy workflow

~/.occasio/policy.yml governs the Occasio-controlled path: secret handling, deny_paths/allow_paths, custom deny_patterns, per-round limits, and tool routing. Approve it and pin against drift:

occasio policy init                              # starter policy.yml
occasio policy validate                          # lint before you rely on it
occasio policy lock --sign --out policy.lock.json   # record the approved policy
occasio policy diff --since policy.lock.json     # CI gate: exit 1 if the policy drifted

→ docs/POLICY.md

Scanner & preflight

occasio scan --file .env                         # explainable secret findings (masked, exit 1)
occasio preflight simulate --read ~/.ssh/id_rsa --bash "npm test" --strict   # would the policy block this?

scan never prints the secret in plaintext (masked snippet + SHA-256). preflight simulate runs candidate actions through the same policy engine the runtime uses and shows the matched rule + how to unblock for anything it would block. → docs/SCAN.md · docs/PREFLIGHT.md

Verify the local-first claim