Tasks, repos and worktrees

Whatever you type in the task box is a task. Its first line can also say where the agent works, with @, and which agent it is, with +.

The task box

The box grows to 8 lines as you type, then scrolls. A task has no length limit, and the agent gets it word for word.

Where a task runs

A repo, short for repository, is a project whose history git keeps. A worktree is a second working copy of a repo, on a branch, or line of changes, of its own.

Agents in different worktrees can’t trip over each other’s edits.

• The @ and + words can go anywhere on the first line. Irie takes them out, and the rest goes to the agent as you wrote it.
• Any word on the first line that starts with @ or + is read this way, so add +5 to the total asks for a profile called 5. Put such words on a later line.
• One @ and one + per task.
• Write a folder from your home folder, ~/, or from the top, /, such as @/home/alice/code/shop. Paths such as ./shop aren’t accepted.

How @ finds a repo

A name such as @shop is looked up in three places, in this order:

1. The names you give in repos.aliases.
2. Repos in the folders you list in repos.roots, two levels deep. A repo on the second level also goes by its path, such as clients/api.
3. The last 20 repos you used.

[repos]
roots = ["~/code"]
aliases = { web = "~/code/website" }

These lines go in Irie’s settings file. Profiles and models says where it is, and how to make Irie read a change.

The first place that knows the name answers. If no repo there has exactly that name, one that differs only in capital letters will do.

If a name fits two repos, nothing starts, and the line under the list names both, so you can give the folder instead. If it fits none, the line suggests the closest names.

Worktrees

For @shop, Irie makes the worktree before the agent starts:

Your own files stay as they are. Irie never deletes a worktree or a branch.

What a worktree gets

• Every file git keeps, as it is in the starting commit.
• Your local files that git leaves out: the ones your repo’s .worktreeinclude names, if git ignores them, and the ones worktree.copy names, which by default are .claude/settings.local.json and CLAUDE.local.md. A file the worktree already has is left alone.
• The repo’s submodules, checked out, when it has a .gitmodules file.

.worktreeinclude is a file at the top of your repo, written like a .gitignore, and Claude Code reads it too. This one gives every worktree your local .env file:

.env

What stays behind

Changes you haven’t committed stay in your checkout. The line under the list says how many, such as 1 uncommitted change in the main checkout was not carried over.

Commit first if the agent needs them. Right after a task starts, the same line names its branch and what was copied: worktree irie/fix-cart-total · copied .env, CLAUDE.local.md.

A repo with no commits yet has nothing to start a branch from. Commit once, or add ! to work in its own folder.

Trust

Claude Code asks you to trust a folder the first time it works there. It keeps your answer for the whole repo, so a repo you trust once is trusted in all its worktrees.

When you’re done

Review the branch and merge it the way you like. Then remove the worktree and the branch, from your checkout:

cd ~/code/shop
git worktree remove ~/.local/share/irie/worktrees/shop/fix-cart-total
git branch -d irie/fix-cart-total

git won’t remove a worktree that holds changes or files it doesn’t know, such as a copied CLAUDE.local.md that your repo doesn’t ignore. Look inside first; if nothing there is needed, add --force.

git branch -d won’t delete a branch that isn’t merged yet, which keeps unmerged work safe. Clearing out old worktrees from Irie is planned. Planned

Pick the agent with +

+ and a profile’s name picks the agent and its AI model for one task, such as +local. Without one, a task uses spawn.default_profile: out of the box, Claude Code with Opus 5.5 at max effort in auto mode.

A name Irie doesn’t know starts nothing, and the line under the list names the profiles there are. Profiles and models shows how to make your own.

Tab completion

Press Tab with the cursor in an @ or + word on the first line:

• + completes profile names.
• @ completes the names of the repos Irie knows, whatever their capital letters.
• @~/ and @/ complete folders. Hidden folders come up once you type a dot.

One match fills in the word and a space. A folder leaves the cursor at its end, so you can go on into it.

Several matches fill in what they have in common, and the line under the list shows them all.

Pastes and big tasks

A short paste goes into the box as text. One over 8 KiB, which is 8,192 bytes, shows as a chip instead, such as [paste 32.8 KB · 700 lines], and goes to the agent whole when you press Enter, tabs and all.

Type around a chip as you like. Delete its label to drop the paste.

A task over 100 KiB is handed over as a file: the agent is told to read all of it before it does anything else. Irie keeps every task in its records, in ~/.local/state/irie/sessions/<id>/task.md.

From a script, irie ctl spawn @shop - < task.md reads a task of any size from a file: see irie ctl spawn.

Names

A row is named after the first five words of its task’s first line, in small letters joined by dashes, up to 32 characters: fix-the-flaky-checkout-test. A name that’s taken gets -2, -3 and so on.

A worktree and its branch take the same name. irie ctl spawn --name picks the name yourself, and renaming a row later is planned. Planned