SOPHIAXT
Run several coding agents at once, from one terminal.


WHAT THIS IS

You already have agent CLIs installed. Claude Code, Codex, Kimi, whatever you
use. Each one is fine on its own and each one owns your terminal while it runs,
so in practice you run one at a time and babysit it.

This runs a supervisor in the background that owns those processes instead. The
board is a window onto it. Close the window, close the terminal, open it again
on the other side of the room: the agents keep going. That split is the whole
design, and everything else follows from it.

There is no account, no token and no server. It drives what is already on your
machine and keeps its state in your own data folder. Delete that folder and you
are back to a clean install.


GETTING STARTED

Unzip it anywhere and run it, or run "sophia install" to put it on your PATH.
docs/INSTALL.txt has every route in, and the one route out.

    sophia setup           walk through what is set up and what is not
    sophia                 open the board
    sophia doctor          the same report as setup, no questions
    sophia guide           this text
    sophia --help          every command

Run setup first if you have never used this. It looks at what is on the machine,
tells you which engines are ready and which are not, offers to test the ones it
is unsure about, and writes the starter skills. It asks before anything that
costs money and defaults to no.

From inside a project, run sophia and type a name into the box at the bottom.
That starts a session. After that the box talks to the tab's lead agent, and a
line beginning with / is a command instead of a message.

    /agent                 add an agent: pick the engine, then the model
    /auto <task>           let it choose the engine, and say why it chose it
    /route <task>          the same reasoning without starting anything
    /tab review            another workstream, with its own lead agent
    /panes                 one, two or four agents on screen at once
    /all <message>         say something to every agent at once
    /propose codex <task>  ask for a helper on a different engine
    /theme punk            midnight, daylight, punk, evil, amber
    /matrix                rain in the empty space, if you like that
    /help                  everything

There are almost no keyboard shortcuts, on purpose. Letters type. Arrows move
between agents and sessions, tab moves between workstreams, ctrl-K opens a
command palette and ctrl-C detaches without stopping anything. Everything else
is a button you can click or a command you can type.

The whole board is clickable: tabs, the sessions in the sidebar, agent rows,
panes, and every button along the top. Right-click gives you copy and paste,
and the divider between the panes drags. It opens filling the screen, because
four panes in an eighty column window is four unreadable boxes. Set maximize to
false in settings.json if you would rather it did not.


EVERY PANE IS ITS OWN TERMINAL

Open two or four with /panes or the Panes button. Each one has its own command
line along its bottom edge, its own scroll position, and its own half-typed
draft that survives you clicking somewhere else.

Click a pane and the keyboard points at it. The wheel scrolls whatever the
pointer is over rather than all of them at once, so reading back through one
agent's output leaves the others where they were. Escape steps back out to the
wide field along the bottom, which addresses the tab's lead agent instead of any
one pane. That is the one to use when you want to tell the tab what it is for.


THE WORKING OUT IS FOLDED AWAY

An agent's reasoning and its tool output are collapsed by default, each behind
one line saying how much is hidden. The answer is the part you wanted, and it
should not be four screens below the top.

Click the line to open it. Errors and answers are never folded, because an error
you have to expand is an error you miss. Nothing is thrown away: everything the
agent printed is still in the transcript, and a search looks inside the folded
parts too.


TABS ARE WORKSTREAMS

Each tab has its own lead agent and its own helpers under it. The api rebuild in
one, the review pass in another. The tab strip carries a count per tab, so a tab
with something stuck says so from the outside and you do not have to open it to
find out.

Click + Tab in the strip, or type /tab review. Watching one agent at a time is
how you miss the one that fell over.


EVERY AGENT GETS ITS OWN COPY

Two agents editing one folder share an index and a branch, so the moment either
one stages something they corrupt each other, silently, and the first sign is a
mangled commit. So when a session is in a git repository and more than one agent
is working in it, each helper gets its own checkout on its own branch.

    sophia trees                  who is working where
    sophia tree diff <agent>      what that one changed
    sophia tree merge <agent>     fold it back into the base branch
    sophia tree drop <agent>      give the checkout up, keep the branch

Nothing here is ever forced. Closing a session reclaims the clean checkouts and
keeps any with uncommitted work in them, and says which and why. A branch is
never deleted unless you ask twice.

    sophia spawn <session> <engine> --isolate      make it certain
    sophia spawn <session> <engine> --no-isolate   share the session's tree

The cost is worth knowing. A fresh checkout has no build output, no
node_modules, no .venv and no .env, because git ignores them, so an isolated
agent pays a cold build. Rust is handled: every checkout of a repo shares one
CARGO_TARGET_DIR, so the second agent builds warm. Node and Python are not
solved, and an isolated agent there runs its own install.


