Code with agents you trust.
Spettro is a terminal-first, open-source coding assistant with real agent handoffs - plan, approve, code, and resume without leaving your shell.
curl -sSfL https://spettro.app/install | shReal 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, add skills and memory, 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.
Install skills, save memory, and write custom slash commands that match your repo.
Anthropic, OpenAI-compatible, or local. Model catalog cached from models.dev.
Kernel-level sandboxing, invisible to the model.
Spettro confines shell commands with Seatbelt on macOS and Landlock on Linux. The policy is set by the operator through CLI flags or the agent manifest, and the model cannot inspect or change it.
Choose `off`, `workspace-write`, or `read-only`. File tools honor the same scope, so `read-only` cannot be bypassed by writing through a file tool.
Choose `all`, `localhost`, `none`, or a port list like `ports:443,8080`. The Spettro parent still reaches the LLM API, but sandboxed commands are confined.
Set the policy from the command line or lock it into `spettro.agents.toml`. CLI flags take precedence.
On Linux, an unenforceable Landlock policy exits 126, so an opt-in sandbox never silently runs unconfined.
# Read-only review, no network spettro --sandbox read-only --sandbox-net none # Safe autonomous run with API access only spettro --goal "refactor auth" \ --sandbox workspace-write \ --sandbox-net ports:443 # Read-only build with external module cache spettro --sandbox read-only \ --sandbox-allow-read-dir ~/go/pkg/mod
Every part of the workflow is a first-class surface.
Manifest-driven agents, goal mode, skills, approval flow, provider routing, encrypted keys, memory, web tools, hooks, and custom commands - all in one terminal-native runtime.
Multi-agent runtime
Manifest-driven roles for plan, coding, review, docs, git, test, and explorer agents. Orchestrators delegate to workers; handoffs are explicit, not hidden in one prompt.
Goal mode
Run `/goal <objective>` and let Spettro work autonomously across iterations. It detects stalls, resumes progress, and calls `goal-complete` when done.
Agent Skills
Install reusable capability packs from local folders, git URLs, or `owner/repo` shorthands. Compatible with Claude Code skills.
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`.
Persistent sessions
Messages, tasks, and agent events are saved automatically. `/clear`, `/resume`, and `/compact` keep long threads alive.
Persistent memory
Save facts and preferences across sessions with `/memory`. User-scope and project-scope memory load into every run.
Web tools
Built-in `web-search`, `web-fetch`, and `download` with SSRF-hardened HTTP, an HTML-to-markdown engine, and network approval flow.
Runtime hooks
Middleware on PreToolUse, PostToolUse, PermissionRequest, and SessionStart. Enforce project-specific guardrails with JSON + bash.
OS sandboxing
Seatbelt on macOS and Landlock on Linux confine shell commands. Filesystem modes and network policies are set by the operator and are invisible to the model.
Custom slash commands
Write reusable prompts as TOML or markdown files in `~/.spettro/commands/` or `<repo>/.spettro/commands/`, then run them as `/command`.
Extended thinking
`/thinking <off|low|medium|high|x-high|max>` sets extra reasoning budget for the active model, mapped per provider.
Remote, Telegram & ACP
`/remote` exposes an HTTP/SSE control plane, `/telegram` drives sessions from a chat, and `--acp` integrates with ACP-capable editors.
Clipboard & attachments
Paste images with `Ctrl+V`, attach files with `Ctrl+F`, copy the last response with `Ctrl+Y`, and toggle text-select with `Ctrl+T`.
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, `/models` selects the model. Hosted or local, your keys are encrypted.
Plan first
The plan agent reads the repo and proposes a change. You review and run `/approve` before any code is written.
Add skills & memory
Install `/skill` packs, save `/memory` facts, and define custom `/commands` so the workflow matches your repo.
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. Start with getting started, explore commands, architecture, sessions, goals, skills, memory, and more.
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.
What is goal mode?
Goal mode lets you set an objective like `/goal update all dependencies` and Spettro runs autonomously across iterations, verifying progress and stopping when done, stalled, or interrupted.
What is Ultra mode?
Ultra mode is Spettro's swarm-style execution: it breaks a task down, then spawns and delegates to many sub-agents that work on it in parallel. It's available on every plan, from Free to Max.
How do Agent Skills work?
Skills are reusable instruction packs in `SKILL.md` format. Install them from a local path, a git URL, or `owner/repo`, and every Spettro agent picks them up automatically.
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?
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. An onboarding wizard also guides first-time users.
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.
What is persistent memory?
You can save short facts and preferences with `/memory`. User-scope memory lives in `~/.spettro/memory.md`; project-scope memory lives in `<repo>/.spettro/memory.md`. Both load into every session.
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`.
Can I create my own slash commands?
Yes. Save TOML or markdown prompt files to `~/.spettro/commands/` or `<repo>/.spettro/commands/`. They support `{{args}}` placeholders and optional shell interpolation.
Can I control Spettro remotely or from Telegram?
Yes. `/remote` starts an HTTP/SSE control plane for external clients, and `/telegram` sets up a Telegram bot relay so you can drive sessions from your phone.
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.
How does sandboxing work?
Spettro uses Seatbelt on macOS and Landlock on Linux to confine shell commands. You set the policy via CLI flags or `spettro.agents.toml`. Modes include `read-only`, `workspace-write`, and network policies like `none` or `ports:443`. It is opt-in, invisible to the model, and fails closed when a policy cannot be enforced.
How does the Spettro subscription work?
`/login` starts a device-flow login in the TUI. Once signed in, your plan gives you access to Spettro-hosted models under a single key. Pro and Max plans fall back to a free-tier model with automatic retry when your monthly credits run out.
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.
curl -sSfL https://spettro.app/install | sh