Terminal-first. Multi-agent. Open source.
The terminal coding assistant with real agent handoffs.
Spettro is a Go + Bubble Tea TUI with manifest-driven agents, approval-aware execution, encrypted keys, and provider routing across Anthropic, OpenAI-compatible, and local model endpoints. Plan, approve, code, and resume — without leaving the terminal.
Real repo. Real workflow. Real builders.
Numbers come straight from the public repository, the release feed, and the docs — nothing else.
Built around repository work, explicit permissions, and real agent handoffs.
Spettro is not trying to hide the workflow. The product is the workflow: trust the folder, connect a model, plan the change, approve execution when needed, and keep the session alive long enough to finish serious work.
Explicit project trust handshake before any tool call leaves the terminal.
Plan agent proposes, coding agent executes — only after /approve in stricter modes.
Sessions, tasks, /clear, /resume, /compact. Long threads stay workable.
Anthropic, OpenAI-compatible, or local. Model catalog cached from models.dev.
Every part of the workflow is a first-class surface.
Manifest-driven agents, approval flow, provider routing, encrypted keys, hooks, MCP, and a project indexer — all in one terminal-native runtime.
Multi-agent runtime
Manifest-driven roles for plan, coding, review, docs, git, test, and explorer agents — handoffs are explicit, not hidden behind a single prompt.
Approval-aware execution
Ask-first, restricted, and yolo permission modes. Plans pause before execution and resume only after /approve.
Provider flexibility
Native Anthropic, OpenAI-compatible APIs, and local endpoints like LM Studio or Ollama. Models.dev catalog cached locally.
Encrypted key storage
API keys are encrypted with AES-GCM. Trusted paths, sessions, and cached models live under ~/.spettro.
Sessions, tasks, compact
Persistent session storage for messages, tasks, and agent events. /clear, /resume, and /compact keep long threads alive.
Per-repo agent manifests
Project-level spettro.agents.toml plus prompt files in agents/ — each repo can define its own default agent and runtime.
Hooks + command policy
PreToolUse, PostToolUse, PermissionRequest, and SessionStart hooks. Persisted command approvals in .spettro/allowed_commands.json.
MCP + project indexer
MCP integration and a project indexer keep agents grounded in repo state instead of guessing from filenames alone.
From trust to resume, in five steps.
The default Spettro flow is documented and predictable. No black-box agents, no surprise file writes, no vendor lock-in.
Trust the project
Spettro starts with an explicit project trust handshake. Path-scoped permissions, no implicit access.
Connect a model
/connect adds a provider — hosted Anthropic, OpenAI-compatible, or a local OAI endpoint. Keys are encrypted.
Plan first
The plan agent reads the repo and proposes a change. You approve before any code is written.
Approve and code
Coding agent executes the queued plan. Tool calls are visible. Permission level is yours to choose.
Resume later
Sessions persist. /compact summarises context, /resume picks the work back up next time you open it.
The terminal coding assistant, as a real workflow.
Single-agent terminal assistants and editor chat panes are useful, but they collapse the whole job into one prompt. Spettro splits the work into roles you can see.
Everything important is already documented.
The repo ships its own docs. DeepWiki keeps a structured map of the codebase, including the agent runtime, provider layer, and storage model.
Questions that come up once you start using it for real work.
What makes Spettro different from a single-agent terminal assistant?
Spettro is built around explicit roles and handoffs. Planning, coding, review, docs, git, test, and explorer agents can each own part of the work instead of one assistant pretending to do everything the same way.
Does it support local models?
Yes. The docs cover OpenAI-compatible local endpoints such as LM Studio or Ollama, alongside hosted providers.
How does approval work?
Spettro exposes ask-first, restricted, and yolo permission modes. In stricter flows, plans pause before execution and continue only after approval.
What does first-time setup look like?
The documented path is straightforward: launch Spettro, confirm project trust, run /connect to add an API key or local endpoint, run /models to select a model, then start in plan mode.
Can it work with Anthropic and OpenAI-compatible providers at the same time?
Yes. The provider layer supports native Anthropic plus OpenAI-compatible APIs and local OpenAI-compatible endpoints, with model metadata loaded from models.dev and cached locally.
What happens in ask-first mode?
In ask-first mode, the normal path is to generate a plan first, review it, and then run /approve so the coding agent executes the queued plan instead of acting immediately.
Can I resume longer conversations later?
Yes. The docs describe persistent session storage for messages, tasks, and agent events, plus /clear, /resume, and /compact so longer threads stay manageable instead of vanishing.
Where does Spettro store its state?
It uses both global and project-local storage. Global state lives under ~/.spettro for config, encrypted keys, trusted paths, sessions, and cached models. Project-local state lives in .spettro for things like PLAN.md, allowed_commands.json, hooks, and optional index data.
Are API keys stored in plain text?
No. The configuration docs state that keys are encrypted with AES-GCM and are not stored in plaintext inside config.json.
Can I customize the agent workflow per repository?
Yes. Spettro can load a project-level spettro.agents.toml and prompt files in agents/, so each repository can define its own default agent, runtime settings, and handoff structure.
Does Spettro support hooks and command policies?
Yes. Global and project-local hooks can run on events like PreToolUse, PostToolUse, PermissionRequest, and SessionStart, and command approvals can be persisted per project in .spettro/allowed_commands.json.
What should I check if provider setup fails?
The troubleshooting docs recommend running /connect again, verifying your API key or local endpoint, checking that the endpoint responds to /v1/models, and then confirming the selected model in /models actually exists for that provider.
What if /approve does nothing useful?
The docs call out three common causes: no plan was generated first, there is no pending plan to execute, or the current permission mode is not what you think it is.
How do I keep large-repo sessions from blowing up context?
Use /budget to adjust token limits, /compact to summarize active context, /compact auto to control automatic compaction, and narrower prompts or focused file mentions when repository scans get heavy.
Get the source
Open the repo. Read the docs. Run it locally.
Free, open source, GPL-licensed. Spettro is built for developers who want a terminal assistant with explicit roles, approval flow, and provider freedom.