sprout

command module

v0.17.19 Latest Latest Go to latest Published: Aug 24, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/sprout-foundry/sprout

Links

Open Source Insights

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. Use cautious or readonly until 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, and computer_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
42 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/*.json and run them with sprout 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 and gh CLI 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.json is embedded in the binary and refreshed from raw.githubusercontent.com at 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
Local LLM (MLX)	Run a local model via MLX — no API key or network
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 with agent, 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 via make deploy-ui and is served by the daemon or by sprout itself 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 project sprout-foundry pins to a SPROUT_VERSION and 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 runs on Linux, macOS, and Windows with full agent capabilities, plus WASM (browser-embedded) and no-CGO builds. Some features are platform-specific (process management, terminal control, native embeddings).

Full platform compatibility matrix: docs/PLATFORM_SUPPORT.md

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

MIT License.

Support

Report issues at github.com/sprout-foundry/sprout/issues.

Documentation ¶

Rendered for

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

Path	Synopsis
cmd Agent command for sprout	Agent command for sprout
audit_pricing command
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 Package agent: delegation getters and setters for sub-managers.	Package agent: delegation getters and setters for sub-managers.
agent_api Package agent_api: LM Studio model-list discovery.	Package agent_api: LM Studio model-list discovery.
agent_commands
agent_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.
cliui Package cliui hosts the CLI terminal display helpers extracted from cmd/.	Package cliui hosts the CLI terminal display helpers extracted from cmd/.
codecompletion
codegraph
codereview
commands
configuration Package configuration: command categorization and force-flag detection.	Package configuration: command categorization and force-flag detection.
console Package console.	Package console.
credentials Encryption and decryption operations	Encryption and decryption operations
daemon Package daemon — Phase 2: Daemon lifecycle + auto-start machinery.	Package daemon — Phase 2: Daemon lifecycle + auto-start machinery.
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_* prefix support.	Package envutil provides environment variable helpers with SPROUT_* 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 Event bus implementation	Event bus implementation
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.
factory
filediscovery
filesystem
git
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.
index
interfaces/types
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.
localmodel Package localmodel manages the lifecycle of the local LLM server (cmd/llm_server) that runs on Apple Silicon via MLX.	Package localmodel manages the lifecycle of the local LLM server (cmd/llm_server) that runs on Apple Silicon via MLX.
logging
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.
lsp/semantic
mcp Package mcp provides secret management for MCP server environment variables.	Package mcp provides secret management for MCP server environment variables.
model_settings
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.
personas
prompts
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 Remote provider cache and configuration.	Remote provider cache and configuration.
pythonruntime
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.
security
service
skills Package skills owns the catalogue of skills shipped with sprout.	Package skills owns the catalogue of skills shipped with sprout.
spec
testutil Package testutil provides shared helpers for sprout's test suite.	Package testutil provides shared helpers for sprout's test suite.
text
tools
trace
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).
types
ui
utils Package utils provides error handling utilities and conventions for the codebase.	Package utils provides error handling utilities and conventions for the codebase.
utils/console Package console provides Windows console utilities shared between pkg/automate (StopProcess escalation) and pkg/agent_tools (interruptProcessGroup).	Package console provides Windows console utilities shared between pkg/automate (StopProcess escalation) and pkg/agent_tools (interruptProcessGroup).
utils/pidalive Package pidalive provides a single canonical answer to "is this PID alive?" for all of sprout.	Package pidalive provides a single canonical answer to "is this PID alive?" for all of sprout.
validation Package validation provides syntax validation using gofmt/goimports	Package validation provides syntax validation using gofmt/goimports
wasmshell
webcontent
webui Package webui provides React web server with embedded assets	Package webui provides React web server with embedded assets
workflow
zsh
gomlx module
tensor module
smoke_tests

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL