Iris documentation

Iris is a local proxy and policy layer for Claude Code. It binds to 127.0.0.1, sits between Claude Code and Anthropic, and answers four questions you cannot answer from the chat window.

1. What is Claude actually sending? The full system prompt, every tool schema, the whole conversation, sized in tokens and priced at list rates.
2. Does it need all of that? Which schemas ship on every turn and were never once called.
3. Is this action inside the task's authority? Evaluated before the tool runs, not after.
4. What actually happened? A local ledger of every call and every decision.

How it works

Iris hooks Claude Code at two independent points, each using a feature Claude Code already has.

Claude Code  →  Iris :8787  →  api.anthropic.com
                    │
                    ├── Context     what the request carried
                    ├── Optimize    which schemas ship without being called
                    ├── Guard       allow / ask / deny, before execution
                    └── Recorder    what ran, and under which decision

The proxy hop sees everything the model receives. init writes ANTHROPIC_BASE_URL=http://127.0.0.1:8787 into your project's .claude/settings.json, so every POST /v1/messages lands in Iris first. Iris parses the body, sizes each tool schema, logs the exchange with secrets scrubbed, and forwards it byte-identically upstream.

The hook hop sees everything the agent does. init also installs iris hook as a PreToolUse and PostToolUse hook. PreToolUse runs before the tool executes and returns a permission decision; PostToolUse records the outcome. No model is involved in either — Guard is deterministic code.

Requirements

• Node 18 or newer. Iris has zero dependencies — it runs on Node's standard library.
• Claude Code, with an Anthropic account it can already use. Iris does not handle authentication; your existing credentials pass through untouched.
• A project with a .claude/ directory. That is the project Iris will serve.

Install

# terminal 1 — leave this running
npx @zero-drift/iris

# terminal 2 — from a project that has .claude/
npx @zero-drift/iris init

Restart Claude Code, then open http://127.0.0.1:8787. The step-by-step version, with what to expect at each point, is the Quickstart.

Your first session

1. Work normally for a while, so there is real traffic to look at.
2. Open Context and read your fixed prefix — the system prompt plus every tool schema, the part that is re-sent on every message.
3. Open Optimize and sort by never-called. Turn off the large optional and MCP schemas you do not need for this project. Leave Core tools alone.
4. Open Guard, describe the task in one line, and accept the envelope.
5. Come back to Flight Recorder at the end of the day.

Read next