Headless Go agent harness
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-03 22:26:52 +00:00
.forgejo/workflows ci(code-review): run reviews on melious/deepseek-v4.1-flash-1017 with high thinking 2026-11-03 21:00:17 +00:00
cmd/brainless fix: validate env refs, thinking modes, and share ParseModelRef 2026-09-23 18:06:24 +00:00
internal test: pin appendSystemInstruction against ADK version drift 2026-10-19 19:28:57 +00:00
.gitignore feat: bare-minimum ADK agent harness over ACP stdio 2026-09-21 18:35:36 +00:00
brainless.json.example feat: add per-model promptCompression config 2026-10-19 17:04:41 +00:00
cost_plan.md feat: close out cost docs, cache-write accounting, context steering, fork, per-session cwd 2026-10-05 17:50:48 +00:00
go.mod feat: add built-in per-repo memory tools 2026-10-04 09:37:07 +00:00
go.sum chore: update deps 2026-10-03 14:49:12 +01:00
LICENSE Initial commit 2026-09-21 18:08:56 +00:00
README.md feat: add per-model promptCompression config 2026-10-19 17:04:41 +00:00

brainless

Headless Go agent harness: an ADK agent (Go SDK: google.golang.org/adk/v2) that speaks Agent Client Protocol (ACP, via github.com/coder/acp-go-sdk) over stdio, so it can be registered as a Paseo agent/provider.

Bare minimum: one ADK llmagent over an OpenAI-compatible (Responses API) endpoint, bridged to ACP one session at a time.

Requirements

  • Go 1.26.6+ (the ADK module requires it)
  • An OpenAI-compatible endpoint implementing the Responses API (OpenAI, recent Ollama/LM Studio/vLLM), reachable with an API key

Configuration (config file)

Providers and models are declared in a JSON config file. By default brainless looks for brainless.json next to the executable; point -config-file at a different path to override.

{
  "version": "v1",
  "providers": {
    "melious": {
      "name": "Melious",
      "baseUrl": "https://api.melious.ai/v1",
      "apiKey": "${MELIOUS_API_KEY}",
      "models": {
        "deepseek-v4-flash-0731": {
          "name": "DeepSeek V4 Flash 0731",
          "input": ["text", "image"]
        },
        "deepseek-v4-reasoning": {
          "name": "DeepSeek V4 Reasoning",
          "reasoningEffort": ["off", "low", "medium", "high", "max"]
        }
      }
    }
  }
}

