Super-Agents: Real Agents Commanding Headless CLI-Agent Fleets
Note on dates. Written 2026-06-29, published 2026-08-16 after every tool name in it was checked against the shipped implementation. The control-surface table below was wrong in the original draft and has been corrected — see "The control surface" for what changed.
The coding-agent CLIs are good now — Claude Code, Codex, Gemini, OpenCode. The obvious next move is to run a fleet of them. The non-obvious part is who drives. In our model the answer isn't a human at a terminal. It's another agent.
A super-agent is a lightweight, automated wrapper around an existing CLI agent. You attach context, credentials, and git repositories to it, and it runs headless in a sandbox — no console exposed to the end user. The org's real agents (CEO, CTO, DevOps) spawn and command super-agents over MCP; humans don't operate them, they observe them. This post is the architecture.
First, which "super-agent" this is
We have overloaded this term, and you will hit the others. To be explicit about which one this post means:
| Where you'll see it | What it means there |
|---|---|
| Introducing the Super Agent | The AI-CEO orchestrator that delegates across your org |
| The Super Agent Console | The super-agent-ceo CLI turning your machine into a node your org can drive |
| Shared pool | A pool of scale-to-zero runner pods, a compute/pricing construct |
| This post | A headless wrapper around a CLI coding agent, spawned and commanded by another agent |
They are related but not interchangeable. If you only need one, the second is the one most readers arrive looking for.
The shape of a super-agent
Rendering diagram…
A super-agent is [ a CLI coding agent ] + [ attached context, credentials, repos ], running headless, driven by a real agent, watched through observability — not through a console.
Attach is one declarative spec
The whole "give it context, credentials, and repos" idea is a single object, not a pile of flags:
SuperAgentSpec = {
"cli_agent": "claude-code", // the engine (adapter)
"context": { "charter": "…immutable instructions…", "task": "…" },
"credentials": [ { "ref": "keychain://org/anthropic", "as_env": "ANTHROPIC_API_KEY" } ],
"repos": [ { "url": "git@github.com:org/repo.git", "branch": "main", "mount_path": "/work/repo" } ],
"budget": { "total_usd": 5.0, "stop_on_exhaust": true }
}
Credentials are references, never inlined — they resolve from a keychain at runtime and never hit a log. Repos clone into the operand's workspace. The charter is immutable — the super-agent can't rewrite its own marching orders.
The control surface is for agents, not people
A super-agent has no end-user console. Instead it exposes MCP tools that a real agent calls.
These are the literal tool names. The original draft of this post printed shorthand — run(id, task, mode), pause / resume / stop(id), observe(id), delete(id) — and none of those resolve to anything. A reader copying that table would have got nothing back. Each name below was checked against the shipped implementation before publishing:
| Tool | What a real agent does with it |
|---|---|
spawn_super_agent(spec) | Materialize a headless worker from the spec |
attach(id, {context,credentials,repos}) | Add or refresh what's attached |
super_agent_run(id, task, mode) | Dispatch a task — one-shot, or hand it to a loop |
pause_super_agent(id) / resume_super_agent(id) | Lifecycle |
stop_super_agent(id) | Halt the worker |
observe_super_agent(id) | Subscribe to its live event/audit stream |
delete_super_agent(id) | Tear down |
This is the real shift: the operator is an agent. A human "creating a node in a dashboard" was the training-wheels version. The product version is the CTO agent spinning up six Codex super-agents, attaching the monorepo and a scoped token to each, and running them.
No console means observability is mandatory
If a person isn't watching a terminal, you need a different window — and it has to be machine-readable, because the watcher is often another agent. Every super-agent emits a structured stream: task_started · step · tool_call · file_diff · commit · cost_delta · blocked · error · done, plus tokens and cost. We surface it three ways:
observe_super_agent(id)— a real agent subscribes and reacts, for example a governor that swaps out a stuck worker.- Read-only live transcript — what a console would show, minus the input box.
- The Observe graph — super-agents render as nodes; the edge to their controlling real agent shows who's driving; status and budget live on the node.
Observability isn't a nice-to-have here. It's the only way to run a headless, agent-commanded fleet without flying blind.
Why this matters: loops over fleets
Once a real agent can spawn and observe super-agents, it can run a loop over a whole set of them: an Observable Loop where the governor is a real agent and the operands are super-agents. An AutoResearch swarm where each experiment is a super-agent in its own sandbox. The super-agent is the worker; the loop is the coordination; the Observe graph is the shared window.
That's the operating model: real agents ↔ super-agent fleets ↔ observability, with loops as the layer that ties them together.
Key takeaways
- A super-agent = a CLI coding agent + attached context/credentials/repos, headless, agent-driven. It is not the AI-CEO orchestrator or the shared compute pool, which share the name.
- Attach is one declarative spec; credentials are references, the charter is immutable.
- The control surface is MCP tools for real agents — there's no end-user console, and the tool names are
*_super_agent, not bare verbs. - No console makes observability (stream + transcript + graph) a hard requirement, not a feature.
- The payoff is real agents running loops over fleets of super-agents.