PICKING THE ENGINE FOR YOU

    /route rename every use of ctx_pct across the repo

reads the task, scores every engine you actually have against it, and tells you
which one it would use and why, in a sentence. /auto does the same thing and
starts the agent.

It refuses to guess quietly. An engine whose last probe failed scores nothing
and is named as excluded. When the top two are within a hair of each other it
says the margin is too thin and asks you to choose, because a coin toss you did
not know about is how work lands on the wrong model.


PICTURES

    sophia image screenshot.png
    sophia image diagram.png --ascii

PNG and BMP, decoded here rather than shelled out to anything, drawn with half
blocks so you get two rows of pixels per line of text.


MEMORY

Every agent gets a private file that nothing else reads, and every session gets
one shared file that all of them read and write. Private is scratch. Shared is a
deliberate handover: decisions made, interfaces agreed, files claimed, dead ends
already ruled out.

Both are prepended to future prompts, which is why the shared file says to keep
it short. Every line you add costs the other agents context.


HELPERS NEED YOUR SAY-SO

A lead agent can ask for a helper. A box appears with approve and deny buttons,
or type /approve or /deny. Nothing spawns on its own.

That gate is deliberate. An agent that can quietly multiply is an agent you
cannot budget for, and the first you would know about it is the bill.


AGENTS CAN DRIVE THIS TOO

They run the same sophia command you do, under a narrower set of rules. They may
read the board, message each other, and ask for helpers. They may not spawn,
approve, kill or shut anything down. Every agent carries its own credential, and
the supervisor works out who is asking from that rather than from anything the
request claims about itself.

Be clear about what that is and is not. It stops an agent doing the wrong thing
by accident, and it stops a model deciding on its own that it needs four more
helpers. It is not a wall around a hostile process. An agent runs as you, on your
machine, with your files, so an agent determined to get around it can read the
same things you can. Real containment needs a sandbox or a separate account, and
this does not ship one.

So the charter is a guardrail, not a boundary. Do not hand an engine you would
not trust with your login a folder you care about.


CONTEXT

Every model has a limit on how much it can hold at once, and when it runs out it
throws away the middle of the conversation. The board shows how close each agent
is and asks it to write its notes out before that happens, while doing so is
still cheap.

A measured figure shows as 62 percent. A guess shows as ~62 percent, with the
squiggle. Some engines report their token usage and some do not, and a guess
presented as a measurement is worse than no number at all.


NOTHING IS LOST TO A CRASH

Kill the supervisor mid-thought and it comes back with every session, task and
transcript intact. Then:

    sophia resume <session>

hands each interrupted agent its own transcript back and tells it to carry on
rather than start over.

One thing a kill does not reach: a backend that deliberately detaches a child
of its own, the shell equivalent of `start /B`, can leave that child running
after its agent is gone. None of the real engines do this, and the supervisor
catches everything they do start, but if you write a tool that detaches, it is
yours to clean up.

The processes themselves do not survive, and they cannot: you cannot reattach a
pipe to the child of a dead parent. What survives is everything needed to pick
the thread up again, including the engine's own conversation id, so a resumed
agent continues the same conversation rather than opening a fresh one.


ENGINES

Claude Code, Codex, Kimi, OpenCode, Gemini, Cursor Agent, Aider, Grok, Prime,
and plain shell commands.

    sophia agents
    sophia models codex           what that engine says it offers

Adding an agent asks two questions, not one: which engine, then which model.
The model list comes from the engine itself where it will answer, because a
list compiled into this binary goes stale on the vendor's schedule rather than
ours. Anything you type is passed straight through, so a model released this
morning works without waiting for a new build. Leave it on default and the
engine picks.

    sophia spawn <session> <engine> --model <name>

does the same from the command line.

Read that output carefully. "configured" means a credential file exists on disk.
That is not the same as working, and the difference has cost people an afternoon
before. To find out:

    sophia probe claude

which makes one real call and tells you what happened. The result is remembered,
so an engine that failed will not be picked for you later.

Some engines are an API key rather than a program. Mercury from Inception Labs,
and Gemini through either of its two API surfaces. They have nothing to install:

    sophia key                    what is set
    sophia key set mercury        type the key, it is not echoed
    sophia models mercury         what that provider offers
    sophia key model mercury mercury-2

Mercury is a diffusion model rather than an autoregressive one, which in
practice means it is very fast. Credit to Inception Labs for it, and for an API
whose error messages actually say what went wrong. That suits the tight edit-and-check loops this
thing spends most of its time running, so it is worth having even if it is not
what you reach for on a hard design question.

