Occasio

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](docs/GETTING-STARTED.md) 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 # Build a behavioral attestation for one session occasio explain # 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 --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

occasio doctor --paranoid

Scans the installed source for every outbound network primitive, classifies each callsite, checks for telemetry SDK signatures, and surfaces the audit chain status. Exits non-zero if any critical finding appears. JSON output via --paranoid --json. See docs/WHY-LOCAL.md for the architecture this verifies.

Where Occasio sits alongside SLSA Provenance and CycloneDX AI-BOM: docs/SUPPLY-CHAIN-TRIANGLE.md. Occasio is the runtime behavioral leg.

---

Live visibility — for developers

The audit chain and signed attestations answer *"what did the agent do, prove it"* — the auditor's question. Sometimes you also want the simpler one: *"what is the agent doing right now?"* What is leaving your machine in this HTTP request. Which files have already gone to Anthropic in this session. What the system prompt looks like. What got redacted before it shipped.

occasio eyes is a local browser UI on http://127.0.0.1:3002 that shows exactly that. Capture is opt-in via --eyes on the proxy; nothing leaves the machine, all storage stays under ~/.occasio/eyes/.

occasio eyes --demo            # synthetic data, no proxy needed (10-second tour)

occasio claude --eyes # then in another terminal: occasio eyes # browser tab opens automatically

What you see:

• Sidebar grouped by user prompt — one "read the readme" expands into the 3–6 HTTP round-trips it actually took (Claude Code's agentic loop made visible).
• Session sparkline + per-file aggregate — outbound size over time, which files have been sent to the cloud and how often.
• Per-exchange byte-decomposition — stacked bar showing system / history (replay) / new-this-turn / tools-framing. The "small" request that's 124 KB is suddenly explainable: 108 KB of it is the same system prompt every time.
• Tabs: Request · Response · Tools (full local tool outputs — Read/Glob/Gr