Quickstart

The whole path below takes about five minutes. Each step says what to run, what you should see, and what to do when you see something else.

1. Start Iris

   From anywhere. Leave this terminal running for as long as you are working — Claude Code reaches the API through it.

   npx @zero-drift/iris

   Expected: a banner naming the project, the proxy URL, and the paths it is using.

   If the port is busy: Iris prints which project is using it. If it is another Iris instance, it moves to the next free port and re-points that project's settings itself. See Troubleshooting.

2. Initialize the project

   From the project directory that contains .claude/, in a second terminal.

   npx @zero-drift/iris init

   Expected: a summary of what was written — ANTHROPIC_BASE_URL, the two hooks, the envelope draft, and four .gitignore entries. Re-running is safe; it never wipes an existing permissions.deny.

   If it says the project has no .claude/: you are in the wrong directory, or the project has not been opened in Claude Code yet.

3. Restart Claude Code

   Claude Code reads .claude/settings.json at session start, so a running session will not pick up the change. Quit it fully and start it again.

   Expected: nothing visible. Claude Code behaves exactly as before.

4. Send one message

   Anything that makes Claude read a file is ideal, because it produces both a model request and a tool call.

   What does src/guard/policy.mjs do?

   Expected: a normal answer. If Claude Code reports that it cannot reach the API, Iris is not running — see step 1.

5. Open Iris

   open http://127.0.0.1:8787

   Expected: the Overview, with at least one call recorded. Keys 1–7 switch views and ⌘K / Ctrl-K opens the command palette.

   If it says "waiting for agent": the proxy is up but no traffic has reached it. Confirm you restarted Claude Code after init.

6. Inspect Context

   Press 4. The band at the top is the most recent turn drawn to scale.

   What to read: the fixed prefix — system prompt plus tool schemas — is the part re-sent on every message. If tool schemas are a large share of it, step 7 is worth your time. Details: Context.

7. Open Optimize and stage a trim

   Press 5 and sort by never-called. Toggle off a large optional or MCP schema you know this project does not need.

   Expected: the change is staged. Nothing is written until you press Publish changes, and the deny list applies from the next Claude Code session, not the next turn. Details: Optimize.

8. Open Guard and accept an envelope

   Press 6, write one line describing what this task is allowed to do, and press Accept envelope.

   Expected: subsequent tool calls appear in the decision ledger with a rule name attached. Until an envelope is accepted, Guard uses the restrictive default. Details: Guard.