A probe on an API engine makes the smallest real completion the provider will
take, not a model listing. Listing models is not proof of anything: Inception's
endpoint answers happily to a key you invented, so a probe built on it could
never fail, and a check that cannot fail is worse than no check.

Keys are typed in, never passed as an argument. Arguments are readable by every
other process on the machine and they end up in your shell history, so a key
passed that way is a key you have to rotate. They are never printed back either.
You get a four-byte fingerprint, which is enough to tell two keys apart and
useless to anybody else.


LOOK

    sophia theme                  list
    sophia theme punk             set

midnight, daylight, punk, evil, amber. On the board, click Theme in the toolbar
or the theme name in the bottom bar, or type /theme punk. Drag the divider
between the panes to resize the sidebar.

If symbols come out as empty boxes, your font is missing them. SOPHIA_GLYPHS=
sharp drops to square corners; SOPHIA_ASCII=1 drops to plain characters.


KEYS AND HOW HARD IT THINKS

The Engines button lists the CLIs it found and, under them, the engines that
take an API key instead: Mercury from Inception, and Gemini through either of
its two endpoints.

Press k on one of those to enter its key. Nothing is echoed while you type, and
the key is never drawn on the board afterwards. What you get back is a short
fingerprint, which is enough to answer "is this the key I think it is" without
putting the key on screen. Then press p to make a real call and find out whether
it works, because a stored key is not a working key.

The key column says one of three things and the difference matters when a call
fails. Stored means this program has it. In env means your shell has it and this
program is using that. Not set means neither.

Press e to change how hard an engine thinks. Each provider gets its own levels,
named the way that provider names them, because they are genuinely different
settings: Google takes a budget in tokens, OpenAI takes a named tier. An engine
with no such setting says so rather than showing you a dial that does nothing.
Mercury is one of those. It is a diffusion model, so there is no chain of
thought to spend more of, and pretending otherwise would be a setting that lies.

For the CLI engines, sign in the way that engine already documents. If a key is
already in your shell, this finds it: the Gemini CLI is logged in by any of
several environment variables and by a browser login, and all of them count.


MAXIN BITCHIN MODE

    sophia maxin "add a --json flag to ls so scripts can read agent state"

It plans before it builds. It asks you the questions a decent engineer would
ask first, works the goal into steps with real dependencies so several run at
once, picks an engine per step and tells you which and why, then loops verify
and fix until the suite is green or it runs out of rounds.

It swears at the work the entire way through. At the work, the code and its own
last draft. Never at you, and never inside an error message, because a stack
trace with a joke in it is a stack trace you have to read twice.

    --plan                 show the plan and the cost, start nothing
    --heat off             same orchestration, no swearing at all
    --heat warm            mild
    --yes                  skip the confirmation

It uses a lot of tokens and it tells you roughly how many before it starts,
worked out from the plan rather than picked to sound alarming. The low end is
one turn per step and a clean first verify. The high end is every fix round
spent, and a run that hits the round cap costs the high end and does not finish.
Five rounds is the cap, and when it hits it, it stops and writes down what is
still broken in plain words.

    sophia route "rename every use of ctx_pct"

is the same engine-picking reasoning on its own, if you only want the opinion.


SKILLS AND TOOLS

Skills are written instructions an agent can pull in by name. Tools are programs
it is allowed to run. Both work machine-wide, or for one project if you put them
under .sophia in the project folder, and the project one wins on a name clash.

    sophia skills
    sophia skill new my-check "what it is for"
    sophia tool git-diff-stat

A tool only runs if it is in the registry, looked up by exact name, and its input
is passed as a single argument or on stdin. Never through a shell. That is the
difference between a tool an agent can call and an agent that can run anything.


MCP SERVERS

An MCP server is somebody else's program that publishes tools. Point the harness
at one and its tools become ordinary tools, under the same verb:

    sophia mcp add fs npx -y @modelcontextprotocol/server-filesystem C:\work
    sophia mcp on fs
    sophia mcp tools
    sophia tool mcp.fs.read_text_file {"path":"notes.md"}

Arguments are a JSON object, or key=value pairs when that is easier to type. The
name is always mcp.<server>.<tool>, so two servers that both publish "search"
stay apart and neither can shadow a built-in.

A server arrives switched off, because adding one and running one are two
decisions. Discovery is cached: the daemon starts each enabled server once and
remembers what it offers, so building an agent's prompt and calling a tool never
wait for a server to start. The daemon keeps a started server warm, so the second
call to it is a round trip rather than another process.

    sophia mcp brief     exactly what an agent is told about your servers
    sophia mcp status    which servers the daemon is holding open

Use `brief` when an agent says it has no such tool. A server that is misconfigured
or not installed shows up there by name with the reason, never as an empty list.


