Spettro is a terminal-first multi-agent coding assistant written in Go.

Quick install

curl -sSfL https://raw.githubusercontent.com/aploide/spettro/main/install.sh | sh

Installs to ~/.local/bin by default (no sudo needed); set INSTALL_DIR to override. Self-updates (/update in the TUI, or the built-in update check) write in place to that same directory, so they never need sudo either.

It uses a configurable agent manifest (spettro.agents.toml + agents/*.md prompts), parallel sub-agent spawning via native tool calls and an agent tool, plus specialized orchestrator/worker roles (plan, coding, ask, explore, code, git, test, review, docs).

Highlights

• Configurable multi-agent system via spettro.agents.toml and agents/*.md
• Parallel native tool-call spawning of sub-agents
• Permission policies: ask-first, restricted, yolo
• Live tool traces in planning/coding runs
• Fantasy-backed provider routing for OpenAI, Anthropic, and OpenAI-compatible text calls
• Multi-provider model support via models.dev catalog + OpenAI-compatible endpoints
• Normalized thinking/reasoning levels across providers (/thinking off|low|medium|high|x-high|max)
• Ultra mode — fan hard tasks out across a swarm of parallel sub-agents (/ultra, any model)
• Interactive PTY sessions — the agent drives REPLs, debuggers, and ssh through a real terminal
• Conversation persistence and resume per project
• Project trust prompt before first use in a folder

Build and run

Requirements:

• Go 1.26.1+

git clone https://github.com/aploide/spettro
cd spettro
make build
./bin/spettro

Alternative:

go run ./cmd/spettro

First-time setup

At first launch:

1. Confirm folder trust.
2. Run /connect to add an API key (or local endpoint).
3. Run /models to select provider/model.
4. Start with plan (default agent) and switch with Shift+Tab.

Common commands

Spettro commands are entered with a leading /.

• /help show help text
• /exit, /quit quit Spettro
• /mode, /next cycle active agent/mode
• /connect connect provider or local endpoint
• /models [provider:model] [api_key] open selector or set directly
• /permission <ask-first|restricted|yolo> set execution policy
• /permissions [ask-first|restricted|yolo] show/set permission policy
• /permissions debug <on|off> toggle permission diagnostics
• /budget <n|0> set request token budget (0 = unlimited)
• /thinking <off|low|medium|high|x-high|max> set the reasoning level (Anthropic thinking budget, OpenAI-style reasoning_effort; hidden for non-reasoning models, auto-falls back if a level is rejected)
• /ultra [on|off] toggle Ultra swarm mode (requires restricted or yolo permission)
• /plan [prompt] switch to plan mode or run plan prompt
• /approve execute pending approved plan through coding agent
• /tasks [list|add|done|set|show] manage session tasks
• /mcp <list|read|auth> manage MCP resources and auth tokens
• /skill <list|install|info|uninstall|enable|disable|where> manage Agent Skills (Claude Code / OpenAI / Anthropic format)
• /hooks show effective runtime hooks
• /compact [focus] summarize conversation history
• /compact auto <status|on|off> configure auto-compact
• /compact policy show compact thresholds/counters
• /clear auto-save and clear current conversation
• /resume load a previous saved conversation
• /init analyze the repo and create/update SPETTRO.md
• /remote [:port] expose a loopback HTTP/SSE control plane (see docs/remote.md)
• /remote local [:port] expose the control plane to LAN devices on 0.0.0.0 (see docs/remote.md)
• /telegram setup <token> configure a Telegram bot relay so you can drive Spettro from a chat (see docs/telegram.md). Alias: /tg.
• /<custom> [args] run your own saved prompts from ~/.spettro/commands/ or .spettro/commands/ (see docs/custom-commands.md)

For full commands and keybindings, see docs/commands.md.

Editor integration (ACP)

spettro --acp runs Spettro as an Agent Client Protocol agent over stdio, so ACP-capable editors like Zed can drive it from their native agent panel — with streamed reasoning, tool call reporting, mode switching, and permission prompts. See docs/acp.md.

Project docs

• Session Lifecycle — auto-save, resume, compact, clear
• Goal Mode — autonomous /goal runs
• Runtime Hooks — custom bash middleware
• Clipboard and Attachments — image paste, file attach
• First-Launch Onboarding
• Spettro Subscription — login, plans, credits
• Agent Manifest
• Agent Prompts
• Agent Skills
• Getting started and workflow
• Commands and keybindings
• Custom slash commands — save reusable prompts as your own /commands
• Configuration and storage
• OS sandboxing
• Architecture overview
• Remote control plane
• Agent Client Protocol (editor integration)
• Telegram relay
• Extended thinking levels
• Ultra mode (agent swarm)
• Troubleshooting
• Documentation Index

Development

make test
make build
make build-all