---
title: "What Shoal is"
description: "Shoal is one agent and one binary that runs models on hardware you control and spends its effort on the context window."
source: https://shoal.grimvane.ai/docs/start/what-is-shoal/
---

# What Shoal is

## 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.