## Iris for Claude Code

> Iris is a local proxy and policy layer for Claude Code. It runs on 127.0.0.1 between Claude Code and Anthropic, measures what every API request carries, identifies tool schemas that ship without ever being called, and evaluates tool calls against an authority envelope before they execute. MIT licensed, zero dependencies, Node 18+.

- **Name:** Iris for Claude Code
- **Author:** Hammad Abbasi
- **License:** MIT
- **Install:** `npx @zero-drift/iris`
- **Source:** https://github.com/csehammad/iris-control-plane
- **Package:** https://www.npmjs.com/package/@zero-drift/iris

- [Iris for Claude Code](https://hammadabbasi.com/iris): Product overview — what Iris measures, how unused tool schemas are removed from context, and how Guard evaluates tool calls before they run.
- [The Token Tax](https://hammadabbasi.com/iris/token-tax): Research measuring what Claude Code sends before any prompt. A 28,000-token baseline reduced to 5,600 by removing unused tool schemas, measured with /context on a fixed eight-message conversation. Includes method, per-call cost arithmetic, and stated limits.

### Documentation

- [Iris documentation](https://hammadabbasi.com/iris/docs): How Iris works, requirements, install, and first session.
- [Quickstart](https://hammadabbasi.com/iris/docs/quickstart): Eight steps from install to first context reading and first trim, each with expected output and failure handling.
- [Context](https://hammadabbasi.com/iris/docs/context): What a Claude Code request is made of — system prompt, tool schemas, conversation — why the fixed prefix is re-sent every turn, how token counts are calibrated against measured usage, and what Iris does not measure.
- [Optimize](https://hammadabbasi.com/iris/docs/optimize): How tool schemas are sized and call counts derived, why only a bare tool name in permissions.deny removes a schema from context while a scoped rule does not, and which tools should never be disabled.
- [Guard](https://hammadabbasi.com/iris/docs/guard): The authority envelope, how a tool call is normalised into a structured effect, the six-rung decision ladder producing allow/ask/deny, trajectory signals, fail-closed behaviour, and known limitations.
- [Flight Recorder](https://hammadabbasi.com/iris/docs/flight-recorder): The local ledger of every tool call with its policy decision attached.
- [Configuration](https://hammadabbasi.com/iris/docs/configuration): Environment variables, what iris init writes, multi-project port resolution, and where captured data is stored.
- [Security and privacy](https://hammadabbasi.com/iris/docs/security): Loopback-only binding, byte-identical forwarding, the 14 credential patterns scrubbed at rest, opt-in wire redaction, Guard's threat model, and what Iris explicitly does not claim.
- [Troubleshooting](https://hammadabbasi.com/iris/docs/troubleshooting): Connection failures, port conflicts, stale hook paths, trims that did not apply, and recovering a disabled tool.
- [Uninstall](https://hammadabbasi.com/iris/docs/uninstall): Every change Iris makes and how to reverse it.

### Key facts

- **Measured result:** system tools 25.6k → 3.2k tokens; total baseline 28.0k → 5.6k; 22,400 tokens reclaimed per turn. One measured configuration, not a guaranteed saving.
- **Mechanism:** a bare tool name in Claude Code's `permissions.deny` removes that tool's schema from the request payload; a scoped deny rule blocks execution but leaves the schema in context.
- **Guard is not a sandbox.** It evaluates tool calls before execution and is strongest on filesystem containment and production access. It does not confine processes.
- **No model calls.** Policy decisions are deterministic code, so Guard costs no tokens.