One prompt.
Then one move at a time.
headless does not plan a folder of changes and then hand you a diff. It reads, decides one move, makes that move, looks at what came back, and only then decides the next one. You watch the whole thing in the order it happened.
Five beats, over and over.
Every run is this loop, from the first prompt to the summary at the end. Nothing happens between the beats that is not printed on one of them.
- 01you
You type a task.
A question, a request, or `!` for a raw shell command. Anything after `!` runs as-is and never reaches the agent.
- 02agent
It reads before it writes.
The first move is almost always to look: list the directory, read the file, search for the symbol. It would rather check than guess.
- 03agent
It asks for exactly one tool.
One call per reply, named in a fixed set. Nothing happens in bulk: each step is a single, inspectable move.
- 04machine
The machine runs it, in scope.
Resolved against the workspace root and nowhere else. You see the call, you see the result, on the same screen.
- 05agent
Repeat until it is done.
The loop ends when the work is finished and summarised, or when the task was only ever a question, in which case it just answers.
Three things stop it.
A loop that never ends is not a feature. Three rules keep this one bounded, and all three are visible from the terminal: you never have to wonder whether it is working or wheeling.
One move at a time
The agent asks for one tool per reply and the machine runs exactly that. There is no batch step you did not see.
A repair pass
If a reply describes an action instead of asking for it, it is asked again, this time in the shape the loop can act on.
A repeat stop
If the same call with the same arguments comes back a second time, the loop stops instead of spinning its wheels.
If a reply only describes an action, it is asked again in the shape the loop can act on. If the same move with the same arguments comes back twice, the loop stops there rather than repeating itself forever. And when it is out of things to do, it says so and exits.
Everything is printed.
The ask, the move and the result, each on its own line, in the order it happened. Read the transcript top to bottom and you have read the whole run. There is nothing underneath it.
- /help
- List everything.
- /tools
- Show the tool catalogue.
- /clear
- Clear this terminal's transcript.
- /info
- Workspace, counters, paths.
- /new
- Start a clean conversation.
- /exec on|off
- Turn the shell tool on or off.
- /quit
- Exit.
- /
- Open the command palette, fuzzy search.
- !
- Shell mode: run a command, stream its output.
- ↑ ↓
- Walk back through your prompts.
- esc
- Interrupt a reply, and kill a running ! command.
- ctrl+c
- Quit.