Sonny reuses a few ordinary words for specific things. This page defines them the way the CLI, the configuration files, and the error messages use them, and links to the page that goes deeper.

Recipe

A recipe is the YAML file that tells Sonny who to be: which LLM profile or profiles to call, which tools it may use, and what system prompt to render. Recipes are versioned (version: 2 is the current schema), they compose through parent, includes, and sub-packs, and a recipe never contains a model name, endpoint, or credential — it names a category instead. See Recipes and authoring a recipe .

Base recipe

The embedded doctrine every recipe composes with: the shared operating instructions that apply regardless of which recipe you select. You do not select it yourself; it is always part of the rendered system prompt.

Profile (LLM profile)

An entry in a recipe’s llm_profiles list. A profile names a role — code, reasoning, fast, orchestrator — through a provider URI rather than pinning a concrete model. Which model actually serves a role comes from the catalog and the routing policy, so the same recipe runs against a different provider on a different machine with no edits. See Providers and models .

Provider URI

The <scheme>://<model>?key=value dialect a recipe uses to name an LLM endpoint. It is a small addressing grammar, not a real URL: the scheme selects the transport, the path names the model, and the query parameters map onto request settings.

Category

A role name a recipe asks for (code, reasoning, fast, …) instead of a concrete model. Sonny resolves a category at pack-load time against your per-user catalog, ranking the candidates by a fitness score under a routing policy and picking the winner.

Catalog

Your models.yaml file: the list of model sources (provider scheme, optional endpoint, credential environment-variable name) and how each source’s models map onto categories with fitness and optional pricing. It is the only place model names live. See models.yaml .

Credential

The environment variable name a source reads its API key from — never the key itself. Because a catalog stores a name and not a secret, a catalog file and a recipe file are both safe to commit. See Credentials .

Session

One conversation, stored as a row plus its turns in <data-dir>/sessions.db (SQLite, WAL mode, directories 0700). Sessions carry a stable, never-reused session number, the recipe id and version, the provider and model, and a working directory. --continue, --session, and --new choose which one a run picks up. See Sessions and the configuration reference .

Trace

The append-only record of what happened during a run — turns, tool calls, results — written under the state directory and read back with sonny trace. Traces are what “the model said it ran the tests” is checked against.

Recipe keys (pack-keys/)

The directory holding per-pack signing and trust material. It resolves from $SONNY_PACK_KEYS_DIR, falling back to ~/.config/sonny/pack-keys.

Authority mode

The control posture for tool approvals: off (authority is never consulted), observe (every decision is computed and recorded as a counterfactual, but the call is always admitted), and enforce (a missing, stale, or unavailable authority view fails the operation closed). It comes from the single SONNY_AUTHORITY_MODE environment variable, resolved once at process startup. sonny control status reports the effective mode.

Grant

An approval recorded for one exact call, not for a tool in general. A grant that matches a different call does not apply. Older, broader “always allow” style grants are automatically quarantined rather than honoured.

Toolcap

The output-size cap every tool result passes through before it reaches the model, so one verbose command cannot crowd out the rest of the context.

MCP server

A Model Context Protocol server Sonny connects to for extra tools. Servers are declared in configuration and are subject to approval: connecting one and using its tools are separate decisions. See MCP servers and configuration .

Mesh

Sonny’s distributed layer: a set of long-running sonny mesh serve nodes that host sessions, so a session survives your terminal closing and can be attached to from another machine or transferred between nodes. The mesh is the reason a single chat can scale out to sessions running on machines you control. See Running the mesh .

Node

One running sonny mesh serve process. A node exposes a gRPC client plane (default :50052) that CLI tools, the TUI, and sonny-api dial, and a separate Synapse peer plane (default :50053) that nodes use to talk to each other over QUIC and protobuf, with WebSocket kept as an explicit compatibility transport. Production nodes fail closed when their managed dependencies are missing or unhealthy.

Managed manifest

The --managed-manifest file a production node requires before it opens either listener. It is validated against the node’s control database, verification keyring, signed tenant policies, authority and audit plane, recipe loading, and machine isolation configuration.

Split session

A session forked into a peer child running in its own worktree, which you can detach and later reconcile back. Worktrees are listed, inspected, and retired from the CLI.

Portable session

A session exported so it can be imported into another Sonny installation without carrying credentials with it.

Plan mode

A posture in which the model researches a task and writes a structured plan without touching your project. You review and approve the plan, then Sonny executes it task by task, and each task’s completion rests on evidence the host checks rather than on the model’s own claim.

Memory

Project-scoped, durable, file-backed notes the model can save and recall across sessions — one YAML file per record under .sonny/memory/, indexed and searched, injected at session start. Distinct from SONNY_MEMORY, which is policy-evidence retrieval for a recipe’s memory: configuration.

Compaction

What Sonny does when a session outgrows its context window: it replaces older turns with a structured state block (goal, task queue, decisions, findings, files inspected, verification results) so the session can continue without re-reading everything. Your standing goal survives compaction verbatim.

Sub-agent recipe / worker

A narrower recipe a recipe can route work to. agent_search names the sub-agent recipes a recipe can spawn; spawn_agent starts one. A worker runs as its own process, in its own Git worktree inside a repository, and its output is read back with get_agent_output.

Exec-only tool

A tool that is available to a session but not declared in its current tool list. A session discovers one with tool_search and runs it with tool_exec using the name and argument schema the search returned.

XDG directories

Where Sonny keeps its state, following the XDG Base Directory specification: configuration in ~/.config/sonny, data in ~/.local/share/sonny, cache in ~/.cache/sonny, and state in ~/.local/state/sonny on Linux (with platform equivalents on macOS and Windows). Every one of those is overridable by its XDG_* variable. See Configuration .

Skill

A per-tab tool toggle: a named bundle of tools you can switch on or off for the current tab without editing a recipe.

Gap

Sonny’s unit of tracked work in its own repository. A gap is a named, IDed deficiency — a missing test, a missing document, an unclosed requirement — that a change can reference in its commit message, for example fix: close Q-007 - add .golangci.yml. See Contributing .

Canary

A tracked requirement token that implementation is graded against, so “requirement covered” is a mechanically checkable claim rather than prose.