Subagent harness, featherweight.
fwt is a headless coding agent that other programs run as a subagent.
You give fwt one task. It works in a directory with shell commands until the task is done, and then it prints the answer. A script, an editor, or another coding agent can start it. Each fwt process runs one agent, and the program that starts it decides what each agent does.
A coding agent that hands work to a subagent needs that subagent to be cheap, predictable, and easy to read from a program. Interactive agents are built for a person at a terminal. fwt is built for the program that starts it:
- One task, one process. fwt takes a prompt and returns the answer on standard output, or every step as JSON Lines. The exit code says whether it finished, ran out of context, looped, or hit the step limit. There is no terminal interface, no MCP server, and no subagent of its own.
- A small tool set. The model gets three tools: one runs shell commands, one writes to a running command, and one reads images. It edits files with shell commands, so there is no patch format to learn.
- Built around the prompt cache. The system prompt and tools never change, and history only grows. When the context fills up, the same model writes a summary from the prefix that is already cached, and the session continues.
- Sessions you can branch. You can resume a session, or fork it so that several runs continue from the same history in separate worktrees and share its cached prefix.
- Any provider. fwt speaks OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, and sets up providers from models.dev. Routine tests run on small, inexpensive models such as DeepSeek V4.1 Flash and GLM-5.3 Flash.
- ACP when you need it. Editors and orchestrators can drive the same agent through the Agent Client Protocol.
Install fwt from npm:
npm install -g @moeru-ai/fwtYou can also run it without an install, with npx @moeru-ai/fwt in place of fwt.
Add a provider. fwt finds it on models.dev, asks for your API key, and lets you select a model:
fwt provider add deepseekGive fwt a task in the directory where you want it to work:
cd /path/to/project
fwt -p "Fix the failing test in src/parse.test.ts"The fwt skill tells a coding agent how to give a task to fwt and how to read the result. Install it for your projects with the skills command:
npx skills add moeru-ai/fwtThen ask your coding agent to give a task to fwt.
fwt runs each command with bash -c <command>. To run commands in a sandbox, set shell in ~/.config/fwt/config.toml to a program that also accepts -c <command>. fwt itself does not include a sandbox, and the model requests, API keys, and session files stay outside it.
For example, sandbox-runtime (srt) limits file writes and network access. On Linux it needs bubblewrap and socat:
npm install -g @anthropic-ai/sandbox-runtimeshell = [
"srt",
"--settings",
"/home/me/.config/fwt/srt.json"
]This srt.json lets commands write only in one project directory and blocks the network:
{
"filesystem": { "allowWrite": ["/home/me/project"], "denyRead": [], "denyWrite": [] },
"network": { "allowedDomains": [], "deniedDomains": [] }
}Use absolute paths in srt.json. srt resolves a relative path from the directory where the command starts, which can be a subdirectory.
fwt has no MCP client. The model can use MCP servers through mcpdo, a command that keeps named connections open in a background process. Install it and connect your servers before you start fwt:
npm install -g @modelcontextprotocol/inspector
mcpdo connect @docs https://example.com/mcp
mcpdo connect @fs -- npx -y @modelcontextprotocol/server-filesystem /home/me/projectThen install the mcpdo skill, so fwt lists it and the model reads it when a task needs a server:
npx skills add modelcontextprotocol/inspector --skill mcpdoThe model then runs commands such as mcpdo @docs tools/list --format json. Because commands from fwt have no terminal, every command must name its connection with @name. When a server needs a sign-in or asks a question, mcpdo returns a URL or a question ID, and the model gives it to you in its answer.
The MCP servers run in the mcpdo background process, outside a shell sandbox. On Linux, srt blocks the socket that mcpdo uses. To allow it, set "allowAllUnixSockets": true under network in srt.json. This setting allows every Unix socket, for example the Docker socket, so use it only when you trust that access.
The fwt command tells you how to add providers and run tasks. It also lists the flags, the environment variables, and the files.
fwt takes ideas from Codex and Pi. From Codex, it takes the exec_command and write_stdin tools, the provider configuration in TOML, and the retry rules for model requests. From Pi, fwt draws inspiration from the idea of keeping an agent harness small and focused.