oat-agents

Why

Most coding agents can already hand work off to subagents. That works for one or two. With five on a real change, it gets hard to follow.

A team of coding agents runs into two problems.

The first is that the information doesn't reach you. Inside one session, every subagent's output lands in the same scrollback. You can't see which one is stuck, and when one goes wrong you can't talk to it directly. All you can do is ask the parent to pass a message along. You need to see each agent's context.

The second comes from the obvious fix. If the agents have to keep a record for you, that record is extra work on top of the change, and every note an agent writes for you is attention it didn't spend on the change. An agent should do its work and nothing extra.

So oat-agents has to do three things at once, with as little structure as it can.

Three things, with the least structure

A simple structure

A team has two levels: one meta-agent, which splits your goal and hands out the pieces, and the member agents it launches. Who is on the team, how the work is split and which skills each role loads all live in a plugin. Changing how your team works never means changing oat-agents. See Define your team and its rules with a plugin.

No extra work for the agents

A member agent is plain Claude Code or Codex, in its own interactive interface. Besides the change, it only sends the meta-agent a report when it's done, or a question when it's blocked. oat-agents takes care of the rest: a git worktree and branch for each agent, and a pod for its build and test commands when its role asks for one. See Execution and isolation.

Context you can see

The live view shows only the flow of information: one row per agent, with its state, diff, timeline and log, and the whole team on one screen. When you want to act, select an agent and press enter. You're typing into its real tmux session, the same as if you had opened it yourself. ctrl+] brings you back to the team. See How a Run goes.

How a Run goes

That is oat-agents tui. The Run is illustrative, but the layout, glyphs and keys are the real ones.

1. You start a Run with a goal: oat-agents meta fire --prompt "…". Describe the outcome you want, not the steps.
2. The meta-agent launches member agents with role fire: a planner, two workers, a reviewer, or whatever roles your plugin defines. It doesn't write the code itself.
3. Members write to the meta-agent through the Run inbox. One that finishes sends its report (dispatch done); one that is blocked asks a question (dispatch ask) and waits for the reply. Only the meta-agent reads the inbox.
4. When the meta-agent needs a decision it can't make from the goal, its row shows 🙋. Select it, press enter and type your answer. Otherwise it doesn't ask.
5. When a review fails, the fix goes to a new member agent. The failed attempt keeps its row, its report and its place in the workflow log.
6. The meta-agent closes the Run with meta finish and prints a receipt. The work is on the Run's oat/<run>/… branches, and you review and merge it.

You choose how close to work. Stay at the top: read the roster, open the meta-agent's checklist (ctrl+l), or ask the meta-agent where things stand. Or go down to any member, read its diff, and work with it directly.

Define your team and its rules with a plugin

How your team works lives in a plugin, a directory of Markdown and TOML. It says which roles exist, what each one is told, which model it runs on, and how the meta-agent should split work and when it should ask you. The core supplies the mechanism and nothing else (ADR-0001, ADR-0004).

The example plugin ships planner, worker and reviewer so oat-agents does something useful on day one. Your plugin can keep them, replace them, or add a tester, a security-auditor, or a migrator that runs four at a time. A team with no planner at all works too.

A new role is one directory with two files:

team/
├── oat-plugin.toml
├── core/
│   └── oat-meta-instruction.md          # tell the meta-agent when to use your roles
└── roles/
    └── security-auditor/
        ├── role.toml
        └── instructions.md

# team/roles/security-auditor/role.toml
description = "Audits a change for security issues and reports findings with evidence."
start = "existing"          # run inside the worktree of the change under audit
exec_environment = false
max_concurrent = 1

[model.claude]
model = "opus"

<!-- team/roles/security-auditor/instructions.md -->
# Security auditor

You start in the worktree of the change under audit. Look for injection, authorization gaps
and leaked secrets. Report each finding with the file, the line, and why it is exploitable.

Pin it next to the example team (or on its own), trust it once, and the next Run can use it:

oat-agents init --force --embedded --path team my-team
oat-agents plugin list --repo .          # prints the exact trust command for each plugin

Every TOML file rejects unknown fields, so a typo fails at load time instead of being silently ignored. The full format is in docs/plugins.md.

Execution and isolation

oat-agents is a single Rust executable, and there is no server, database or daemon behind it. A Run is branches, tmux sessions and plain files under ~/.local/state/oat-agents/. That includes the workflow log, an append-only JSONL file you can tail -f, jq or grep.

Each member agent gets a worktree on its own branch (oat/<run>/<name>) and a tmux session on oat-agents' private tmux server. meta fire and role fire print the command that attaches to it (tmux -L oat attach -t oat_<…>).

A role that sets exec_environment = true runs its build and test commands in a pod built from your .devcontainer/ (Kubernetes today), as long as the Run has an execution profile. The agent itself, and everything else, stays on your machine. The live view shows pod:… beside each agent, or HOST (no pod) in yellow when a role wanted a pod and didn't get one. If the environment couldn't run a check, the role protocol has the agent report it as unverified, never as a pass.

Agents run unattended. Nobody is there to approve each step, so oat-agents starts your agent CLI with its permission prompts turned off. A worktree keeps each agent's work apart, but it doesn't limit what the agent can reach