Keys and commands

Irie lists these keys on the right until you pick an agent.

Irie has two places to type: its list on the left, with the task box at the bottom, and the agent you show on the right. Ctrl+] moves between them.

In the list

Key	What it does
`↑` `↓`, `k` `j`	Pick the row above or below.
`PgUp` `PgDn`	Move a screenful.
`Home` `End`	Pick the first or the last row.
`Enter`	Show the picked agent on the right, and move there.
`Space`	Show it, but stay in the list.
`x` `x`	Close the picked session. The first `x` says what it closes, and any other key keeps it. Its folder stays, and `:reopen` brings it back.
`z`, `Z`	Park the picked session out of the way, in Parked at the end of the list, or bring it back to its place; fold or open Parked. Parked starts folded, so what you park goes out of sight, and it leaves the to verify count. A parked session keeps running and still turns red when it needs you. A state change never moves a row: only you do.
`u`, `U`	Undo or redo the last start, close or reopen; the header says which. When Irie is not sure, it asks first: pick a numbered answer, or `Esc` to change nothing.
`Tab`	Go to the task box.
`:`	Go to the task box with a `:` typed, for a command such as `:rename`. More commands are planned; see Keys to come.
`r`	Rename the picked session: its name opens in the task box, after `:rename`, for you to edit. Enter renames it and Esc keeps the name. The name stays when Irie restarts.
Mouse wheel	Scroll the list without changing the pick.
Click a row	Show it and move there, like Enter.
Click the task box	Go to the task box.

In the task box

Key	What it does
`Enter`	Start the task.
`Shift`+`Enter`, `Ctrl`+`J`	A new line.
`Tab`	Complete the `@` or `+` word under the cursor: see Tab completion.
`Esc`	Clear the box and go back to the list.
Paste	Over 8 KiB, a paste shows as a chip and goes to the agent whole: see Pastes.

Anywhere

Key	What it does
`Ctrl`+`]`	Move between the list and the agent on the right. `ui.focus_key` changes it.

On the right, every key goes to the agent, since that’s the agent’s own screen. Click there to move in, and scroll with the wheel.

There’s no key to quit. Close the window and your agents keep running; tmux’s own keys are switched off inside Irie.

Keys to come

Key	What it will do
`/`	Jump to a row by typing part of its name.	Planned
`1`–`9`	Jump to the first to ninth row.	Planned
`p`, `P`	Pause the agent, or it and its helpers, at its next step.	Planned
`f`, `F`	Freeze the session, or all of them, at once.	Planned
`!`, `n`	Mark the task as urgent; send its agent a note.	Planned

:rename NAME renames the picked session. Other commands typed after :, such as :pause and :note, come with milestones 4 to 7. Until then the task box answers unknown command.

Commands

Command	What it does
`irie`	Start Irie if needed, and open it in this terminal.
`irie up`	Start Irie if needed, in the background, without opening it.
`irie attach [--nested]`	Open Irie in this terminal. `--nested` opens it inside another tmux.
`irie ctl <command>`	Use Irie from scripts: below.
`irie version`	Print the version.
`irie config path`	Print where the settings file is.
`irie config print`	Print the settings in effect.
`irie help`	Print the list of commands.

Irie also runs irie core, irie ui, irie host, irie hook and irie placeholder for itself. You don’t need to.

irie ctl

irie ctl lets scripts, files of commands run in a row, use Irie without a window. It talks to the Irie that’s running, and spawn starts one first if needed.

irie ctl list [--json]

Lists the sessions and their states.

$ irie ctl list
SESSION        STATE      NAME                         DETAIL
s38bvacmnq8rx  working    fix-the-flaky-checkout-test  Bash · go test ./checkout/...
s38bvad9actcd  needs_you  write-the-release-notes      asks: Which version is this?
s38bvad9qgve0  done       update-the-dependencies

A state is one of starting, working, needs_you, stalled, failed, exited, done and idle.

--json prints {"sessions": […]}, with an object for each row. It holds the row’s id, name, state, detail, created time and cwd, and where they apply the repo, worktree, branch, copied files, profile, warnings, exit_code and tail: the last lines of the screen of an agent that stalled or failed.

irie ctl spawn

irie ctl spawn [--wait] [--cwd DIR] [--name NAME] [@REPO[!]] [+PROFILE] TASK...

Starts a task and prints its session id, starting Irie first if it isn’t running.

@REPO, @REPO! and +PROFILE work as in the task box, but must come before the task.
- as the task reads it from standard input, such as a file: irie ctl spawn @shop - < task.md.
--cwd DIR runs the task right there in a folder. It can’t go with @REPO.
--name NAME names the row.
--wait waits until the agent is up and working. If it fails, stalls or ends first, the command fails and says why, with the last lines of the agent’s screen.

$ irie ctl spawn --wait @shop fix the cart total
s38bvacmnq8rx
$ irie ctl spawn --wait +aider tidy the README
s38bvaapndcgp
irie: tidy-the-readme failed: failed: exit 127 · irie: aider: command not found
  irie: aider: command not found

The command ends with 0 when the task started and 1 when it didn’t, so a script can test it. Without --wait, it returns as soon as the task is handed over.

irie ctl show [--focus] SESSION

Shows a session on the right, as Enter does in the list. --focus also moves your typing there. Showing a done session marks it seen, so it turns idle.

irie ctl show s38bvacmnq8rx

irie ctl watch [--session SESSION]

Prints Irie’s events as they happen, one JSON object per line, until you stop it with Ctrl+C. --session keeps one session’s events.

$ irie ctl watch --session s38bvacmnq8rx
{"v":1,"seq":42,"ts":"2026-10-26T14:02:11.408Z","session":"s38bvacmnq8rx","agent":"main","source":"hook","harness":"claude-code","kind":"tool.started","vendor":{"session_id":"6f1c…","tool_use_id":"toolu_01…","hook_event":"PreToolUse"},"data":{"tool":"Bash","summary":"go test ./checkout/..."}}

Each event has a kind and its data. The kinds today are spawn.requested, spawn.failed, session.started, prompt.submitted, tool.started, tool.finished, tool.failed, input.needed, turn.ended, turn.failed, subagent.started, subagent.finished, session.ended, pane.exited and ui.shown.

Irie keeps the same events in ~/.local/state/irie/journal/, one file per day, for 30 days.

irie ctl dog [--json]

Lists the tasks that aren’t through: their turn is over, but their work isn’t committed, or isn’t yet in the branch their repo lands in ([dog]). A task you close is done, so it’s never listed and the dog never brings it back. A task that closed on its own (close_when_done) in the last day is listed when work has come into it since, so irie ctl reopen can bring it back to finish.

$ irie ctl dog
SESSION        STATE   NAME            LEFT                   WHERE
s38bvad9qgve0  done    fix-cart-total  2 commits not in main  ~/.local/share/irie/worktrees/shop/fix-cart-total (irie/fix-cart-total)

More irie ctl commands arrive with the actions they control, such as pausing. Milestone 10 adds irie ctl preflight and spawn --force for local models. Planned