Skip to content
github-actions[bot] edited this page Jun 30, 2026 · 78 revisions

steiner

A minimal, local-first Go coding agent with bounded context and sandboxed execution.

  • Delegation-first: sub-agents isolate work so it never fills the parent conversation
  • Sandboxed execution: bash and subprocess tools run inside a bubblewrap sandbox; sandbox violations prompt for user decision
  • Provider-agnostic: same config shape for local and cloud providers

Why steiner

Most coding agents are designed for cloud models with large context windows. Steiner is designed for the opposite constraint: local LLMs where context is expensive, reasoning quality degrades as the window fills, and you want to know exactly what is happening before anything changes on disk.

The core bet is that delegation is a better context strategy than summarisation. When a sub-agent handles exploration or code changes, the parent conversation never sees the intermediate turns — only the result. Combined with per-source byte budgets and late-stage compaction, this keeps the working context lean across long sessions.

By default, bash and subprocess tools run inside a sandbox that prevents writes outside the workspace and filters credential-bearing environment variables. Users can temporarily allow writable access to specific paths or disable sandboxing entirely with the --unsafe flag.

The provider/model split means you can point steiner at Ollama, LM Studio, OpenRouter, or a native Anthropic or OpenAI endpoint with the same config shape and the same tool behavior.

Quickstart

  1. Prerequisites: Go 1.25+. For local models, Ollama or LM Studio.
  2. Start a local model (Ollama example):
    ollama run qwen2.5-coder:14b
  3. Run from source:
    go run ./cmd/steiner --exec "summarize this repository in one sentence"
    Or start interactive mode:
    go run ./cmd/steiner
  4. Inspect resolved configuration before doing real work:
    go run ./cmd/steiner config
  5. Optional — build a local binary:
    make build-binaries
    ./bin/steiner

Usage

Interactive mode — launches the TUI, accepts natural-language requests, streams tool calls and responses:

go run ./cmd/steiner
# or
./bin/steiner

Single-shot — runs one request and exits:

go run ./cmd/steiner --exec "explain the auth package"

Commands reference:

Command What it does
version Print the build version; --short for script-friendly output
config Print the resolved configuration (providers, models, limits)
update / upgrade Self-update to the latest release; optionally specify a version
tools List configured tools and their approval status
skills List discovered skills
--help Print all flags and usage

Output format

steiner --version and steiner version print a multi-line panel with build metadata:

  version    v0.1.0
  commit     abc1234
  built      2026-06-17T12:00:00Z
  go         go1.25.0
  channel    stable

Labels are bold with the configured accent color; values use the default foreground. Use steiner version --short to print only the raw version string (no styling, no labels) for scripts and CI.

steiner update (alias upgrade) runs in two phases: check then apply.

  checking version
  Current:    v0.1.0
  Latest:     v0.2.0
  updating...
  ✔ updated

If already up to date, the apply phase is skipped:

  checking version
  Current:    v0.2.0
  Latest:     v0.2.0
  ✔ Up to date

When switching between dev and stable channels, a warning is shown:

  ⚠ notice   switching from dev to stable — this replaces your current build
  checking version
  …

A spinner animates during check and download. On a non-TTY or when NO_COLOR is set, the spinner degrades to a static line.

Configuration

Configuration is loaded in this precedence order (later overrides earlier):

  1. Compiled defaults
  2. ~/.config/steiner/config.yaml
  3. .steiner/config.yaml (project-local)
  4. Environment variables with the STEINER_ prefix
  5. CLI flags

Example — local LLM (Ollama or LM Studio):

default_model: local
providers:
  local:
    type: openai_compat
    base_url: http://localhost:11434/v1
models:
  local:
    provider: local
    id: qwen2.5-coder:14b

See Configuration for all provider types, model fields, limit overrides, sandbox settings, sub-agent config, and environment variables.

Built-in tools

Tool Description
read Read files with offset/limit pagination; detects and base64-encodes images
mutate Apply structured file mutations atomically (create, write, replace, delete, move, insert)
glob Find files by pattern
grep Search file contents with surrounding context
ls List directory contents
bash Run shell commands (sandboxed by default)
scratchpad Record working state; persists across compaction
fetch_url Fetch a URL; web pages converted to markdown, images returned for vision models
display_file Show a file in the TUI overlay without adding to conversation
advisor Ask a stronger-model steering advisor for guidance (requires advisor.enabled)
workflow_handoff Transition to a different workflow with approved artifacts

Sandboxing

By default, bash and subprocess tools run inside a Linux sandbox (using bubblewrap) that restricts writes to files outside the workspace and filters credential-bearing environment variables. The sandbox bind-mounts the entire host filesystem read-only (--ro-bind / /), with writable overlays for the workspace and a sandbox state directory (.steiner/home/). All installed toolchains, system libraries, and user config files are accessible read-only without per-path configuration.

Steiner also creates an ephemeral in-memory OpenSSH client-config overlay for sandboxed commands so ssh can read the system client config and static drop-ins without copying SSH config into the workspace. If OpenSSH still rejects the config inside the sandbox, Steiner can prompt to rerun the command outside the sandbox.

