Iris Code · v0.4.0

Getting started

Iris Code is a desktop wrapper around the official claude CLI from Anthropic. Before launching the app for the first time, install the CLI and authenticate it.

Install the Claude Code CLI

From a terminal:

npm install -g @anthropic-ai/claude-code
claude auth login

claude auth login opens a browser and walks you through the OAuth flow. When it completes, the CLI stores credentials in your OS keychain and is ready to use.

Install Iris Code

Download the installer and run it. The default install path is fine — no admin rights required. The installer creates a Start menu shortcut and a desktop shortcut (you can opt out of the desktop shortcut).

First run & the onboarding wizard

On first launch, Iris Code runs a four‑step wizard:

1. CLI check — confirms the claude binary is on PATH and authenticated.
2. Key vault setup — optionally store one or more Anthropic API keys in the OS keychain.
3. Hotkey registration — claim a global hotkey for the Spotlight overlay.
4. Shortcut tour — a 30‑second interactive tour of the command palette and snippets.

Skip any step and revisit it from Settings · First run later.

The Iris overlay

The Spotlight overlay is a translucent, always‑on‑top mini‑window you can summon from anywhere with a global hotkey — default Ctrl + Shift + Space. Use it as a launcher, a rubber duck, or a research assistant without leaving whatever you were doing.

Summon & dismiss

• Ctrl + Shift + Space — open the overlay (configurable).
• Esc — dismiss and restore previous focus.
• Return — send your prompt.
• Ctrl + Return — send and open the response in the main app.

What to ask

The overlay is optimized for quick, single‑turn questions:

• "Explain this error" (with a pasted stack trace).
• "Quick regex for ISO‑8601 dates."
• "Translate this curl command into TypeScript fetch."
• "What does flag --mmap do for rsync?"

For multi‑turn work, start a thread in the main window instead.

Threads & agents

A thread is a conversation. An agent is the claude process that powers it. Each thread owns exactly one agent; threads are independent.

Create a new thread

Click + New thread in the sidebar, press Ctrl + N, or pick New thread from the command palette.

You'll be asked:

• Working directory — a folder on your machine, or "sandbox copy."
• Model — the Claude model the agent should use.
• API key — which named key from your vault.
• Template (optional) — a workflow template to seed the system prompt and starter actions.

Sandbox mode

With sandbox mode on, Iris Code copies your working directory into a scratch folder under %LOCALAPPDATA%\IrisCode\sandboxes\. The agent works there. When you're satisfied, choose Export changes from the thread menu to:

• Apply changes back to your real working tree (with conflict detection).
• Save changes as a .patch file.
• Create a new branch on the real repo and push the changes there.

Per‑agent keys

Every thread can use a different API key from your vault. This matters when you want to bill different clients separately, isolate experimental keys, or use a key with different rate limits. See API keys & encryption.

Command palette

Press Ctrl + Shift + P (or Cmd + Shift + P on macOS once we ship that build) and a fuzzy search opens over every action in the app.

The palette covers:

• Thread management — new, rename, pin, archive, export.
• Navigation — jump between threads, open settings, open the stats dashboard.
• Agent control — pause, resume, cancel, change model, change key.
• App actions — toggle theme, reload, check for updates, open logs.

Recently used actions float to the top automatically.

Workflow templates

Templates are pre‑configured starting points. Pick one when creating a thread (or via the palette: Template: Code Review) and the agent boots with a tuned system prompt and a small list of starter actions you can fire with one click.

Built‑in templates

Custom templates ship in v0.3.

Prompt snippets

Snippets are saved prompts you can drop into any chat input. Open the chat input, type /, and a fuzzy list appears. Type a few letters to narrow, hit Return to insert.

Manage snippets at Settings · Snippets. Each snippet has:

• A trigger — what you type after the slash. E.g. review.
• A body — the actual prompt text. Supports placeholders like {{selection}}.
• An optional description — shown in the dropdown.

Pinning & notifications

Pinned threads