Key points:

  • version must be "v1".
  • default optionally names the model a fresh session starts on, as provider/model. Omitted means the first configured model in sorted order. It does not restrict the selector: the ACP model config option always lists every model.
  • Providers are keyed by id (used in the ACP model selector as provider/model); name is an optional display label.
  • Each provider needs baseUrl (an OpenAI-compatible endpoint) and apiKey.
  • api optionally names the OpenAI HTTP API a provider speaks: "responses" (the default, POST /v1/responses) or "chat_completions" (POST /v1/chat/completions). Responses calls are streamed over SSE — the endpoint some providers implement correctly only when streaming — and the harness reports the final aggregated answer. Set "chat_completions" for a provider whose Responses endpoint is broken or absent; tools, thinking effort, and usage accounting work identically on both APIs.
  • API keys and base URLs may reference environment variables with $VAR or ${VAR}; unset variables expand to empty. Literal values without $ are used as-is. apiKey may be empty (local models).
  • Models are keyed by the wire model id; name is an optional display label. input lists accepted content modalities (text, image, audio); unknown values are ignored and empty means text.
  • reasoningEffort lists the selectable thinking levels (off, none, minimal, low, medium, high, xhigh, max). Empty means the model does not reason, so no reasoning control is offered at all. xhigh and max are accepted but collapse to high: the ADK model bridge maps reasoning onto Responses effort and tops out at high, so a model declaring max would otherwise advertise a level that silently sends high.
  • promptCompression appends a compacted copy of the honey-for-devs AGENTS.md ruleset (https://github.com/Green-PT/honey-for-devs/blob/main/AGENTS.md — less code, less prose, denser agent-to-agent messages) to the model's system prompt. Off by default: the extra instructions cost tokens on every round, so they are opt-in per model.

MCP tools

brainless exposes Model Context Protocol (MCP) tools to the model on demand, so the schemas of tools the model has not asked for never bloat the prompt. Two sources are merged:

  • The ACP client. session/new, session/load, and session/resume carry mcpServers; brainless speaks the stdio (the transport every agent must support) and http transports, and advertises mcpCapabilities.http in initialize. Other transports (sse, acp) are ignored with a warning.
  • The config file. An optional mcpServers map, keyed by display name. A session server with the same name overrides the config-file one.
{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/work"],
      "env": { "HOME": "/home/user" }
    },
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

transport is stdio (requires command, optional args and env) or http (requires url, optional headers). MCP env/headers values are literal (no $VAR expansion).

Trust boundary. A stdio server declared by the ACP client is launched as a subprocess as soon as the session starts, with no confirmation step and no model mediation. Anything able to reach the ACP endpoint can therefore run commands in the brainless process by sending session/new with an mcpServers entry. This is inherent to the ACP stdio transport, which every agent must support, and is safe only when the ACP client is trusted — as it is when Paseo spawns brainless as its own child process over stdio. If you expose brainless to an untrusted client, restrict stdio servers to the config-file allowlist and do not accept client-declared ones.

The model starts each turn seeing the built-in file, fetch, and execute tools plus one more tool, tools. Calling tools returns a compact catalog of every available MCP tool and loads the ones named in its load argument; those tools' full schemas are then sent on the next round and the tools become callable. Loaded MCP tools are cleared when the turn ends, so a later turn starts from the catalog again unless it loads them anew. Tool calls and their results are streamed to the ACP client as tool-call updates.

Built-in file tools

brainless ships nine built-in tools that need no MCP server: read, create, edit, insert, list_directory, search_files, create_directory, delete, and delete_directory. They exist so an agent can work with files even when the ACP client connects no MCP server that offers file tools (Paseo's injected workspace MCP exposes workspace management only, so without them a brainless agent cannot read or modify a file at all). They are always visible — their schemas ride in every request, with no tools discover/load round trip — which for a small fixed set of tools is cheaper and more reliable than routing them through the lazy MCP catalog.

  • read(path, head?, tail?) returns the file's contents as text, streamed and stopping early. head and tail are 1-indexed line bounds: head is the first line to include and tail the last, so both together read a line range and a bounded read never loads the whole file.
  • create(path, content) creates a new file or completely overwrites an existing one. Inside a git repository it refuses an existing file tracked by git — create is for new and untracked files, and precise changes to tracked files must go through edit. A tracked file that is gone from the working tree is not refused: nothing is on disk to overwrite, and edit cannot bring it back because it needs the file to read. The guard shells out to git, so create is only registered when git is present at startup; without git the tool is not advertised at all. A new file gets mode 0600; an existing file keeps its mode.
  • edit(path, oldText, newText, count?) replaces an exact string. By default (or with count: 1) oldText must appear exactly once, so the edit is never ambiguous; a negative count replaces every occurrence and a larger count replaces up to that many. A missing match is always an error, and oldText is matched within a single line, because the edit streams line by line. This mirrors the safe replace semantics of the reference MCP filesystem server (https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).
  • insert(path, line, text) inserts text before a 1-indexed line: 1 inserts at the top, line count + 1 appends at the end, anything else out of range is an error. Use it to add a section where edit cannot match existing text.
  • list_directory(path) lists a directory's entries like ls, marking each as [FILE] or [DIR] (the reference filesystem server's format). .git is omitted, so repo discovery never drowns in git internals.
  • search_files(pattern, path?, maxResults?) finds a literal substring across files like grep -rn, returning matching lines as path:line: text up to maxResults (default 100). .git and binary files are skipped.
  • create_directory(path) creates a directory and any missing parents, like mkdir -p; it succeeds silently if the directory already exists.
  • delete(path) deletes a file, and delete_directory(path) deletes an empty directory (contents must be deleted first).

The three structural tools (create_directory, delete, delete_directory) are confined to the session working directory: an absolute path or a .. escape that lands outside it is refused. The read/write tools keep the harness's documented posture of trusting the ACP client with no allowed-directories jail.

Together list_directory and search_files cover repo inspection — seeing what exists and where a symbol appears — and the structural tools cover scaffolding and cleanup, so agents never need a terminal just to look around or restructure a repo; a terminal remains for running commands (git, builds, tests).

create, edit, and insert all write atomically: the new contents go to a temporary file in the same directory, which is renamed over the original, so a concurrent reader never sees a half-written file. read, edit, and insert stream the file instead of loading it whole. Every operation takes the caller's context and stops when it is cancelled. Relative paths resolve against the session working directory (cwd from session/new); absolute paths are used as-is. Like the rest of the harness, files are written without a permission prompt and there is no allowed-directories jail: the ACP client is trusted, the same posture as the stdio MCP servers the harness already launches.

Built-in fetch tool

brainless ships one more always-visible tool, fetch, so an agent has internet access even when the ACP client connects no MCP server that offers it. It is modelled after the reference MCP fetch server (https://github.com/modelcontextprotocol/servers/tree/main/src/fetch).

fetch(url, maxLength?, startIndex?, raw?, timeout?) retrieves an http/https URL and returns its contents as markdown:

  • HTML is simplified to markdown with JohannesKaufmann/html-to-markdown, which drops scripts, styles and other non-content elements and keeps headings, lists, links, code and tables. Relative links are made absolute against the fetched page, so a URL that appears in the output can be fetched directly. raw: true returns the body as fetched instead, and a non-HTML content type is always returned raw with a prefix saying so.
  • Content is windowed. maxLength defaults to 5000 characters; a result cut short ends with the startIndex to continue from, which is what makes it practical to read a long page in pieces. Indices count characters, not bytes, so a window never splits a multi-byte character. A body is read up to 8 MiB.
  • robots.txt is honored before the page is fetched: the origin's /robots.txt is read and evaluated for the brainless crawler token (RFC 9309 rules: longest matching pattern wins, Allow wins a tie). A disallowed path is refused, as is a site that answers 401, 403, or a 5xx server error for its robots.txt (a server error leaves the policy undefined, so the fetch fails rather than fetching unchecked); any other 4xx means there is no robots.txt to obey. The check runs again for every redirect the page takes, so a redirect cannot slip a disallowed path past it, and relative links in a redirected page resolve against the URL it actually came from.
  • Each request identifies itself as brainless/0.0.1 (+https://git.norobo.chat/sam/brainless), follows redirects, and honors the proxy environment.
  • The fetch is bounded in time. timeout is the number of seconds the whole fetch may take, robots.txt check included; it defaults to 30 and may not exceed 300. A slow site therefore ends the fetch with a deadline error instead of holding the turn open, and a canceled turn still stops it immediately.

Like the file tools it takes the caller's context, so a cancelled turn stops the fetch, and it runs without a permission prompt: the ACP client is trusted, the same posture as the stdio MCP servers the harness already launches. Where the reference server also runs readability extraction (readabilipy) to strip a page's navigation and boilerplate, brainless only converts: the whole page's text comes back, which is noise rather than harm for an agent reading it.

Exposure. fetch is the first outbound network channel the model can drive. It can reach any http/https URL, including addresses that are not part of the public internet (localhost, RFC 1918 private ranges, cloud metadata), and the page content — an untrusted prompt-injection vector — is handed back to the model verbatim. This is acceptable only under the trusted-ACP-client posture above; if brainless ever runs somewhere those internal addresses are reachable from the same network, restrict what fetch may target.

Built-in execute tool

brainless ships one more always-visible tool, execute, so an agent can run commands even when the ACP client connects no MCP server that offers a terminal tool. It is the model's sh -c: the command runs in the session working directory (an absolute or relative cwd overrides it) and its combined stdout/stderr plus exit code come back as the result.

  • execute(command, cwd?, timeout?) runs command under sh -c, so pipes, redirection and compound commands work. A non-zero exit code is returned, not raised: the model reads the output to see what went wrong.
  • Output is capped at 100 KiB with a truncation note, so one noisy command cannot exhaust memory or drown the model.
  • The command is bounded in time. timeout is the number of seconds the command may run; it defaults to 30 and may not exceed 300. A timeout kills the whole process tree (the command runs in its own process group) and reports exit code -1 with a note, so a runaway command cannot hold the turn open, and a canceled turn still stops it immediately.

Like the file tools and fetch it takes the caller's context, so a canceled turn stops the command, and it runs without a permission prompt: the ACP client is trusted, the same posture as the rest of the harness. It can reach anything the paseo user can, which under that posture is the point — it is how the agent builds and tests code.

Environment disclosure. The command inherits the harness's full process environment — including provider API keys and tokens — and can read it via env. There is no environment filtering; like every other capability this is acceptable only under the trusted-ACP-client posture above.

Built-in memory tools

brainless ships six always-visible memory tools so an agent can keep and recall facts across sessions, organised per repository: every operation is scoped to the git repository root found by walking up from the session working directory (the same anchor as the file tools), and directories outside any repo share one default memory. The store implements the ADK memory.Service interface and is backed by SQLite (memory.db under the state dir, WAL mode), so two agents working the same repo serialize writes through SQLite's file locks and cannot lose each other's entries; -ephemeral keeps the store in memory only.

The two read tools are ADK's native memory tools, which search the same store the curation tools write:

  • load_memory(query) — the model explicitly searches the repo's memory; results are ranked by how many query words they match, at most ten.
  • preload_memory — runs automatically at the start of every request and injects up to ten relevant entries into the system instructions, so facts the model wrote earlier resurface without being asked for.

The four curation and structured-read tools are modeled after the reference MCP memory server (https://github.com/modelcontextprotocol/servers/tree/main/src/memory), which stores a knowledge graph of entities (name, type, observations) and relations (active-voice connections between entities):

  • create_memory(entities?, relations?) — creates entities (with optional observations) and/or relations. Creating an entity or relation that already exists is a no-op, so the tool is safe to call repeatedly. A relation whose endpoint entity does not exist is an error.
  • add_observations(observations[]) — appends observations to existing entities; an observation already present is skipped.
  • delete_memory(entities?, observations?, relations?) — deletes entities (cascading to their observations and every relation touching them) and/or exact observations and relations. Deleting something that does not exist is reported, not an error.
  • read_graph(names?) — returns the repo's graph as JSON: with names, those entities with their observations plus every relation touching either of them; without, the whole graph.

Stored content is deliberately curated only: AddSessionToMemory refuses to ingest whole conversations, so memory never grows with raw session history — the only records are the small facts the model writes with the curation tools.

Env expansion

apiKey and baseUrl may reference environment variables with $VAR or ${VAR}; unset variables expand to empty, so local models without an API key boot fine. A malformed reference (an unterminated ${..., a bare $) is a boot error, so a typo fails immediately instead of being used as a literal credential; write $$ for a literal dollar sign in a key. API-key expansion is the only env usage besides STATE_DIR (below) and the -prompt/-model single-shot flags. The old MODEL/API_KEY/BASE_URL env provisioning is retired.

Context compaction

Once a session's prompt grows past a token budget, brainless summarizes the older turns and later prompts carry the summary instead of the raw turns, so the prompt stays small as the conversation grows. Compaction is on by default (ADK tail retention: one rolling summary plus the most recent events, the strategy that puts a ceiling on prompt size); the block below only tunes it, and "disabled": true turns it off.

{
  "compaction": {
    "defaultThreshold": 20000,
    "compactionThreshold": {
      "local/gemma4:e2b": 3000
    },
    "summarizerModel": "melious/deepseek-v4-flash-0731"
  },
  "timeouts": {
    "promptTimeout": "10m"
  }
}
  • defaultThreshold is the prompt token count at which older turns are summarized, for models with no compactionThreshold entry. Zero uses the built-in default (20000 tokens).
  • compactionThreshold overrides the default per model, keyed by provider/model — context windows differ, so the trigger should too. A small-context model (e.g. the local Gemma 4 E2B's ~4096 tokens) needs a threshold well below its window (3000 leaves room for the response and the always-visible tool schemas); a 128k-window cloud model can take 60000.
  • summarizerModel names the model that writes summaries, as provider/model. Empty, the default, uses the session's own model — which is fine for large models, but a small model too small to summarize its own history needs this pointed at a model with a bigger context window. The summarizer call is bounded at 60s; a failure costs a bigger prompt later, never the user's answer (it is logged and the turn continues).

The most recent 10 events always stay raw, so the model keeps immediate continuity. Invalid settings fail at boot: negative thresholds, non-positive per-model thresholds, and compactionThreshold/summarizerModel keys that name no configured model are all errors. The threshold applies to whichever model the session is on; switching models rebuilds the runner's compaction config for the new model.

Per-prompt timeout

A prompt that loops can burn your wall-clock long after it stopped being useful. timeouts.promptTimeout puts a hard ceiling on how long one prompt may run; it is off unless configured:

{
  "timeouts": {
    "promptTimeout": "10m"
  }
}
  • The value is a Go duration string ("10m", "90s", "1h30m"). An unparsable or non-positive value fails at boot.
  • When the prompt passes half its budget, the clock block the model sees each round gains a countdown (prompt timeout: 10m; 5m10s left); past 90% it becomes a directive (prompt timeout nearly reached — report what you have), the last point where writing up what exists is still possible.
  • At expiry the turn settles with the partial answer already streamed and stop reason cancelled, and the in-flight model request is aborted — the same machinery as session/cancel.

Cost awareness

brainless can tell the model what its tokens cost, so cost joins wall-clock time as a second guide for how much work to spend on a task. Nothing is predicted: cost is computed from the provider's own usage report, and prices come from you.

Prices

Prices live in the config file, per model, as a pricing block. Rates are per million tokens, named after the unit so a bare number cannot be misread:

{
  "providers": {
    "melious": {
      "models": {
        "deepseek-v4-flash-0731": {
          "pricing": {
            "currency": "EUR",
            "inputPerMillion": 0.27,
            "cachedInputPerMillion": 0.07,
            "cacheWritePerMillion": 0.50,
            "outputPerMillion": 1.10
          }
        }
      }
    }
  }
}
  • currency is a label, defaulting to EUR; nothing is converted, the harness reports in whatever unit you entered.
  • inputPerMillion is the fresh (uncached) input rate.
  • cachedInputPerMillion is the cache-read rate; omit it to assume no cache discount, so cache reads cost the same as fresh input.
  • cacheWritePerMillion is the rate for input tokens written to the prefix cache, for providers that bill cache creation separately (Anthropic-style). Omit it to charge writes at the fresh input rate, the OpenAI convention where a cache write is an ordinary input charge.
  • outputPerMillion is the output rate. Reasoning/thinking tokens are billed at the output rate on every provider brainless talks to, so they need no separate rate.
  • Absence means free. A model with no pricing block, or a block with no rates, costs nothing: it shows no money line and is steered by time alone. A negative rate is a boot error.

What the model sees

On a priced model, every round's <brainless-clock> block carries a cost line measuring the last round, the current task, and the whole session:

cost: last round €0.0030; this task €0.0120 / 41k in (62% cached) / 3.2k out (2.4k thinking); session €0.0630

last round is the lever the model can pull at its next decision; this task is the budget signal; session is the "this conversation has already cost me" signal. The cache share and the thinking count are shown because they are the two cost levers the model controls: keeping the cached prefix stable, and choosing a reasoning level. The turn log reports the same figures (cost, session_cost, plus cache_write_tokens and compaction_cost when non-zero) so the operator can audit them against an invoice.

On a free model with a declared context window, the cost line is replaced by a context line — the real cost of a local model is prefill time, so the model should keep its prompt small instead:

context: 2k / 4k tokens

Budgets

budgets.maxTaskCost puts a hard money ceiling on one task, the money counterpart of the wall-clock timeout. It is off unless configured, and it only applies to priced models (configuring it when no model is priced is a boot error rather than a silent no-op):

{
  "budgets": {
    "maxTaskCost": "0.50"
  }
}

The value is a string so "0.50" cannot be misread as tokens. The model is warned at half the budget and told to report what it has at 90%; at expiry the turn is cancelled through the same context path as a timeout. A hard cost stop can discard work that is nearly done and then be redone, which costs more — set the budget from measured history (below), not a guess.

Measured history

history.lastTasks adds a line that tells the model what comparable tasks have actually cost, computed from the persisted session events (grouped per task; only completed tasks count):

{
  "history": {
    "lastTasks": 3
  }
}

It is a measured average of the last N completed tasks, never a prediction, and it only appears when at least N completed tasks exist.

Context windows

contextWindow on a model declares its context window in tokens. It is the steering knob for free local models: the clock block then shows how much of the window the prompt uses, so the model can keep its prompt small where prefill time is the real cost (see Wiring the local Pi model). A negative value is a boot error; zero (unset) turns the line off.

Selecting a model

  • ACP clients pick the model at runtime through the model config option (session/new advertises a model selector; session/set_config_option switches it). That is the only config option: reasoning is not a raw selector but is controlled entirely through session modes.
  • ACP clients switch reasoning behavior through session/set_mode, which advertises three modes (fast, default, deep) as presets over the model's declared efforts: fast disables reasoning, default turns reasoning on with no effort override so the provider applies the model's natural default, and deep uses its maximum declared effort. The mode selector is only advertised for models that declare a reasoning effort other than off/none; a model that cannot reason offers no modes.
  • The same modes are also advertised as a mode config option (category mode). ACP conveys SessionModeState only in session/new/load/resume, so the config-option form is what lets the list change with the model: on a mode or model change, through either session/set_mode or a config option, the harness pushes a config_option_update and a current_mode_update, and the client re-derives the mode selector. Without it, switching to a non-reasoning model would leave a stale mode selector.
  • The harness advertises loadSession and the sessionCapabilities list/close/resume/fork flags, so clients (Paseo) can list, load, resume, close, and fork persisted sessions; session/cancel settles an in-flight prompt with stop reason cancelled.
  • -model provider/model selects the model for single-shot (-prompt) runs.

State is persisted to disk by default. Where it lives:

Control Env var Flag Effect
State dir override STATE_DIR -state-dir Directory for persistent state (sessions today; more later). Overrides the default.
Ephemeral — -ephemeral Keep all state in memory, persist nothing.

The default state dir is the per-platform user config dir joined with brainless: on linux $XDG_CONFIG_HOME/$HOME/.config/brainless, on macOS ~/Library/Application Support/brainless, on Windows %AppData%\brainless. Boot fails if the platform has no config-dir convention or the location cannot be determined (set STATE_DIR or pass -ephemeral to proceed).

Build & run

Prerequisites: Go 1.26.6+ (per go.mod minimum), and the module deps (go build fetches them via the module proxy; a GOPROXY may be needed in air-gapped environments).

# build the binary
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o brainless ./cmd/brainless

# run it directly (spawned by an ACP client over stdio, or idle alone)
./brainless

Static cross-build (no CGO) so the same binary runs in the arm64 Paseo container:

CGO_ENABLED=0 go build -o brainless ./cmd/brainless

On its own (no ACP client attached) the process idles on stdio until the peer disconnects — which is the correct behavior for an ACP agent spawned by a client like Paseo. To smoke-test the ADK half without a client, run:

./brainless -prompt "What is 2+2?"

-prompt TEXT runs one turn through the ADK runner and prints the final text. It uses the default model from the config file; pass -model provider/model to pick another.

Registering as a Paseo agent provider

This walks through wiring brainless into Paseo as an ACP agent provider. brainless is just an ordinary ACP-over-stdio process — Paseo launches it as a provider declared in its config.json, so there is no server port or socket to configure.

1. Build the binary

Build a static (no CGO) binary so it runs in the arm64 Paseo container:

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o brainless ./cmd/brainless

Copy it onto the Pi host into a directory the Paseo daemon can execute, e.g. /home/sam/bin/brainless. Make sure it is executable: chmod +x brainless.

2. Add the provider to config.json

Paseo reads providers from agents.providers in its config.json. A brainless entry looks like this:

// In paseo/config.json, under "agents": { "providers": { ... } }
"brainless": {
  "extends": "acp",
  "label": "brainless (ADK)",
  "description": "Headless ADK agent harness (OpenAI-compatible Responses API)",
  "command": [
    "/home/sam/bin/brainless",
    "--config-file", "/home/sam/brainless.json",
    "--state-dir", "/home/sam/data/brainless"
  ],
  "enabled": true
}

Notes:

  • "extends": "acp" tells Paseo this provider is an ACP agent (same as the acp native protocol), so it drives the stdio handshake for you.
  • The providers/models come from brainless.json (see Configuration); the API key is read from the environment via $VAR expansion in the config file, so it never appears in config.json. Put the secret in the daemon environment (e.g. paseo.env).
  • Model switching happens at runtime over ACP: session/new advertises a model config option listing every configured model, and session/set_config_option switches it. Reasoning is controlled through session/set_mode (fast/default/deep), advertised only for models that reason. There is no need to declare models in the Paseo provider entry — it is returned by the agent on each new session.
  • Pass -model provider/model to select the model for single-shot (-prompt) runs only; server mode is driven entirely by ACP config options.

3. (Optional) Choose where state is stored

State (sessions today) persists to disk by default; brainless uses a directory under the user's config dir unless you pass --state-dir. To keep conversations across restarts (session/load, session/resume) at a known location, point it at a directory the daemon can write and create it if absent (it is also created on first run):

mkdir -p /home/sam/data/brainless

brainless writes one shared SQLite database, sessions.db, in that directory. Every brainless process pointed at the same directory shares it. Pass --ephemeral instead to keep all state in memory and persist nothing.

4. Restart and verify

Restart the Paseo daemon so it picks up the new provider, then:

  1. In the Paseo agent picker, brainless should appear with the model(s) listed in models.
  2. Start a conversation and send a message — it should be answered by the configured model.
  3. If you are persisting state (the default), end the session, start a new one, and use the session list/load UI (or session/load) to confirm the earlier conversation is still available.

To smoke-test the ADK half of the harness without Paseo attached (a useful way to confirm the binary, config, and endpoint are all wired correctly):

./brainless -prompt "What is 2+2?"

Other ACP-compatible orchestrators

Any orchestrator that runs an ACP stdio agent can launch brainless the same way — run the binary with stdio attached and drive initialize → new-session → prompt. The -prompt flag is a convenient one-shot smoke path for validating a given orchestrator's wiring.

Wiring the local Pi model (Gemma 4 E2B)

The pi-deploy stack runs a local inference endpoint (llm service) on the Pi: an official ghcr.io/ggml-org/llama.cpp:server container serving Gemma 4 E2B Q4 over an OpenAI-compatible API (both /v1/chat/completions and /v1/responses) at http://llm:8080/v1. Because this llama.cpp build serves the Responses API, brainless can talk to it directly — no chat to-responses adapter needed.

Why it fits small/subagent prompts

The endpoint is small-context (~4096 tokens). Paseo's normal agent context (system prompt + MCP tool schemas + session history) is ~31k tokens and cannot fit, so the model is NOT registered as a normal Paseo agent model. For brainless — which runs as a separate ACP harness you drive with small, standalone prompts (e.g. subagents, quick Q&A, structured micro-tasks) — the context stays small and the endpoint is a good fit.

Provider config

Add the local endpoint as a provider in brainless.json (see Configuration). An empty apiKey is fine for a local server:

{
  "version": "v1",
  "providers": {
    "local": {
      "name": "Local Gemma (llama.cpp)",
      "baseUrl": "http://llm:8080/v1",
      "apiKey": "",
      "models": {
        "gemma4:e2b": {
          "name": "Gemma 4 E2B (local, Pi)",
          "input": ["text"],
          "contextWindow": 4096
        }
      }
    }
  }
}

Then register brainless in the Paseo daemon's config.json (under agents.providers) pointing at that config file:

// In paseo/config.json, under "agents": { "providers": { ... } }
"brainless-local": {
  "extends": "acp",
  "label": "brainless local (Gemma 4 E2B)",
  "description": "Local Gemma 4 E2B via llama.cpp Responses API",
  "command": [
    "/home/sam/bin/brainless",
    "--config-file", "/home/sam/brainless.json",
    "--state-dir", "/home/sam/data/brainless-local"
  ],
  "enabled": true
}

Notes:

  • The baseUrl is http://llm:8080/v1 because the llm container and the Paseo daemon (which spawns brainless) are already on the same localinference compose network — so the hostname llm resolves inside Paseo. No API key is needed for the local server.
  • Reachability caveat: the llm service is published only on the internal localinference network, not the host LAN. brainless must therefore run in a context that is on that network — i.e. spawned by the Paseo daemon (as here). If you run brainless on the Pi host or another container, expose the endpoint (e.g. publish 100.64.0.1:8080:8080 in pi-deploy's docker-compose.yml) and point the baseUrl at the host-reachable address.
  • Keep the model key equal to the id the server reports (/v1/models returns gemma4:e2b); the local OpenAI proxy accepts any model id but we pin it for clarity. It is selected per session via the ACP model config option.
  • contextWindow: 4096 declares the endpoint's small window, so the free model's clock block shows how much of it the prompt uses (context: 2k / 4k tokens) instead of a money line — the model's real cost is prefill time, and the line steers it to keep the prompt small. The per-model compactionThreshold (see Context compaction) should stay below the window too.
  • A separate --state-dir keeps local sessions distinct from cloud ones.

Verify

Smoke-test the ADK half without Paseo attached (run from a container/host that can reach the endpoint):

./brainless --config-file /home/sam/brainless.json \
  --ephemeral -model local/gemma4:e2b -prompt "Write one sentence about paseo."

Or hit the endpoint directly to confirm it serves the Responses API:

curl -sS -X POST http://llm:8080/v1/responses \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer local' \
  -d '{"model":"gemma4:e2b","input":"hi","max_output_tokens":16}'

Building for a different endpoint

The ADK openaimodel speaks the OpenAI Responses API, so every provider's baseUrl must point at a Responses-API-compatible server (OpenAI, recent Ollama/LM Studio/vLLM). Point baseUrl at your provider in brainless.json and give the model its wire id as the map key.

What's a "bare minimum" and what's consciously missing

  • No permission flow: ACP session/request_permission is not bridged to ADK's Human-in-the-Loop confirmation, so loaded MCP tools execute without asking. Tool calls and their results are surfaced to the client as ACP tool-call updates (see MCP tools).
  • Sessions map one at a time and live in a shared SQLite store (sessions.db under the state dir) so they persist across process restarts by default; -ephemeral keeps them in memory instead. session/list, session/load, session/resume, session/fork, and session/close are implemented; session/delete is not and returns method-not-found. session/load and session/resume replay the stored conversation as message updates, so a resumed session shows its history, and session/fork branches a session into a fresh one with a verbatim copy of the conversation. Each session records the working directory it was created with, so session/list reports the right cwd per row (Paseo feeds it back into session/load and its import UI) and the file tools resolve relative paths correctly even after a restart.
  • Model switching (session/set_config_option) is applied to the next prompt for the whole process (one active session at a time), not persisted per session. The input modality metadata in brainless.json is not yet wired to ACP prompt capabilities, so image/audio inputs are not accepted even when a model declares them.
  • No streaming of partial chunks.

Next steps

The harness is deliberately minimal. Likely next steps, roughly in order of value:

  1. Multiple sessions per instance. Today the harness tracks one active session id; Prompt routes by the id carried in the request, falling back to the single active id. Supporting several sessions per process is a natural follow-up: replace the single cursor with a registry keyed by id — the SQLite store already supports many.
  2. Per-session model selection. session/set_config_option sets the model for the whole process today (the harness holds one active session). When multi-session support lands, persist the selection per session id.
  3. Input modalities. The input metadata in brainless.json is validated but not yet enforced: a configured image-capable model does not advertise promptCapabilities.image and the harness drops non-text prompt blocks.

Things that remain consciously out of scope for the bare-minimum harness: no human-in-the-loop permission bridging (tool calls run without asking), no streaming of partial chunks, and no memory/recall service.