README
¶
Sprout
AI-powered coding agent and development environment. Sprout gives you a chat-first CLI, a Web UI for visual work, and 11 specialized personas that collaborate to understand your workspace, edit code, run tests, open PRs, and orchestrate multi-step development tasks against any LLM provider.
Cost & safety: Using sprout involves LLM interactions and external services which may incur per-token costs. Sprout ships a tiered risk cascade (5 profiles —
readonly,cautious,default,permissive,unrestricted), per-hunk diff approval for edits, OS-notification-based agent completion signals, and configurable tool allowlists. Usecautiousorreadonlyuntil you understand the cost profile of your chosen model. See docs/SECURITY.md for the full model.
Features
Agent & personas
- Coding agent with workspace-aware context, self-correction, parallel subagents, and steerable execution
- 11 specialized personas that collaborate through structured delegation:
orchestrator(top-level routing),coordinator(long-running workflow driver),coder,refactor,tester,reviewer,debugger,researcher,web_scraper,general, andcomputer_user(desktop automation) - Mid-flight steering — type while a subagent runs and the message is delivered to the active subagent, not buffered
- Cooperative cancellation — Stop button (UI) or Ctrl-C (CLI) cancels the primary plus all running subagents
- 34 slash commands for in-session control —
/search,/compact,/clear,/rewind,/commit,/review,/risk-profile,/persona,/models,/max-context, and more
Editor, UI, and tools
- Web UI with chat, file tree, code editor, integrated terminal, git UI, settings, command palette, sessions picker, cost dashboard, and notifications
- Plan mode (
sprout plan) — interactive planning before any code changes - Cross-session search (
/search,sprout search) — full-text search across past sessions with debounced incremental indexing - MCP server integration — connect external tool servers (GitHub, Postgres, custom) via
sprout mcp - LSP support (
sprout lsp) — language servers for symbol resolution, diagnostics, and code intelligence - Skills system (
sprout skill,sprout skills) — loadable, versionable instruction packs for domain expertise - Computer-use persona (
computer_user) — desktop automation with screenshots, mouse, and keyboard under safety gates
Workflow automation & integrations
- Workflow automations — define autonomous agent workflows in
automate/*.jsonand run them withsprout automate - Background tasks, parallel subagents (
run_parallel_subagents), and cooperative cancellation for long-running work - PR creation (
sprout pr) — push branch and open GitHub PR from the CLI with title/body/base/head, with credential-store lookup andghCLI fallback - Review staged changes (
sprout review) — AI-powered code review on staged git diffs before commit - Service / daemon mode (
sprout service) — run sprout as a background daemon with HTTP API and WebSocket terminal/editor sessions - Onboarding flow (
docs/onboarding.md) — guided first-run setup with provider selection, API key validation, and a working first chat
Providers & models
- 12 first-party providers — OpenAI, DeepInfra, OpenRouter, Z.AI, GLM Coding Plan, DeepSeek, Mistral, MiniMax, LMStudio, Cerebras, Chutes, Ollama Cloud (plus a built-in self-hosted Ollama Local connector)
- Community provider registry — pull new providers from the curated registry via
docs/PROVIDER_REGISTRY.md - Custom OpenAI-compatible providers (
sprout custom add) — local llama.cpp, vLLM, ollama, or any OpenAI-shaped endpoint - Live provider catalog —
pkg/providercatalog/providers.jsonis embedded in the binary and refreshed fromraw.githubusercontent.comat startup so models stay current between releases
Safety, persistence, and context
- Risk cascade with 5 profiles (
readonly,cautious,default,permissive,unrestricted) plus per-call overrides - Per-hunk diff approval (
SP-072) — review and accept/reject each change before it lands - Persistent memory across conversations, with cross-session recall and structured summarization
- Built-in tool suite — file ops, web search, vision analysis, shell execution, PDF analysis, headless browser, image processing, atomic structured-file writes that preserve key order
- Change tracking — every file mutation is reversible via
sprout log/sprout history(rewind to any prior state) - Cross-session search — find past conversations by content with sub-100ms response once indexed
The UI component library (@sprout/ui) is also available as a standalone npm package for embedding in your own apps.
Installation
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/sprout-foundry/sprout/main/scripts/install.sh | sh
Windows (PowerShell 5.1+):
irm https://raw.githubusercontent.com/sprout-foundry/sprout/main/scripts/install.ps1 | iex
From source (requires Go 1.25.0+ and Node.js 22+):
git clone https://github.com/sprout-foundry/sprout.git
cd sprout
make deploy-ui && make prepare-grammars
go install .
Upgrade, uninstall, version pinning, checksum/provenance verification, Homebrew, and Termux: see the CLI Reference.
Getting started
sprout # interactive mode (Web UI at http://localhost:56000)
sprout agent "Create a python script that prints 'Hello, World!'"
sprout agent --persona coder "Add JWT auth to the API"
sprout plan # planning mode (no code changes)
sprout search "embedding index" # search past sessions
sprout review # review staged changes
sprout pr # open a PR for the current branch
sprout commit # generate a conventional commit
sprout shell "backup all .go files to a timestamped archive" # generate a shell script (review, then run manually)
First time? Follow the Onboarding guide for a guided provider-setup → first-chat flow.
Permissions & risk profiles
Before running a shell command, sprout consults a risk cascade that classifies the command and decides whether to run silently, prompt, or block. Five profiles ship out of the box (canonical descriptions from pkg/agent_commands/risk_profile.go):
| Profile | Behavior |
|---|---|
readonly |
Read-only operations only; any mutation is blocked |
cautious |
Most operations prompt; subagent writes blocked |
default |
Built-in defaults — auto-approves reads and common edits/commits; only destructive ops prompt |
permissive |
High trust; almost everything passes without prompting |
unrestricted |
No risk-cascade gating; only critical patterns (rm -rf /, fork bombs) block |
sprout agent --risk-profile=cautious "review this PR" # one session
# persistent default: set "risk_profile": "cautious" in ~/.config/sprout/config.json
Full reference, profile table, and custom overrides: docs/SECURITY.md#risk-profiles.
Documentation
| Document | Description |
|---|---|
| CLI Reference | All commands, flags, slash commands, personas, tools |
| Onboarding | Guided first-run setup (provider → API key → first chat) |
| Configuration | Config files, environment variables, Zsh detection, CI/CD |
| Fallbacks | Every default, inheritance, and fallback resolution chain |
| Architecture | Package layout, data flow, workspace files |
| Security | Risk profiles, tool call classification, security model |
| Personas | Persona system, risk model, and custom persona guide |
| MCP Integration | MCP server setup, configuration, troubleshooting |
| Agent Workflow | Config-driven workflow sequences |
| Service / Daemon | Run sprout as a long-lived HTTP/WS service |
| Provider Catalog | Provider catalog system and model metadata |
| Provider Registry | Remote provider registry, community provider PRs, schema |
| LSP Architecture | Language server integration |
| Component Library | @sprout/ui npm package usage and architecture |
| Electron Launcher | Desktop app wrapper |
| Testing | Test strategy, categories, and commands |
| Changelog | Per-release commit log |
| Roadmap | Authoritative spec docs (SP-###.md) for planned and shipped work |
Architecture in 30 seconds
- CLI binary (
sprout, Go) — cobra command tree withagent,plan,commit,review,pr,search,history,log,audit,lsp,mcp,service,config,policy,keys,embeddings,skills,automate,explain,diag,export-training,custom,upgrade,version - Web UI (
webui/, React 18 + Vite + TypeScript) — embeds into the Go binary viamake deploy-uiand is served by the daemon or bysproutitself in interactive mode - Shared UI library (
@sprout/ui, packages/ui) — extracted design-system components; both webui and downstream consumers import from it - Embedded provider catalog (
pkg/providercatalog/providers.json) — embedded in the binary; refreshed from GitHub at startup - Distributed via
scripts/install.sh; the sister projectsprout-foundrypins to aSPROUT_VERSIONand installs the binary in Docker images
For the full architecture: docs/ARCHITECTURE.md. For how the binary is consumed by sister projects: docs/FOUNDRY_CHAT_CONTRACT.md.
Platform Support
Sprout targets five build platforms. Most features work everywhere; some are inherently platform-specific (process management, terminal control, native embeddings). This matrix documents what's available on each.
Build targets
| Target | Build command | Usage |
|---|---|---|
| Linux/macOS (native) | go build . |
CLI daemon, WebUI server, full agent |
| Windows | go build . |
CLI daemon, WebUI server, full agent |
| WASM | make build-all (GOOS=js GOARCH=wasm) |
Browser shell, WebUI embedded agent |
| no-CGO | go build -tags '!cgo' |
Stripped binary without ONNX embeddings |
| Browser (rod) | go build . |
Requires Chromium for headless browser features |
Feature availability matrix
| Feature | Linux/macOS | Windows | WASM | no-CGO |
|---|---|---|---|---|
| Shell execution | ✅ Full | ✅ Full | ⚠️ No streaming | ✅ Full |
| Background processes | ✅ Process groups | ⚠️ No group kill | ❌ Not available | ✅ Full |
| Process signals | ✅ SIGINT→TERM→KILL | ⚠️ Kill only | ❌ N/A | ✅ Full |
| Vision / image analysis | ✅ Full | ✅ Full | ❌ Not available | ✅ Full |
| PDF processing | ✅ Full | ✅ Full | ❌ Not available | ✅ Full |
| Headless browser | ✅ Full (rod) | ✅ Full (rod) | ❌ Not available | ✅ Full |
| Code intelligence graph | ✅ SQLite store | ✅ SQLite store | ❌ Not available | ✅ Full |
| ONNX embeddings | ✅ Full (CGO) | ✅ Full (CGO) | ⚠️ JS bridge | ❌ Static fallback |
| Static embeddings | ❌ Uses ONNX | ❌ Uses ONNX | ✅ JS-native | ✅ Hash fallback |
| Terminal raw mode | ✅ ioctl (OPOST safe) | ⚠️ term.MakeRaw | ❌ N/A | ✅ Full |
| Terminal health | ✅ Termios capture | ⚠️ Always "sane" | ❌ N/A | ✅ Full |
| Signal handling | ✅ Full set | ⚠️ Interrupt only | ⚠️ Interrupt only | ✅ Full |
| OOM watchdog | ✅ /proc scan | ❌ No-op | ❌ No-op | ✅ Full |
| Automate sessions | ✅ PID tracking | ✅ PID tracking | ❌ Not available | ✅ Full |
| Foreground app detection | ✅ osascript/xdotool | ❌ Not available | ❌ N/A | ✅ Full |
| Panic key chord | ✅ CGEvent/xrecord | ❌ Not available | ❌ N/A | ✅ Full |
| Computer use | ✅ Full | ⚠️ No process groups | ❌ N/A | ✅ Full |
| Structured file tools | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Memory / settings | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Git operations | ✅ Full | ✅ Full | ❌ No filesystem | ✅ Full |
| Subagent spawning | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
Legend: ✅ Full support · ⚠️ Degraded but functional · ❌ Not available
Known platform limitations
WASM (browser): Cannot spawn processes, access the filesystem directly, or run native libraries. Shell commands route through a JS executor registered by the WebUI. Vision, codegraph, and background processes return informative errors. Terminal is hardcoded to 80×24.
Windows: No Unix process groups (Setpgid), so background process
cleanup can't cascade to children. Signal escalation uses
CTRL_BREAK_EVENT → TerminateProcess instead of SIGINT → SIGTERM →
SIGKILL. Terminal raw mode uses term.MakeRaw (may cause staircase
rendering without OPOST preservation). PID-alive checks may return false
positives.
no-CGO: ONNX Runtime requires CGO. Without it, embeddings fall back to a deterministic hash-based provider (384-dim FNV-1a). Search and recall work but with lower quality than ONNX models.
non-Linux: OOM watchdog has no /proc to scan, so memory alerts never
fire. Process start-time comparison (for PID-reuse detection) fail-opens.
Full audit details: see SP-112.
Contributing
See CONTRIBUTING.md for guidelines. Run make build-all and go test ./... before PRs.
Recommended MCP Servers
Sprout's MCP integration lets you connect external tool servers. Here are some that pair well with sprout's built-in capabilities:
| Server | What it adds |
|---|---|
| codebase-memory-mcp | Persistent codebase knowledge graph — call chains, dead-code detection, type-aware resolution, semantic code search across 158 languages. Extends sprout's native repo_map for very large or polyglot repos. |
| GitHub MCP | Direct GitHub API access — issues, PRs, reviews, actions, search. Complements sprout's built-in git and create_pull_request tools. |
| Postgres MCP | Read-only database queries and schema inspection. Useful when the agent needs to understand data shapes or debug data issues. |
| Filesystem MCP | Sandboxed filesystem access with configurable allowlists. Useful for restricting agent file access to specific directories. |
Add any of these with:
sprout mcp add
See docs/MCP_INTEGRATION.md for full setup, configuration, and troubleshooting.
License
Support
Report issues at github.com/sprout-foundry/sprout/issues.
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Agent command for sprout
|
Agent command for sprout |
|
embedding-wasm
command
|
|
|
enrich_registry
command
Command enrich_registry annotates freshly-generated canonical model files with capability-probe results.
|
Command enrich_registry annotates freshly-generated canonical model files with capability-probe results. |
|
model_probe
command
Command model_probe runs the capability probe against a single provider/model and prints the result as JSON.
|
Command model_probe runs the capability probe against a single provider/model and prints the result as JSON. |
|
model_registry_server
command
Command model_registry_server runs a lightweight static file server for serving per-provider model JSON files.
|
Command model_registry_server runs a lightweight static file server for serving per-provider model JSON files. |
|
refresh_provider_catalog
command
|
|
|
sync_provider_configs
command
Command sync_provider_configs updates the embedded provider config models.available_models field to match the canonical registry.
|
Command sync_provider_configs updates the embedded provider config models.available_models field to match the canonical registry. |
|
validate_registry
command
Command validate_registry checks every providers/*.json against the runtime schema before the publish workflow uploads to GitHub Pages.
|
Command validate_registry checks every providers/*.json against the runtime schema before the publish workflow uploads to GitHub Pages. |
|
wasm
command
|
|
|
pkg
|
|
|
agent
Auto-skip learning for ChangeTracker shell-mutation tracking.
|
Auto-skip learning for ChangeTracker shell-mutation tracking. |
|
agent_api
Package api provides API types used across all providers.
|
Package api provides API types used across all providers. |
|
agent_tools
Package tools provides the interface-based tool system for the Sprout AI agent.
|
Package tools provides the interface-based tool system for the Sprout AI agent. |
|
agent_tools/computer_use
Package computer_use denylist loader.
|
Package computer_use denylist loader. |
|
ast
Package ast (continued) — body extraction.
|
Package ast (continued) — body extraction. |
|
automate
Package automate provides shared workflow discovery and validation for the automate/ feature used by both the CLI (cmd/automate.go) and the agent tool layer (pkg/agent/tool_handlers_automate.go).
|
Package automate provides shared workflow discovery and validation for the automate/ feature used by both the CLI (cmd/automate.go) and the agent tool layer (pkg/agent/tool_handlers_automate.go). |
|
clihooks
Package clihooks holds tiny callback hooks that wire higher-level CLI behavior (e.g.
|
Package clihooks holds tiny callback hooks that wire higher-level CLI behavior (e.g. |
|
configuration
Package configuration provides high-level configuration and credential resolution for providers, including support for custom providers and stored credentials.
|
Package configuration provides high-level configuration and credential resolution for providers, including support for custom providers and stored credentials. |
|
console
Mouse tracking and context menu support for sprout IDE
|
Mouse tracking and context menu support for sprout IDE |
|
credentials
Package credentials provides unified credential resolution for all providers.
|
Package credentials provides unified credential resolution for all providers. |
|
embedding
Package embedding provides ONNX-based embedding infrastructure for sprout.
|
Package embedding provides ONNX-based embedding infrastructure for sprout. |
|
envutil
Package envutil provides environment variable helpers with SPROUT_*/LEDIT_* prefix support.
|
Package envutil provides environment variable helpers with SPROUT_*/LEDIT_* prefix support. |
|
errors
Package errors provides agent-specific error types and classification for intelligent retry/recovery logic.
|
Package errors provides agent-specific error types and classification for intelligent retry/recovery logic. |
|
events
Package events provides event system for sprout UI architecture
|
Package events provides event system for sprout UI architecture |
|
export
Package export provides functions to render Sprout session data as Markdown, HTML, or JSON documents.
|
Package export provides functions to render Sprout session data as Markdown, HTML, or JSON documents. |
|
history
Audit logging for SP-077: tracks every write-back of OriginalCode (or NewCode) to the working tree.
|
Audit logging for SP-077: tracks every write-back of OriginalCode (or NewCode) to the working tree. |
|
llmproxy
Package llmproxy provides an http.RoundTripper that rewrites direct calls to well-known LLM provider endpoints (api.openai.com, api.anthropic.com, etc.) so they instead route through the sprout-foundry platform's /api/proxy/llm/{provider}/* path.
|
Package llmproxy provides an http.RoundTripper that rewrites direct calls to well-known LLM provider endpoints (api.openai.com, api.anthropic.com, etc.) so they instead route through the sprout-foundry platform's /api/proxy/llm/{provider}/* path. |
|
lsp/proxy
Package proxy provides an LSP (Language Server Protocol) proxy manager that manages language server processes for workspace-aware code intelligence.
|
Package proxy provides an LSP (Language Server Protocol) proxy manager that manages language server processes for workspace-aware code intelligence. |
|
mcp
Package mcp provides secret management for MCP server environment variables.
|
Package mcp provides secret management for MCP server environment variables. |
|
modelcontract
Package modelcontract defines the canonical, provider-agnostic model schema and the adapter interface that normalizes each provider's native model API into it.
|
Package modelcontract defines the canonical, provider-agnostic model schema and the adapter interface that normalizes each provider's native model API into it. |
|
modelprobe
Package modelprobe runs a bounded capability probe against a model to check, cheaply and objectively, whether it's usable for agentic coding — and whether it's strong enough for complex work.
|
Package modelprobe runs a bounded capability probe against a model to check, cheaply and objectively, whether it's usable for agentic coding — and whether it's strong enough for complex work. |
|
modelregistry
Package modelregistry provides a client for fetching per-provider model lists from a static JSON model registry server with in-memory caching.
|
Package modelregistry provides a client for fetching per-provider model lists from a static JSON model registry server with in-memory caching. |
|
noninteractive
Package noninteractive provides utilities for detecting and handling provider-not-configured errors in non-interactive environments (daemons, CI, piped stdin).
|
Package noninteractive provides utilities for detecting and handling provider-not-configured errors in non-interactive environments (daemons, CI, piped stdin). |
|
notify
Package notify provides cross-platform OS-level desktop notifications.
|
Package notify provides cross-platform OS-level desktop notifications. |
|
providercatalog
Package providercatalog is the curated UX layer for provider onboarding — friendly descriptions, signup URLs, API-key help text, recommended-model justifications.
|
Package providercatalog is the curated UX layer for provider onboarding — friendly descriptions, signup URLs, API-key help text, recommended-model justifications. |
|
providerregistry
Package providerregistry provides a client for fetching provider connection configs from a remote JSON registry server with in-memory caching.
|
Package providerregistry provides a client for fetching provider connection configs from a remote JSON registry server with in-memory caching. |
|
redact
Package redact provides byte-oriented secret redaction for log files and other persisted artifacts.
|
Package redact provides byte-oriented secret redaction for log files and other persisted artifacts. |
|
search
Package search provides cross-session search indexing capabilities.
|
Package search provides cross-session search indexing capabilities. |
|
secretdetect
Package secretdetect provides secret detection backed by the gitleaks detection engine.
|
Package secretdetect provides secret detection backed by the gitleaks detection engine. |
|
skills
Package skills owns the catalogue of skills shipped with sprout.
|
Package skills owns the catalogue of skills shipped with sprout. |
|
testutil
Package testutil provides shared helpers for sprout's test suite.
|
Package testutil provides shared helpers for sprout's test suite. |
|
training
Package training provides utilities for exporting session data into training-ready formats (ShareGPT, OpenAI fine-tuning JSONL, Alpaca).
|
Package training provides utilities for exporting session data into training-ready formats (ShareGPT, OpenAI fine-tuning JSONL, Alpaca). |
|
utils
Package utils provides error handling utilities and conventions for the codebase.
|
Package utils provides error handling utilities and conventions for the codebase. |
|
validation
Package validation provides syntax validation using gofmt/goimports
|
Package validation provides syntax validation using gofmt/goimports |
|
webui
Package webui provides React web server with embedded assets
|
Package webui provides React web server with embedded assets |
|
gomlx
module
|
|
|
tensor
module
|
|
Click to show internal directories.
Click to hide internal directories.