DOCS · TERMINAL & AGENTS
The terminal it drives, the crew it dispatches.
SynthOS runs real command-line tools on your Mac on your behalf, and turns a single ask into several agents working in parallel — each on its own piece of the job. You see the command and its result, never a hidden process. This page documents both surfaces: how the terminal is driven, how the crew is formed, what you watch while it works, and how agent limits map to your plan.
THE TERMINAL
The command-line, driven for you.
The terminal in SynthOS is a real shell on your Mac. The difference is who types: you describe the outcome in plain language, and the agent runs the actual command for you.
When a job needs the command-line, SynthOS does not simulate it and it does not run it somewhere else. It opens a shell on your machine and invokes the same tools you would run by hand — git, npm, ffmpeg, curl, a Python script, whatever the task calls for. The working directory, the files, the installed binaries, and the environment are all yours. Nothing about the execution is a stand-in.
What makes it a documented surface rather than a black box is the rule that every command is shown with its result. For each step you see the exact command line that ran and the output it produced — the same text you would have seen if you had typed it. There is no hidden process running off-screen, and no summary standing in for what actually happened.
Because the work happens locally, the terminal is also where SynthOS is most honest about its limits. It can only run what your Mac can run, it acts inside the permissions your account already has, and a command that would touch something outside the job is held for your approval first (see Safety on the terminal).
DISPATCH & PARALLELISM
How an ask becomes a crew.
One request rarely maps to one action. SynthOS reads the ask, breaks it into pieces that can run independently, and dispatches an agent to each — so the work happens in parallel instead of one slow line at a time.
You make one ask
You describe the outcome in plain language — “pull the latest issues, summarise each one, and draft a reply.” You do not assign tasks or open tabs. The ask is the whole instruction.
It plans, then dispatches
SynthOS decomposes the ask into pieces that don’t depend on each other, and dispatches an agent to each. Pieces that genuinely need an earlier result wait for it; everything else starts at once.
Each agent owns its own piece
Every agent gets one slice of the job and the tools to do it — a terminal, the browser, your files. It runs its own commands, keeps its own receipts, and reports back. Agents work side by side, not in a queue.
The results converge
As agents finish, their results fold back together into the single answer to your ask — and into your vault, where the work is kept. You directed once; the crew did the rest.
# parallelism is bounded, not infinite. how many agents run at once # is set by your plan tier (see “Agent limits by tier”). # when the ask needs more pieces than your tier can run together, # the extra ones queue and start as slots free up — nothing is # dropped, only ordered.
TRANSPARENCY
Watching agents work side by side.
A running crew shows up as a row of run cards — one per agent. Each card carries that agent’s piece of the job, its current status, and the commands and results as they land.
The cards above are an illustration of the surface, not a live run. In the app the status, command, and output update in place as each agent works.
Nothing about a run is summarised after the fact in place of showing it. While an agent works you can read the command it just ran and the output that came back; when it finishes, the card settles to a final status you can scroll back through. If something needs your decision, the card pauses on that agent and asks — the rest keep going.
Because every agent reports the same way, you can hold the whole crew in view at once: which pieces are running, which are waiting on another result, which are done, and which one (if any) is asking for approval. Transparency here is structural — the surface is built so there is no off-screen work to miss.
CONCURRENCY & PLANS
Agent limits by tier.
How wide the crew can run at once depends on your plan. Higher tiers raise the number of agents that work in parallel and how quickly your jobs are dispatched.
Runs a few jobs at once. Enough parallelism for everyday work — a handful of agents on the pieces of a single ask — without waiting on a queue for ordinary tasks.
Everything in Build, plus priority dispatch: your asks are picked up and fanned out ahead of lower tiers, so a crew starts sooner when you have several things going.
The widest crew — up to 12 agents working in parallel on one ask, with priority dispatch. For jobs that break into many independent pieces and benefit from running them all at once.
Limits affect how many agents run together and how soon they start — never what they’re allowed to do. The terminal is real, the commands are shown, and the safety rules apply the same way on every tier. A bigger plan is a wider lane, not a different set of powers.
See the plans and what each tier includesYOUR TOOLCHAIN
Connecting your own command-line tools.
SynthOS runs on your Mac, so it runs the tools your Mac already has. Anything on your PATH is fair game the moment it’s installed — there is no separate registry to populate.
Install a new CLI the way you normally would — a package manager, a download, a script — and agents pick it up instantly. Because the terminal is your real shell, a freshly installed binary is on the path for the next command without any configuration step on the SynthOS side. The same is true of tools you’ve had for years: they’re already available.
Tools that need a key or a login use your credentials, stored locally, exactly as they would in a shell you opened yourself. SynthOS doesn’t proxy your toolchain through a service or add a markup — it invokes the tool directly on your machine.
Connecting richer integrations — services, accounts, and non-terminal capabilities — is covered separately.
Read Tools & IntegrationsGUARDRAILS
Safety on the terminal.
A real shell on your Mac is powerful, so the guardrails are part of the surface, not an upsell. They apply on every tier.
Ask-first on risky commands. Anything destructive or hard to undo — deleting files, force-pushing, changing system state, spending money — pauses for your explicit approval before it runs. Routine, reversible commands proceed and are shown.
A receipt for every action. Each command and its result is recorded — what ran, when, and what it returned — so the terminal leaves an audit trail you can read back instead of a black box you have to trust.
A spend ceiling. You set a limit on what a run can cost through your own provider key. When a job approaches the ceiling it stops and asks rather than quietly running up a bill.
A kill-switch. You can stop a single agent or the whole crew at any moment. Stopping halts the commands in flight and leaves the receipts of everything that already ran, so you can see exactly where it ended.
The terminal never acts behind your back: risky commands wait for you, everything that runs leaves a receipt, and one switch stops it all.
OUTPUT & ERRORS
Reading terminal output and errors.
What you see is the tool’s real output — the same standard out, standard error, and exit code the command produced. Nothing is paraphrased in its place.
A command that succeeds shows its output and moves on. A command that fails shows the error text the tool printed and the non-zero exit code it returned, on the agent’s run card. The failure is surfaced, not swallowed — you can read the actual message, not a softened summary of it.
When an agent hits an error it can often act on, it will try a sensible next step — read the message, adjust, and run again — and every one of those attempts is shown as its own command and result. If the error needs a decision only you can make, the agent pauses and asks rather than guessing, and the rest of the crew keeps working in the meantime.
Because the full transcript — commands, output, errors, exit codes — is kept as receipts, you can scroll back through exactly what happened after a run finishes. There is no separate “debug mode” to switch on: the honest record is the default view.
# exit 0 → shown and continued. non-zero → error text + code shown, # not hidden. retries are visible commands, not silent magic. a # decision only you can make → the agent asks. the receipts are the # source of truth you can re-read.
KEEP READING
See the terminal and the crew run.
The terminal and the agent model are two parts of one surface — SynthOS, the AI operating system for a company of one. Watch it run, or read how the rest of the app fits together.
Real terminal execution on your Mac · Transparent commands · Parallel agents · Ask-first on risk.