The 9 subagents inside Freebuff (and when each one runs)
A field guide to the specialized workers that make a CLI agent feel agentic.
TL;DR
- Freebuff orchestrates 9 specialized subagents instead of one general "do everything" model.
- Each subagent has narrow scope, narrow context, and narrow trust.
- The main agent decides which subagents to spawn for each task.
- You can also spawn them by hand with
/agent <name>.
Big agents are bad at small tasks; small agents are bad at big ones. Freebuff splits the work: a coordinator picks the right subagent for each turn. Here is the cast.
1. file-picker#
Runs Gemini 3.1 Flash Lite against a local code map to find the files that matter for the current task. Returns ranked paths plus a one-line justification per file. Almost every other subagent depends on it.
2. code-reviewer#
Reads diffs after an edit and reports issues by severity. Catches obvious regressions, missing tests, and security smells. Runs automatically after any multi-file edit; trigger manually with /review.
3. browser-use#
Drives a real Chromium instance to verify the app you just edited still works. Logs in, navigates, asserts on the rendered DOM, takes screenshots. Used heavily on full-stack tasks generated from Freebuff Web.
4. thinker-gpt#
When a turn needs deep reasoning, the coordinator hands off to thinker-gpt. With /connect-chatgpt, it routes through your ChatGPT subscription to use GPT-5.4 — free inside Freebuff.
5. researcher#
Does web research with citations. Useful when the task touches an unfamiliar library or API. Returns a short brief with linked sources.
6. test-runner#
Detects the project’s test framework (vitest, jest, pytest, go test, cargo test) and runs only the relevant tests. Streams failures back to the coordinator for repair.
7. git-curator#
Stages, commits, and writes commit messages that match the repo’s historical style. Opens PRs with /pr. Refuses to push to main unless you explicitly ask.
8. shell-runner#
Executes shell commands inside a permission boundary. Destructive commands always require approval. Long-running processes are backgrounded with output streamed to a terminal file the main agent can read.
9. project-scout#
New in 2026: indexes the repo on first run and keeps the index warm. Tracks recent edits, build outputs, lint errors, and stack metadata so the coordinator has a fast structural understanding without re-reading the whole tree.
Why subagents beat one big model#
- Scope of context. The reviewer does not need browser logs. The browser does not need shell history.
- Scope of trust. The shell-runner can refuse what the coordinator cannot.
- Scope of cost. File-picker can run on a cheap, fast model. Thinker-gpt can run on the smartest model only when needed.
- Parallelism. Independent subagents run concurrently and stitch results back together.
Can I disable a subagent?+
--no-subagent <name> at startup, or set it in your project’s .freebuffrc.