What Irie is
This page says everything Irie is, does, keeps and sends, as its code stood on 27 October 2026. Where you can check a claim on your own computer, Check it yourself says how.
In short
Irie is a free program that starts coding agents, AI programs that work on code, on your own computer. It keeps them running side by side and shows how each one is doing.
Irie isn’t an AI, and it has no server, account or sign-up. Each agent works for you as it would without Irie, on your own account with its AI company.
What it does
- Starts an agent for each task you type, in a folder of its own: a worktree, a second working copy of your project, or a new empty folder.
- Keeps every agent running in a tmux of its own, a free program that runs others in the background, so closing the window stops none of them.
- Shows how each agent is doing: working, needs you, done and more. Only Claude Code reports this today; other agents show whether they’re still running.
- Shows an agent’s live screen, or for Claude Code, its conversation in plain words.
- Picks a profile, the recipe for which agent and AI model to start, when a task names none. It takes the lowest cost per success among the profiles accurate enough for the task.
- Runs small tasks on a model on your own computer, through Ollama, once you set that up.
- Freezes an agent and everything it started at once, puts one session ahead of the rest, and renames, closes and reopens sessions. Undo and redo take back a start, a close or a reopen.
- Lists the Claude Code sessions running outside Irie, and moves one in when you ask.
- Lets scripts do most of this with
irie ctl.
What it never does
- It sends nothing over the internet of its own. What it sends, and where has the one exception, which you start yourself.
- It has no telemetry, analytics, crash reports or update checks.
- It never reads your logins or sends them anywhere. Each agent signs in its own way, as it would without Irie.
- It never edits your agents’ settings files, your tmux settings or your shell’s.
- It never answers a permission prompt for an agent, so the agent’s own permission rules stand.
- It never deletes a worktree, a branch or a folder an agent worked in. The only files it deletes are its own records, such as event logs past 30 days.
- It listens on no network port. The Ollama server it runs for local models listens on 127.0.0.1, which only programs on your computer can reach.
What it’s made of
The irie program
Irie is one program, irie, written in Go. Each of its parts is that program, started as irie and the part’s name.
| Part | What it does |
|---|---|
irie core | Starts agents, keeps track of them and keeps Irie’s records. It’s the only part that drives tmux, and every other part asks it, through a socket file only you can open. |
irie ui | The list on the left of the terminal window. |
irie host | The first program in each agent’s pane. It starts the agent, freezes and thaws it, and notes how it ended. |
irie hook | What Claude Code runs at each step, to tell the core. When Irie is down, it lets the agent carry on, unless you froze it. |
irie statusline | Claude Code’s status line. It passes the session’s cost to the core, then runs your own status line. |
irie runtime | Runs Irie’s own Ollama server for local models, once a task needs one. |
irie placeholder | What the right-hand side shows when no agent is on show. |
irie, up, attach, ctl, setup local, config, version | The commands you run. irie help lists them. |
Irie for Mac
An app for the Mac, in its first build, shows the same sessions as cards, beside an agent’s conversation or its terminal. It asks the same core, so you start Irie with irie or irie up first.
It shows an agent’s terminal by running tmux, and opens Ghostty only when you ask it to. It keeps your view choices, the task you haven’t sent and your last 50 tasks in its macOS preferences.
Its own tmux
Irie runs a tmux of its own, named irie, apart from any you use, with settings it writes. The window you see is its irie session; its irie-agents session holds the core, one window per agent, and Irie’s Ollama server when one runs.
Programs it runs
Irie includes none of these. It runs the copies on your computer.
| Program | When, and why |
|---|---|
| tmux | Always: it holds every agent. |
| git | To find your projects and make worktrees. |
| Your agents | The program each profile names, such as claude. |
claude --version, --help | Once for each build of Claude Code, to learn which flags it takes. |
claude agents --json | Every 3 seconds while you look at Irie, to list the Claude Code sessions running outside it. claude stop when you move one of them in. |
ps | About every 5 seconds, to measure each session’s memory, and when it closes a session or matches the sessions outside Irie. |
| Your status line | If you made one for Claude Code, Irie’s status line runs it. |
| Ollama | Only for local models, if you installed it. Irie bundles neither Ollama nor any model. |
Code from others
Irie’s Go code uses Bubble Tea, Bubbles and Lip Gloss to draw the list, BurntSushi’s TOML to read the settings file, and Go’s x/sys to read the process table, with the modules those need. All are under the MIT or BSD licenses.
The Mac app draws terminals with Ghostty’s engine, or with SwiftTerm, both under the MIT license.
Nobody else’s code is copied into Irie. PROVENANCE.md lists each module with its version and license.
What it keeps on your computer
Irie makes its folders so only you can open them. With XDG_CONFIG_HOME, XDG_STATE_HOME or XDG_DATA_HOME set, they live there instead.
| Where | What | For how long |
|---|---|---|
~/.config/irie/config.toml | Your settings, if you made the file. | Yours to keep |
~/.local/state/irie/journal/ | A file a day of events: each task’s start, each step an agent took, with a line such as the command it ran, and what you did. | 30 days |
~/.local/state/irie/sessions/<id>/ | For each session: its task, task.md; exactly how it was started, spec.json; Irie’s hooks for it, claude-settings.json; its host’s process ids, host.json; its last reply, result.md; its last status line, status.json; and how it ended, exit.json. | Until you remove them |
~/.local/state/irie/state.json | Your undo and redo history: the starts, closes and reopens you can take back. | The last 100 steps |
~/.local/state/irie/core.log, ui.log | What the core and the list did, with their errors. | Until you remove them |
~/.local/state/irie/local.json | The local model irie setup local chose, and how much memory models took. | Until you remove it |
~/.local/state/irie/tmux.conf | Irie’s tmux settings. | Written again as needed |
~/.local/share/irie/worktrees/, scratch/ | The folders agents work in. | Until you remove them |
$XDG_RUNTIME_DIR/irie/, or $TMPDIR/irie-<uid>/ without it, as on a Mac | The core’s socket and locks. | While Irie runs |
journal.tool_input = "none" keeps the steps’ lines out of the journal. A setting you put in a profile’s env is also written to spec.json, so keep secrets out of profiles.
What it sends, and where
- Irie itself talks only to the server behind your local models: its own Ollama on 127.0.0.1, port 11435, or the one you name in
local.url. It never goes through a proxy. - The one exception is
irie setup local, which you run yourself. After you say yes, it installs Ollama the official way, with Homebrew on a Mac that has it or Ollama’s install script on Linux, and asks Ollama to download a model. - Your agents talk to their AI companies, or your company’s, just as they would without Irie. What each sends is up to that agent.
- Its parts talk to each other through a socket file, never over the network.
- Building Irie downloads the modules above, checked against the fingerprints in its code.
What it does to your agents
How it starts them
- Each agent starts with its profile’s program, flags and settings. Its session’s
spec.jsonrecords exactly what ran. - Irie’s built-in profiles for Claude’s cloud models,
claude,sonnetandhaiku, start Claude Code in auto mode, where Claude Code decides which steps it may take without asking you. A profile’spermission_modepicks another. - Subtasks that a session hands on with
irie ctl delegaterun inacceptEditsmode, so they edit files without asking, and commands still need you.route.delegate_modechanges it. - For Claude Code, Irie adds a settings file for that one session, with its hooks, the small commands Claude Code runs at each step, and its status line. Claude Code adds the hooks to your own, and your settings files stay as they are.
- It adds
IRIE_SESSION,IRIE_SOCKETandIRIE_BINto the agent’s environment, so the hooks can find Irie. It removesTMUXandTMUX_PANE, so the agent’s own tmux commands can’t reach Irie’s, and the marks another Claude Code session or terminal left behind. - A local profile adds the settings that point Claude Code at the local model, with a placeholder key, so its requests for the model go there and not to Anthropic.
What it says to them
Irie gives an agent your task word for word.
A task over 100 KiB goes in task.md, and the agent is told: “Your full task is in <path>/task.md. Read all of it before doing anything else.”
Beyond that, Irie says three things to agents, and nothing else. Each begins with [Irie]:
| When | What it says |
|---|---|
A Claude Code session starts, and cheaper profiles could take its subtasks. route.delegate = false turns it off. | [Irie] To save tokens, you can hand a small, self-contained subtask to a cheaper model: run "$IRIE_BIN" ctl delegate "<subtask>" with Bash. It runs the subtask in this directory on the cheapest profile accurate enough for it (+local, +haiku, +sonnet), waits until it is done, and prints the result; it refuses a subtask that needs your accuracy. Delegate mechanical work, such as renames, docstrings, simple tests and summaries, on files you are not editing yourself, and keep planning, design and review. Run a long subtask in the background. |
A task carries on after its first session stopped at a usage limit. route.failover = false turns it off. | [Irie] This task ran on +claude, which stopped at its usage limit. What it did so far is in this directory: check it, then finish the task. |
| You thaw an agent that was working when you froze it. | [Irie] The user froze this session for 4m10s (14:02:11–14:06:21 UTC). Network calls or child processes may have failed meanwhile; re-check before you continue. |
The profiles, times and length in each change to fit.
What it types to them
Irie types into an agent’s terminal only when you send it a message, and to give a task to an agent that takes one at its prompt. It won’t send a message while Claude Code waits on you, so a message can’t answer its question by accident.
What it does to their processes
| When you | Irie |
|---|---|
| Freeze a session | Stops the agent and every process it started (SIGSTOP), and carries them on when you thaw it (SIGCONT). |
| Close a session | Asks the agent to end (SIGTERM), and ends it (SIGKILL) if it hasn’t after 5 seconds. |
| Promote a session, on a Mac | Puts the other sessions’ processes in macOS’s background state: the lowest priority for the processor, and slower disk and network. |
| Move a session into Irie | Ends the copy outside Irie, gently: claude stop for a background session, SIGTERM for one in a terminal. |
Restarting or updating Irie never stops or signals an agent, or anything an agent started.
What isn’t built yet
- Pausing an agent at its next step. The Mac app’s Pause button freezes the session instead. Planned
- Sending an agent a note it reads at its next step. Planned
- Parking sessions, and undoing more than a start, a close or a reopen. Planned
- A live view of each helper an agent starts. Today a helper is one line under its session. Planned
- Opening Irie from the Mac app or Spotlight. Planned
- tmux telling Irie of changes at once. Today Irie asks it once a second. Planned
- Working, needs you and done for agents other than Claude Code, Codex CLI first. Planned
- A release to download. You build Irie from its source code: see Install.
Who makes it
Coding agents write most of Irie’s code. Every commit an agent helped write names it in a Co-Authored-By: line, so git log shows which.
Irie is built only from public documentation and from code whose license allows it. PROVENANCE.md lists every source, with its date and what it shaped.
Anyone can help build it, and Contribute says how their work is counted.
Check it yourself
Every setting in effect, defaults included:
irie config printEvery pane Irie runs, and the program in each. Claude Code shows up as its version number, such as 2.1.310:
tmux -L irie list-panes -a -F '#{session_name}:#{window_name} #{pane_current_command}'Exactly how one session’s agent was started, and the hooks it got:
ls ~/.local/state/irie/sessions/
cat ~/.local/state/irie/sessions/<id>/spec.json
cat ~/.local/state/irie/sessions/<id>/claude-settings.jsonEvery network connection Irie’s parts hold open. Nothing, or only connections to 127.0.0.1:11435 for local models, is what you should see:
lsof -nP -a -i -c irieAnd the code itself, with the design that explains every part: github.com/irie-people/irie.