Right‑click any thread in the sidebar and choose Pin to top — or hit Ctrl + Shift + . while a thread is focused. Pinned threads get a small gold ring marker and sit above the regular list.

System notifications

Iris Code can raise native OS toasts when interesting things happen in the background. Configure each event at Settings · Notifications:

• Agent finished — when a turn completes without errors.
• Agent needs input — when an agent asks a question and stalls.
• Agent errored — non‑recoverable failure (e.g. rate limit, network).
• Sandbox ready to export — when a sandboxed agent says "done."

Stats dashboard

Open the dashboard from View · Stats or with Ctrl + Shift + D. You'll see:

• Total threads, messages, and tool invocations for any time range.
• Per‑agent breakdowns of tokens consumed (input vs. output).
• Most‑used templates and snippets.
• Average turn duration, sorted by template.

All data is local. Iris Code does not phone home; the stats engine reads from your local SQLite database and renders to the dashboard with no network call.

Conversation export

From any thread, choose Export → Markdown (or palette: Export thread as markdown). The result is a single .md file with:

• A # heading containing the thread title.
• ## sub‑headings for each turn ("You" / "Iris").
• Fenced code blocks for any code in the conversation.
• Collapsible <details> blocks for tool calls (kept out of the way but available).

JSON export — for archival or programmatic use — lands in v0.3.

Keyboard shortcuts

Iris Code is keyboard‑first. The shortcuts below are the defaults; remap any of them at Settings · Shortcuts.

API keys & encryption

Iris Code stores API keys in your operating system's keychain — DPAPI on Windows, Keychain on macOS (when that build ships), libsecret on Linux. Keys never touch the filesystem in plaintext, and never appear in log output.

Managing keys

Open Settings · Keys. You'll see a list of named keys; for each one you can:

• Add — give it a friendly name and paste the key. It's encrypted immediately.
• Rotate — paste a new value; the old one is overwritten.
• Delete — removes the key from the vault and any threads using it fall back to your default.
• Set default — the key new threads use unless you pick another.

How encryption works

On Windows, keys are encrypted with the Data Protection API (DPAPI), scoped to your user account. Only your logged‑in Windows profile can decrypt them. If you sign in as another user (or copy the database to another machine), the keys are unreadable.

Troubleshooting

"claude CLI not found"

Iris Code looks for the claude binary on your PATH at launch. If you installed it via npm after launching Iris Code, restart the app (or open Settings · CLI and click Re‑detect).

If detection still fails, set an explicit path in Settings · CLI · Custom path.

Hotkey conflicts

Ctrl + Shift + Space is uncommon, but some IMEs and launchers claim it. If Iris Code fails to register the hotkey at launch, it shows a small banner and offers an alternative (Ctrl + Alt + I by default). Pick a new one at Settings · Shortcuts · Spotlight.

SmartScreen warning at install

The v0.4.0 installer is not yet code‑signed, so Microsoft Defender SmartScreen may interrupt installation with a blue prompt. Click More info, then Run anyway. Signed installers are scheduled for v0.5.

Unsigned installer / antivirus quarantine

On rare antivirus configurations, the unsigned installer may be quarantined automatically. Add an exception for %LOCALAPPDATA%\IrisCode or wait for the signed v0.3 build.

App won't launch / blank window

Open %APPDATA%\IrisCode\logs\ and grab the most recent log file — either attach it to a GitHub issue or paste the last 200 lines into a chat with Iris Spotlight. Most blank‑window cases are GPU driver related; try launching with --disable-gpu as a workaround.

Where is my data stored?

• Threads & messages — %APPDATA%\IrisCode\db.sqlite
• Logs — %APPDATA%\IrisCode\logs\
• Sandboxes — %LOCALAPPDATA%\IrisCode\sandboxes\
• API keys — Windows DPAPI (not on disk in plaintext)
• Preferences — %APPDATA%\IrisCode\settings.json

FAQ

Last updated for v0.4.0 · May 2026 · Edit improvements welcome via PR.