A local-first Rust agent cockpit — route, run, replay, rewind.
One event stream. Terminal UI, WebView cockpit, JSON output, or gateway — your choice.
Quick Start · Commands · Architecture · Docs · Releases
Sparrow is a single-binary CLI agent written in Rust. It routes each task to the cheapest capable model, keeps you in control with Git-backed checkpoints, and makes every run replayable. Local models (Ollama) are always the first hop; cloud providers are explicit fallbacks.
The project focuses on a narrow product promise: a Rust-native local cockpit where every run is visible, replayable, budgeted, and checkpointed.
Public launch readiness — crates.io publish, first-run wizard, live demo, community skills, security hooks, and humanized error messages.
cargo install sparrow-cli— now on crates.io. One command, no curl.- First-run wizard — auto-detects API keys, validates them, offers free providers (NVIDIA, Groq, Gemini) with one-click setup.
sparrow demo— self-contained snake game coding demo in 30 seconds. Live Planner→Coder→Verifier pipeline.sparrow share— share session transcripts as GitHub Gists. One command.sparrow hook install— pre-commit security scanner. Blocks commits with secrets, tokens, or private keys.- 10 community skills — explain-error, generate-commit, write-unit-tests, review-my-pr, refactor-function, onboard-newbie, fix-bug, optimize-sql, api-docs, deploy-check.
- Humanized French errors — HTTP 401 becomes "Ta clé API est invalide. Va sur https://... pour en créer une."
- Provider auto-detection — scans 20+ env vars, validates keys, ranks by cost tier (free first).
- Release build verified —
cargo build --releasegreen, 0 warnings, 9.3 MB binary.
| Model routing | Budget-aware fallback chains across Ollama, NVIDIA, Anthropic, OpenAI-compatible APIs, and 30+ registry entries |
| WebView cockpit | Live route/token/cost/context at http://127.0.0.1:9339/ with drawer panels, slash palette, and agent picker |
| Terminal-native | Animated TUI cockpit, sparrow run, sparrow chat, --json output, replay, memory, gateway |
| Rollback safety | Auto-checkpoint before any mutating action; sparrow rewind <id> to restore |
| Persistent context | SQLite facts + knowledge graph, SOUL-style .agent.md files, guarded skill registry, full transcripts |
| Browser/computer-use | Playwright-backed browser tool and gated screenshot/click/type computer primitive |
| Gateway | Telegram, Discord, Slack, WebSocket API — wired with honest errors, not silent failures |
Sparrow WebView cockpit — Captain theme
Sparrow is public beta with a green cross-platform CI baseline. The kernel, routing core, console surfaces, replay, checkpoints, and memory are wired and tested; external transports are being validated by early adopters.
Full status table (click to expand)
| Area | Status | Evidence |
|---|---|---|
| CI / Rust build | ✅ Stable | Ubuntu · macOS · Windows; fmt, clippy -D warnings, check, release builds |
| Test suite | ✅ Stable | Full cargo test green on current master |
| Security audit | ✅ Stable | rustsec/audit-check on all three platforms |
| Engine loop | ✅ Stable | Event stream, task classification, fallback execution, auto-checkpoint, auto-compaction |
| WebView console | ✅ Stable | Full cockpit — rail/drawer, typed event stream, compact highlighted code cards, themes, composer, approval modal |
| TUI cockpit | ✅ Stable | Animated cockpit, swarm lanes, checkpoint/diff/cost panels, @ picker, history |
| Plan mode / slash | ✅ Stable | sparrow plan, /plan, built-in commands, user/project Markdown discovery |
| Permissions / hooks | ✅ Stable | 6 permission modes; Pre/Post lifecycle hooks for run/tool/checkpoint/compact |
| Declarative agents | ✅ Stable | SOUL TOML + Markdown frontmatter; agent run, agent mention, CRUD |
| Skills / plugins | ✅ Stable | Progressive references + templates; plugin manifests; CLI install/list/remove |
| Toolsets | ✅ Stable | Toolset/risk/auth/mutation/network/exec metadata; surface filtering |
| Browser / computer-use | 🔶 Alpha | Playwright driver, screenshot blocks, click/type, Linux bwrap wrapper when available |
| Security audit CLI | ✅ Stable | sparrow security audit [--json], WebView /security |
| Sandbox policy | ✅ Stable | Protected paths, env allowlist; Docker/SSH/Worktree backends; honest vendor errors |
| Media tools | ✅ Stable | vision, image_generate, text_to_speech, transcribe; WebView upload/artifacts |
| GitHub Action | ✅ Stable | action.yml, sample workflow, sparrow github review/status/logs, --dry-run |
| Context / compaction | ✅ Stable | ContextMeter, engine auto-trigger at 120k chars, durable HandoffDoc |
| Gateway | ✅ Stable | /status roundtrip on port 9338; run registry with real abort |
| Replay / memory | ✅ Stable | Recorder, checkpoint, rewind, SQLite facts, knowledge graph, optional Neo4j sync, bounded MEMORY.md, session search |
| Provider routing | 🔶 Alpha | Ollama + NVIDIA tested locally; 92 NVIDIA models discovered |
| First-run setup | 🔶 Alpha | Conversational setup agent + interactive fallback |
| Telegram / Discord / Slack | 🔸 Partial | Transport implementations exist; E2E token validation pending |
| Extra transports | 🧪 Experimental | WhatsApp, Signal, Email, Feishu, WeCom, QQ, Teams adapters present |
| Cloud sandboxes | 🧪 Experimental | Modal, Daytona, Vercel, Singularity — placeholder entries |
| Cross-platform release | ✅ Stable | Linux · macOS · Windows pre-built binaries on every tag |
See docs/AUDIT.md for module-by-module proof.
Install from crates.io (recommended):
cargo install sparrow-cliOne-click install:
# Windows
irm https://raw.githubusercontent.com/ucav/Sparrow/master/install.ps1 | iex# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ucav/Sparrow/master/install.sh | shLaunch Sparrow:
sparrow launchsparrow launch runs first-launch setup when needed, then opens the WebView cockpit on
http://127.0.0.1:9339/. Use sparrow launch --tui for the terminal cockpit.
Build from source:
git clone https://github.com/ucav/Sparrow.git
cd Sparrow
cargo build
cargo test --all-targetsRun the WebView cockpit:
cargo run -- launch
# → open http://127.0.0.1:9339/Routing smoke test:
cargo run -- --json run "how does Sparrow choose the best model?"List detected providers and models:
cargo run -- model --listForce a specific route:
# Local Ollama first
cargo run -- --local run "summarize this repo"
# Explicit NVIDIA route
cargo run -- --model nvidia:meta/llama-3.1-8b-instruct run "explain routing"
# Coding / reasoning route
cargo run -- --model nvidia:deepseek-ai/deepseek-v4-flash run "refactor this function"cargo run -- setupUseful environment variables:
NVIDIA_API_KEY=...
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GROQ_API_KEY=...
OPENROUTER_API_KEY=...
OLLAMA_HOST=http://127.0.0.1:11434Config lives in the platform config directory (e.g. %APPDATA%\sparrow\config.toml on Windows). Sparrow never needs API keys in the repository.
Sparrow keeps a static provider registry and expands it with live model discovery when credentials are available. Stored credentials added with sparrow auth add nvidia are used for discovery, so sparrow model --list can populate the NVIDIA catalog even when NVIDIA_API_KEY is not exported.
Default NVIDIA chain:
| Model | Use case |
|---|---|
meta/llama-3.1-8b-instruct |
Fast general chat and cheap smoke tests |
stepfun-ai/step-3.5-flash |
Fast backup route via NVIDIA NIM |
nvidia/nemotron-3-super-120b-a12b |
Stronger fallback for heavier tasks |
sparrow model --set nvidia resets an older pinned config back to this chain.
sparrow setup # first-run configuration
sparrow plan "propose an approach" # read-only plan mode
sparrow console # launch WebView cockpit
sparrow run "fix the failing test"
sparrow --json run "summarize" # NDJSON output for CI/hooks
sparrow chat # interactive session
sparrow model --list # discovered providers & models
sparrow gateway start # start gateway (Telegram/Discord/WS)
sparrow gateway status
sparrow gateway stop
sparrow replay <run-id> # replay a past run
sparrow checkpoint list
sparrow rewind <checkpoint-id> # restore workspace
sparrow memory list
sparrow memory graph search routing
sparrow security audit
sparrow doctorCustom slash commands can be declared as Markdown files in .sparrow/commands/*.md or %APPDATA%\sparrow\commands\*.md. User-level commands override project and built-in ones by name. Skills are also exposed as slash commands.
user task
│
routing-need classifier
│
budget-aware fallback chain
│
Engine
think → tool → observe → emit
│
┌──────────┼───────────┐
CLI TUI WebView
JSON Gateway Recorder
Load-bearing contracts:
| File | Role |
|---|---|
src/event.rs |
Canonical event stream |
src/provider/mod.rs |
Brain abstraction |
src/router/mod.rs |
Model ranking and fallbacks |
src/engine/mod.rs |
Agent loop |
src/tools/mod.rs |
Tool contracts |
src/gateway/mod.rs |
External message routing |
| Document | Topic |
|---|---|
| docs/AUDIT.md | Module-by-module proof |
| docs/architecture.md | System architecture |
| docs/cli-reference.md | Full CLI reference |
| docs/routing.md | Routing and provider chains |
| docs/autonomy.md | Permission modes and hooks |
| docs/sandboxing.md | Sandbox policy and backends |
| docs/browser-computer.md | Playwright browser and computer-use tools |
| docs/replay.md | Replay and checkpoints |
| docs/swarm.md | Multi-agent swarm |
| docs/keyboard.md | Keyboard shortcuts |
| docs/configuration.md | Configuration reference |
| assets/brand/ | Brand assets (SVG, HTML, ASCII) |
Before opening a PR:
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targetsKeep docs honest: mark features as Stable, Alpha, Partial, Experimental, or Planned based on tests and runnable examples. See CONTRIBUTING.md.
MIT — see LICENSE.