Shoal is one agent on your own hardware
Shoal is an agent harness, one product in one binary. It reads and edits the files in your repository, runs tools, and asks before it writes. Coding is its first job, and the loop underneath it is general.
It also owns the layer underneath. Shoal starts the inference server, pins its flags, health checks it, reads its context size, and stops it when the session ends. Install the binary, point it at a model, and it answers.
You bring the model and it plugs into Shoal. A GGUF on your disk, a vLLM or other OpenAI-compatible server on this machine or another, and a frontier model over the network are all reachable from the same session. Which one answers is written down in a record you saved, and a request leaves the machine only when that record says it should.
The real job is the context window
Everything above the model is context management. Shoal keeps prompts lean, tracks a token budget and corrects it from what the server actually reports, and appends to history rather than rewriting it so the server’s prefix cache stays warm across turns. When the budget tightens, compaction fires once and deeply at 85 percent full and cuts back to 60 percent, instead of trimming a little every turn and re-prefilling the whole window each time.
The same thinking decides how the agent learns what a repository holds.
Reading files one at a time to find out what is in them spends the window on
the search. Shoal keeps a chart of the codebase at .shoal/chart.yaml, a graph
of files with one-line purposes and import edges, and serves it through a tool
call that answers with a single packed block sized to a token budget. Detail
fades with distance from the files a task named, so pressure costs detail
before it costs coverage. The chart is never injected into the prompt. Work
that does not belong in the main window is torn off into a sub-agent with a
fresh context, and a housekeeping pass runs between turns and stages its edits
so they apply at one cache boundary.
Five parts carry the architecture
| Part | Meaning |
|---|---|
| Shoal | The product. One agent in one binary, on every surface |
| Keel | The engine inside: agent loop, context machinery, tools |
| Dock | An inference engine, on this machine or at an address you name, where models tie up |
| Berth | One spot at a dock, holding exactly one moored model |
| Mooring | A model tied up and ready, and the named record of it |
The rest of these pages use those words as written. A mooring names a model, a dock, and a purpose, and the berth is the room it takes.
One engine stands behind three clients
Keel talks to every client through one seam: a typed event stream out and a
channel of operations in. shoal proto speaks that seam over stdio as JSON
lines, and the clients are built on it.
| Client | What it is |
|---|---|
| Terminal | An inline session with a live status region and finished output in native scrollback |
| VS Code | An editor panel that spawns the installed binary, with Ask About Selection in the context menu |
| Desktop | The same web client in its own app window, over a loopback bridge |
They share the engine, the protocol, and the SQLite session store, so a session started in one is resumable and a capability lands in all three at once.