Free forever.No limits.
headless is a coding agent for the terminal: it reads your workspace, plans one move at a time, calls its tools in plain sight, and prints every step. Free to run forever on frontier models, not a cut-down local stand-in, with no account, no seat count and no usage cap.
Nothing hidden, nothing metered.
It is free to run, it draws on frontier models rather than a cut-down local one, and it never hides the work. headless keeps the whole run on the screen, in the order it happened, so you can read what it did, decide what it does next, and never wonder what it cost.
- 01
Free forever.
There is no trial to expire, no seat to buy and no usage meter to watch. Run it as long and as often as you like on frontier models, not a cut-down local stand-in; the price is the machine you already own.
- 02
It shows its work.
Every move is printed where you are already looking: the call the agent asked for, the result the machine returned, and the next call after that. Nothing is collapsed into a spinner.
- 03
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 the workspace than guess at it.
- 04
One move at a time.
A single tool per reply, drawn from a fixed set, with plain arguments you can read before anything runs. There is no batch step you did not see.
- 05
It stays in its lane.
Every path resolves against the root you started it in, and is refused if it lands outside. The blast radius of a bad instruction is a directory you chose.
- 06
It lives in your terminal.
No daemon, no account, no dashboard. One command in the shell you already have, a transcript, and a clean exit when the work is done.
One prompt. One move at a time.
headless runs a small, fixed loop: it reads before it writes, asks for exactly one tool per reply, runs that one call, and looks at the result before deciding what comes next. You can follow the whole thing as it happens.
- 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.
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.
A small, fixed set.
Nine things it can do, and only these. The agent does one at a time and prints it as it happens, so you always know what it just touched, and every path it reaches resolves against the workspace you started it in.
Read a file
Read a file and put its contents in front of the agent.
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.
Confined to your workspace.
The root you run it in is the whole world the tools can see. Every path is resolved against it and refused if it lands outside, so the blast radius of a bad instruction is a directory you chose.
- 01Every path resolves against the workspace root.
- 02No absolute paths, and no climbing out with ..
- 03node_modules, .git, dist and build are skipped when listing.
- 04The exec tool is closed until you pass --shell.
Two lines and a prompt.
The terminal is the whole interface, and the price is nothing. Every flag is optional and the loop has sane defaults, so the shortest path is also the intended one, and there is no plan to upgrade to.
Install it.
One command, wherever Node already lives. No account to make, no service to reach, nothing left running when you are done, and nothing to pay for later.
Node ≥ 26.4Open a folder.
Run it inside the project you want it to work on. That folder becomes the whole world the tools can see.
cd your-projectAsk for something.
Type the task and watch the loop: read, plan one move, call one tool, print the result, and go again. There is no usage meter above it.
Free forever$npm install$cd your-project$headless "explain this repo"
Run it in whatever directory you want it to work in. That is the entire setup. Direct downloads and the per-platform notes are on the install page.
- --root<dir>
- Workspace the tools are confined to. Defaults to where you run it.
- --shell
- Turn the exec tool on for this run.
- --max-turns<n>
- Stop the loop after n tool rounds. Default 12.
- --timeout<ms>
- How long to keep waiting for a slow answer. Default 180000.
- --help
- Every flag, from the terminal.
- Price
- Free
- Forever, no limits
- Tools
- 09
- Workspace-confined
- Loop guards
- 03
- Keeps it honest
- License
- Proprietary
- All rights reserved
Questions, answered.
The short version of everything above. If something is still open, the terminal has the long version: --help prints every flag and every command it accepts.
Nothing. headless is free to run, forever. There is no trial to expire, no seat to buy, no usage cap and no account to create. Run it as often and for as long as you like, and it draws on frontier models the whole time: free here does not mean the weaker brain.
A terminal and Node 26.4 or newer. There is no separate runtime to install and no service to sign up to.
No account and no sign-in. headless runs entirely on the machine you started it on, under your own root and your own keys.
Yes, and only once. On the very first launch headless sends a single request so the people who build it can count how many people are using it, then nothing more. It never sends your prompts, your files or your workspace, and there is nothing to switch off because there is nothing recurring to stop.
The root you launched it in, and nothing outside it. Paths are resolved against that root and refused if they climb out, and the noisy directories (node_modules, .git, dist, build) are skipped when listing.
Yes, but the exec tool is closed until you pass --shell for the run. It never reaches the agent's list by accident; you open it on purpose.
Three things stop it. It asks for one move per reply, so a reply that only describes an action is asked again in the shape the loop can act on; and if the same call with the same arguments comes back twice, the loop stops rather than spinning.
Esc interrupts a reply, and ctrl+c quits. Nothing is left running behind you.