Starting an Agent
The New agent sheet in the agents view starts an agent with a task. Pick the agent, its model, effort and permission mode, the machine and where it works, and ask for up to 8 attempts. Presets in the config start the same agent the same way from a shell.
The New agent sheet Added in v0.11.0 starts a coding agent with a task, without leaving the agents view. Write the task, pick the agent and where it works, and press Enter. In a git repository the agent gets a new worktree on its own branch by default, so it never touches your working tree.

Quickstart
- Press Ctrl+B i to open the agents view.
- Press n, or click
+ New agent. - Type the task.
- Press Enter.
tuios makes the worktree and its branch, starts the agent in a new pane, and types the task once the agent is ready. The new agent shows up in the agents view as it starts.
The fields
| Field | What it does |
|---|---|
| Task | The first prompt. tuios types it when the agent is at its prompt. Ctrl+J adds a line, @ names a file of the folder or an agent, and a pasted image path or Ctrl+V adds an image |
| Agent | The agents that run now come first, then the ones installed on this machine. more lists every agent |
| Model | Passed to the agent as --model. Type one, or pick one that a running agent of the same kind reports. Empty uses the agent's default |
| Effort | The agent's own effort levels, such as low, medium or high. default passes no flag |
| Permissions | The agent's own permission modes, such as plan or acceptEdits. default passes no flag. A mode that turns approvals off, such as Claude Code's bypassPermissions, says approvals off beside it |
| Where it works | New worktree, on its own branch, or This folder |
| Branch | The new branch. It is named after the task, such as agent/lru-cache-safe, until you change it |
| Base | Where the branch starts. Type it, or pick a local branch |
| Machine | This machine and your linked hosts. With a linked host, the first row is Any machine. When the rows have room for two lines, each says what that machine's daemon finds: claude ready, claude not signed in or claude not installed |
| Attempts | 1 to 8. Each attempt gets its own worktree and branch |
The model, effort and permission choices come from the [launch] table of the agent's manifest, so a choice the agent does not have is not shown. An image goes to the session's file store when the agent starts, and the task names it by its stored path. Only an agent on this machine takes an image.
Uncommitted files stay in this folder. A new worktree starts from the base, not from your working tree.
Keys
| Key | Does |
|---|---|
| Tab, Shift+Tab | Next or previous field |
| ← → | Change the agent, where it works, the attempts or the button |
| Space or ↓ on the agent | Open the list of every agent |
| ↑ ↓ on the machines | Pick a machine |
| v on the attempts | Give each attempt a different agent |
| Ctrl+J | Add a line to the task |
| Ctrl+S | Save the choices, without the task, for the next new sheet |
| Enter | Start |
| Esc | Close the sheet and keep what you wrote for the next n |
The mouse works too: click a field, a choice, Start agent or Cancel. A start that fails keeps the sheet as it was, so you lose nothing. n is inbox_new_agent in [keybindings.inbox].
Where the agent works
New worktree goes through the same path as tuios fan. tuios makes a worktree beside the repository and a branch from the base. The agent starts in a new session for the worktree. The branch name follows git's rules for a ref. A base that starts with - is refused.
This folder goes through tuios start-agent: the agent starts in a new pane in the folder you are in. Use it outside a repository, or for a task that should change your working tree.
Many attempts
Set Attempts to 2 or more to give the same task to several agents at once. Each one works in its own worktree on its own branch, so the attempts never touch each other. v on the attempts gives each attempt a different agent, so you can compare Claude Code and Codex on one task. The attempts show in the agents view under one row with the task. When they finish, press c on an attempt to compare them side by side, j to ask a judge agent, and k to keep one. See Fans, compare and judge and Comparing and keeping one.
All attempts start on the machine you picked.
On another machine
Pick a linked host in Machine to start the agent there. The agent works in a new worktree of the host's checkout of this repository. The host finds that checkout by the repository's origin. See Work from another machine.
Each machine row shows its cores, how many agents work there, and its load as a bar. The machine with the most free cores is first. A machine that does not report its load says "no load report". The order holds still while the sheet is open.
Any machine
With a linked host, the first machine row is Any machine. It names the machine the daemon would pick and why, in one line, such as build: 16 cores, 0 working, the repo is there. This machine stays picked unless you pick another row, so an agent never moves on its own. With Any machine picked, Start asks again and starts the agents there.
The daemon picks in three steps:
- It leaves a machine out when its link is not up, the agent is not installed or not signed in there, the agent reached its usage limit there, it has no checkout of the repository, its memory is 95% used, or it is at its
[tasks] machine_cap. - Of the rest, the most spare cores wins: the cores times the share the one-minute load leaves free, less half a core for each agent that works, starts or was just picked there. Memory over 80% used lowers it.
- Two machines within one core tie: the one with the checkout wins, then this machine.
The pick counts as a busy agent on that machine for 90 seconds, so a burst of starts spreads out. From a shell, tuios start-agent -s any:SESSION and tuios fan --host any use the same rule, and tuios call place-agent '{"agent":"claude"}' asks it without starting anything.
From a shell
The sheet runs two commands that you can run yourself:
# This folder
tuios start-agent claude --prompt "Make the LRU cache safe for concurrent reads."
# Three attempts, each in a new worktree: two Claude Code, one Codex
tuios fan 3 --agent claude,claude,codex "Make the LRU cache safe for concurrent reads."See start-agent and fan for their flags. --model, --effort and --permission-mode pass the agent's own flags:
tuios start-agent claude --model opus --effort high --permission-mode planPresets Unreleased
A preset names how you start one kind of agent, so a script or another agent starts it with one flag. Write it in config.toml:
[agents.presets.worker]
agent = "claude"
args = ["--verbose"]
add_dirs = ["~/notes"]
grants = ["read", "write", "task"]
model = "opus"
env = ["GOMAXPROCS=4"]
after_ready = ["/remote-control", "Enter", "Escape"]
ready_timeout = 180000Then start it:
tuios start-agent --preset worker --prompt 'Read ~/notes/briefs/api.md and do it.'
# Its pane id in a variable
id=$(tuios start-agent --preset worker --name w3 --print-id)| Key | What it does |
|---|---|
agent | The agent. With a preset, start-agent may leave it out |
args | More arguments for the agent |
add_dirs | Folders the agent may read too. Each is one --add-dir (the harness's [launch] add_dir_flag), before args. ~ is the home folder of the machine the agent starts on. A harness with no such flag refuses it |
grants | What the pane may do through tuios |
model, effort, permission_mode | As the flags of the same names |
env | Variables for the agent, each NAME=VALUE |
after_ready | Steps sent once the agent is ready, before --prompt. A step that is one key name (Enter, Escape, Tab, C-c) is that key. Anything else is typed as text. A step is refused while the agent waits on a prompt of its own, and that stops the rest |
ready_timeout | Milliseconds to wait for the agent to be ready |
A flag you pass wins over the preset's. args, env and after_ready are the preset's, then yours. The preset is read from this machine's config and sent in full to a session on another machine. An unknown preset is refused with the names there are. A change to the file applies at once.
--print-id prints the new pane's full id alone. When the agent is not ready, the pane is kept for you, the id is still printed, and the command exits non-zero.
The sheet's own preset
Ctrl+S in the sheet ("save as preset") keeps the sheet's choices for the next sheet. It is not an [agents.presets] entry: those are for start-agent, and you write them in the config. A mode that turns approvals off is never kept by Ctrl+S.
How do I
- Start an agent on a task without opening a pane first? Press Ctrl+B i, then n, type the task and press Enter.
- Let an agent change my working tree? Pick This folder.
- Race two agents on one task? Set Attempts to 2 and press v on it to give each attempt a different agent.
- Use the same agent and model every time? Pick them once and press Ctrl+S.
- Run the agent on my build machine? Pick the host in Machine. It needs a checkout of the repository.
- Let tuios pick the machine? Pick Any machine, or use
-s any:SESSIONfrom a shell. - Start the same worker from a script every time? Write an
[agents.presets.NAME]and runtuios start-agent --preset NAME.
Related
Inbox and Review
One list of everything your agents are waiting on, a view of every agent with its conversation and the forms it showed you, answers from wherever you are, safer approvals, replies queued for a busy agent, and a review of what an agent changed.
Task Boards
Task cards hold the work of a session or a repository, one unit each. Agents claim them, finish them and hand them on to a check and a review, and dispatch can give the next card to an agent that is free, or start an agent for each card.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.
