iris

A live terminal supervisor for every active Claude Code session. cargo install iris-tui (the binary is iris).

🌐 Landing page: itzenata.github.io/iris-tui

What it does

A fast terminal dashboard that watches all your running Claude Code sessions at once: what each one is doing right now, its model, tokens and estimated cost, an AI "doing / done / next" summary, and one-key approval of pending tool calls routed from any session into a single pane.

It reads the transcripts Claude Code already writes under ~/.claude/projects/. No daemon, no config, nothing to set up beyond an optional approval hook.

Hard rules: local-first (the only network call is the AI summary you opt into), read-only over your transcripts, and a heartbeat so sessions never hang waiting on iris.

What's working today

A single live pane, refreshed every second:

Panel	What it shows
Sessions list	Every session active in the last N minutes, grouped and sorted, color-coded by state
Aggregate cost	The header totals the estimated USD spend of everything on screen (also in iris ls)
Status glyphs	⚠ pending approval · ● running · ✓ done / awaiting you · ○ idle
Per-session meta	Model (opus-4-8, sonnet, haiku, fable), token total, estimated USD cost
Activity feed	The latest prompt, thinking, tool call, and result of the entered session, tailed live
Tool timeline	A histogram of which tools a session leans on, so you can spot the one stuck in a build loop
AI summary	s for a Haiku-generated "doing / done / next" briefing of any session
Approval modal	⏎ opens the full tool input with an x AI risk read; a/d allow or deny

Views & navigation: vim motions (j/k, g/G, Ctrl-d/Ctrl-u) on both the session list and the activity feed, foldable groups (space/z), D to remove a stale session from the view (the transcript on disk is untouched), and an ls subcommand that prints a one-shot table with no TUI.

Remote approvals: iris install-hook registers a PreToolUse hook in settings.json. With gating armed (A), any session's permission prompt routes into iris: approve or deny it, for one session or a whole group, from one place.

Cost model: per-model pricing (input / output / cache-write / cache-read) kept as editable constants in src/cost.rs. Figures are estimates; adjust them to your plan.

Hard rules

• Read-only over your data. iris tails the transcript files Claude Code writes; it never edits them.
• Local-first. The only outbound request is the AI summary / risk read, and only when you press s / x. No telemetry, no remote config.
• Never hangs a session. iris touches a heartbeat file while running. If it's stale (iris not up) or gating is disarmed, the hook instantly defers to Claude Code's normal permission flow, so your sessions are never blocked on a dashboard that isn't there.
• Opt-in interception. Approval gating is off until you arm it with A, and it disarms automatically when iris exits.
• Your key, your machine. The Anthropic API key for summaries is entered in-app (K) and saved 0600 in your home directory.

Install

cargo install iris-tui   # installs the `iris` binary in ~/.cargo/bin

(The crate is iris-tui because iris is a reserved name on crates.io, but the command you run is iris.) Prebuilt Linux and macOS binaries are on the releases page, or build from source with cargo install --path . after cloning.

Then:

iris                     # live dashboard
iris ls                  # one-shot table, no TUI
iris install-hook        # route approvals through iris (--project for ./.claude)
iris uninstall-hook      # remove the hook

Single static binary, built with Rust + ratatui. Reads ~/.claude/projects/; override with -d <path>.

Keys

Key	Action
j k	move between sessions
g G	jump to first / last · Ctrl-d Ctrl-u half-page
space z	fold a group / fold all
D	remove the selected session from the view (transcript on disk untouched)
⏎	open the approval detail (full input + AI risk read), or enter a session's feed
a d	allow / deny the pending tool call (whole group when a header is selected)
s	AI summary of the selected session (g to regenerate)
x	AI risk read of the pending tool call
i	open the approval-interception proposal
A	arm / disarm approval gating
K	set your Anthropic API key (saved 0600)
r	force refresh
q	quit

Progress

• MIT-licensed, single static Rust binary
• Landing page on GitHub Pages
• Issue templates for bugs, features, integration ideas
• Live session discovery + tailing from ~/.claude/projects/
• Dashboard: status glyphs, model, tokens, estimated cost
• Activity feed with vim navigation and foldable groups
• Tool-usage histogram per session
• AI "doing / done / next" summaries (Haiku)
• PreToolUse hook bridge: remote approve / deny from one pane
• AI risk read on a pending tool call
• Heartbeat fallback so sessions never block on iris
• ls one-shot table mode
• Remove sessions from the view (D) without touching transcripts
• Unit tests for the heartbeat and transcript parsing
• CI on every push and PR (clippy, build, test)
• CONTRIBUTING guide + PR template
• crates.io publish metadata in Cargo.toml
• 60s demo video + validation post
• Published to crates.io as iris-tui + prebuilt binaries on releases

Get involved

• ⭐ Star to follow progress
• 💡 Suggest an integration or signal
• 💬 Open an issue for any session-supervision problem you'd want solved
• 🔧 Want to contribute code? Read CONTRIBUTING.md: small fixes go straight to PR, features start as an issue

Star History

Development

cargo run                 # live TUI
cargo run -- ls           # one-shot table
cargo test                # heartbeat + transcript parsing tests
cargo clippy --all-targets -- -D warnings   # CI gates on this
cargo build --release     # optimized binary (LTO, stripped)

CI runs clippy (warnings as errors), build, and tests on every push and PR; see .github/workflows/ci.yml. Contribution guidelines live in CONTRIBUTING.md.

Code layout: main.rs is the CLI entry and event loop; modules under src/ split as app (state), ui (rendering), session (transcript parsing), bridge (the hook + heartbeat), anthropic (summaries / risk reads), and cost (estimation).

License: MIT