WHAT AN AGENT CAN ACTUALLY DO

Every agent here can read and search its folder, change files in it, and look
things up on the web.

    read     one file                write   create or replace a file
    ls       a directory             edit    replace exact text in a file
    find     files by name           web     search the web
    grep     search file contents    fetch   read one web page

Paths resolve inside the agent's own folder and anything outside it is refused.
Each agent gets its own git checkout, so an edit it gets wrong is on its own
branch and not in your working tree.

`edit` matches exact text and refuses when that text appears more than once. A
tool that quietly changed all six occurrences would be a mass edit nobody asked
for, so it makes the agent include enough surrounding text to mean one place.

Claude Code and Codex bring their own versions of these and use those instead.
The engines that have no tools of their own, which is Mercury and the Gemini
endpoints, get them from the harness: it reads the tool blocks out of each
reply, runs them, and hands the results back as the next message. That loop is
what makes an API engine an agent rather than a chat window, and it runs up to
twelve rounds in a turn before it stops and says so.

Web search needs no key and no account, which matters on a phone where nothing
is configured.


WORK YOU DID BEFORE THIS EXISTED

The History button, or /history.

Claude Code, Codex, Gemini, Kimi and Grok all keep their own sessions on disk,
and this reads them where they lie. You get the engine, when it last moved, how
many turns, and what it was about, newest first.

A turn count reading 12 is exact. One reading 12+ is a floor, because the scan
reads the head of a transcript rather than all of it, and some of those files
run to a gigabyte. Nothing is written, moved or deleted: this is another
program's data and it is opened read-only.

Enter starts a NEW session in the folder that old work happened in. It does not
resume the other tool's conversation. Two programs writing one vendor's session
file corrupts it for both of them, and yours is the one that would be lost.

Some rows are thin. Grok keeps its conversation in a database this cannot open,
so a Grok row has a folder and a time and nothing else. It is listed anyway,
because knowing the session existed is worth more than a tidy table.


THE BACKGROUND

The Matrix button cycles it, the way the theme button cycles palettes: off,
matrix rain, embers, starfield, drift, aurora, and the wordmark sitting dim
behind everything. One more press comes back to off.

It only ever paints where nothing else has. It will not draw over a panel, a
dialog or a line of output, so it cannot be mistaken for corruption in your
transcript. Off is the default, because an effect nobody asked for is a
distraction.


THE WALL

Every agent in the session, one tile each, across every tab. The Wall button,
or /wall.

Panes show up to four agents inside one tab, which is right when you are
working. This answers the other question: with four tabs running, which of the
fourteen agents needs you. Blocked is the colour that catches your eye, because
it is the only state that needs a person. An agent that is working but has gone
silent says "quiet 4m" rather than showing a healthy green lamp.

Tiles are ordered by tab and by when the agent started, never by recent
activity. A grid that reshuffles under your pointer is a grid you cannot use for
the one thing it is for.

The trace along the bottom of a tile only moves while that agent is actually
producing output. A tile that animates while nothing is happening is a tile that
lies.


READING THE WORK BEFORE IT LANDS

The Review button, or /review.

Every isolated agent works on its own branch. This shows what each one changed,
coloured, with the file count and the line counts, so you can read four agents'
work without leaving the board.

The flow is: give an agent its own checkout, let it work, read the diff, then

    sophia tree commit <agent>
    sophia tree merge <agent>

Commit first because merging over uncommitted work is how an afternoon
disappears, and the merge refuses until it is done. Merging never touches the
checkout: it stays on its branch until you drop it.


FINDING THINGS AGAIN

    sophia search "the decision about retries"

Across every transcript and both kinds of notes. Something a person wrote down
deliberately ranks above something a tool printed, because it usually is the
answer you wanted.


WINDOWS, LINUX AND MACOS

One codebase, three builds, and the difference between them is honest.

Windows and Linux are both built and run. On Linux the daemon detaches into its
own session, so closing the terminal or pressing ctrl-C at the prompt leaves
your agents working, and the token file it writes is mode 600 rather than
readable by every account on the box.

macOS compiles and has not been run by anybody yet. Say so out loud rather than
finding out later. If you are the first, `sophia doctor` and `sophia sys` are
the two commands that would show it up.

Anything network-facing on unix goes through curl, which has to be on PATH. It
says so plainly if it is missing rather than failing quietly.

    sophia sys                    what it reads off this machine


WHERE IT KEEPS THINGS

    Windows          %APPDATA%\sophiaxt
    macOS and Linux  ~/.local/share/sophiaxt

SOPHIA_HOME moves it.


Copyright (c) 2026 SOPHIA XT LLC.