When a sandboxed tool attempts to write to a file outside the workspace, the user is prompted to either grant temporary access, use the --unsafe flag to disable sandboxing, or cancel the operation. This protects against accidental workspace-external writes and environment variable leakage. Reading host files (including on-disk credentials) is not restricted — sandboxing is not a confidentiality boundary, and private SSH keys are never copied into the workspace.

Platform support: Linux only (automatic detection; sandboxing is disabled on macOS and Windows).

For configuration, environment variable filtering, mount layout, and troubleshooting, see docs/tool-sandboxing.md.

Context management

Local LLMs have limited context windows — often measured in tens of thousands of tokens, not millions. Every turn accumulates tokens from model output and tool results, and long contexts cost more while degrading reasoning quality. Steiner keeps the context window lean through three mechanisms, ordered by effectiveness.

Delegation is the primary strategy. Sub-agents isolate work from the parent conversation. The full turn-by-turn transcript of exploration, code changes, or research never enters the parent context at all — only the result comes back. This is the most effective mechanism because it prevents context growth rather than managing it after the fact.

Per-source byte budgets cap each context source (preamble, agent summaries, skills, tool results, conversation history) so no single category can crowd out the others. Compaction kicks in when estimated prompt tokens reach 70% of the context window: older turns are summarised by the model into a compact durable prefix, then dropped from the live history.

See docs/context-management.md for the full reference.

Sub-agent delegation

Delegation is steiner's primary context management strategy. steiner exposes six sub-agent tools that delegate bounded tasks to isolated child agents. Sub-agent delegation is enabled by default — the model sees these tools alongside the built-ins:

Tool What it does Can mutate?
explore Navigate the codebase to find files, symbols, call sites, and patterns No
research Gather and synthesise information from the codebase or web No
code Implement a scoped change — read relevant files, write changes, run tests Yes
plan Analyse a sub-problem, evaluate options, and produce a structured recommendation No
verify Run tests, linters, builds, or other checks and report pass or fail No
follow_up Resume an existing sub-agent session by agent ID with a new user message No

See docs/sub-agent-delegation.md for full documentation, including per-agent tool allowlists and safety restrictions.

Optional features

Advisor

A stronger-model steering pass that reviews the live conversation and returns concise guidance. No tools, no mutation, no child loop.

advisor:
  enabled: true
  model: advisor-model

See Advisor for configuration options and behavior reference.

Cache hit rate tracking

Token-weighted prompt-cache hit rate, always-on with no configuration. Surfaces in the sidebar and via the /cache-stats overlay command.

See Cache Stats for the metric definition, storage format, and privacy notes.

Oneshot mode

Autonomous three-phase orchestration (plan, implement, review). Each phase runs as a sub-agent in an isolated git worktree. Runs are resumable.

oneshot:
  auto_pr: false
  models:
    plan: ""
    implement: ""
    review: ""

See Oneshot Mode for invocation, configuration, and resume behaviour.

Desktop notifications

Native notifications when the agent needs approval or handoff. Linux fully supported; macOS and Windows no-op with a startup warning.

desktop_notifications:
  enabled: true

See Desktop Notifications for platform support and configuration.

Other features

These features are documented in Optional Features:

  • cave_human — terse output with anti-AI-writing style instruction
  • Accent colour — customizable TUI accent with 13 presets and /accent picker
  • Web search — model-facing search tool with Google, Kagi, Brave, and SearXNG backends
  • Image paste — Ctrl+V image input with auto-resize and token accounting
  • Conversation forking — fork live or saved sessions into independent copies
  • Code simplification — parallel sub-agent analysis for reuse, simplification, efficiency, and altitude
  • Codex OAuth — use OpenAI Codex subscription models without a separate API key

Self-update

Steiner can self-update via the update (or upgrade) command. It fetches the latest release from GitHub, verifies the binary checksum, and atomically replaces the running executable.

A GitHub token is not strictly required, but GitHub API rate limits may apply without one. Set STEINER_GITHUB_TOKEN in your environment to authenticate:

export STEINER_GITHUB_TOKEN=ghp_...

Specific version

Pass a version tag to install a specific stable release instead of the latest:

steiner update v1.2.0
steiner update 1.2.0     # "v" prefix is optional

Dev channel

The update command selects the release channel via the --dev flag, which is a root-level persistent flag and also works on the update subcommand:

# Stable channel (default): installs the latest stable release.
steiner update

# Dev channel: pulls the build published on every merge to main.
steiner update --dev
steiner --dev update

--dev selects the dev release channel; its absence selects the stable channel. Both a dev build version string (dev or dev-<sha>) and a stable semver (vX.Y.Z) honor the flag. The dev binary is always replaced with the latest dev release; the stable binary is only replaced when a newer semver is available.

When switching channels — dev to stable or stable to dev — a warning is printed with the channel names highlighted in the accent colour. --dev and a specific version cannot be used together.

Development

# Build
go build ./...
make build-binaries

# Test
go test ./...
go test -race ./...

# Lint and vet
go vet ./...
golangci-lint run ./...

# All checks (lint + vet + format check)
make check

# Format
make fmt

For agent contributor context, architecture constraints, and conventions, see AGENTS.md.

Clone this wiki locally