sparrow-cli 0.5.9

A local-first Rust agent cockpit β€” route, run, replay, rewind
Documentation

🐦 Sparrow

A local-first Rust agent cockpit β€” route, run, replay, rewind.

CI Security Audit Release License: MIT Rust 1.96+ crates.io docs.rs Linux macOS Windows Downloads GitHub stars

One event stream. Terminal UI, WebView cockpit, JSON output, or gateway β€” your choice.

β–Ά Watch the 30-second demo

Quick Start Β· Why Sparrow Β· 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.

Why Sparrow vs Claude Code / Codex / Aider

Capability Claude Code OpenAI Codex CLI Aider Sparrow
Single static binary, no Node/Python runtime ❌ ❌ ❌ βœ…
Choose any provider, any model ❌ Anthropic ❌ OpenAI βœ… βœ… 38 providers
Local-first (Ollama OOTB) ❌ ❌ ⚠️ βœ…
Git checkpoints + rewind per run ❌ ❌ ⚠️ βœ…
Budget caps (--max-cost-usd / --max-wall-secs) ❌ ❌ ❌ βœ…
WebView cockpit + TUI + JSON stream ⚠️ TUI only ⚠️ TUI only ⚠️ TUI only βœ… all three
MCP server host + client βœ… ⚠️ ❌ βœ…
Drop-in import of ~/.claude/ config n/a ❌ ❌ βœ…
Multi-agent swarm (Planner β†’ Coder β†’ Verifier) ❌ ❌ ❌ βœ…
Telegram / Discord / Slack gateways ❌ ❌ ❌ βœ…
Pre-commit secret scanner bundled ❌ ❌ ❌ βœ…
Voice (speak, transcribe) ❌ ❌ ❌ βœ…
Replay & share session as URL/Gist ❌ ❌ ❌ βœ…
Source open, MIT ⚠️ closed ⚠️ closed βœ… βœ…
Zero telemetry by default ⚠️ ⚠️ βœ… βœ…

See docs/comparison/vs-competitors.md for the long form (incl. OpenCode, Hermes, Continue, Cursor).

✨ What's New β€” v0.5.8

Reliability and surface-polish release β€” the agentic loop now completes correctly against thinking-mode providers, the Windows TUI renders cleanly, the WebView no longer leaks selector metadata into prompts, and DeepSeek-style inline tool markup is recovered instead of leaking as text.

Engine

  • Multi-tool turns survive thinking-mode β€” a single model turn that emits N tool calls is now replayed as one assistant message with reasoning_content + all tool_calls, instead of N separate messages dropping reasoning_content. Fixes the HTTP 400 loop against DeepSeek / Qwen / Moonshot (and routes like opencode-go) that left multi-file tasks half-done.
  • Inline tool-call markup recovery β€” providers that emit <｜｜DSML｜｜invoke …> or <invoke name="…"> blocks in content (DeepSeek native format, Anthropic XML-style) now have those calls parsed and executed instead of leaked as raw text.

Windows TUI

  • UTF-8 console β€” SetConsoleOutputCP(65001) is set before alternate-screen entry. The mojibake (Γ’, ·, truncated words) is gone and box-drawing/middle-dot/arrows render correctly.
  • Clean initial buffer β€” terminal.clear() runs once at startup so stray dots from the parent shell prompt never bleed into empty panels.

WebView

  • Protocol-prefix isolation β€” the __agent:NAME__ROLE__BASE64__ and __model:M__ prefixes the console wraps around your input are now stripped at the very top of the dispatch loop. They no longer reach the LLM, the persisted conversation history, or the user-visible transcript.
  • GET /healthz β€” lightweight 200 OK liveness probe for IDE extensions and external orchestrators (no more 404).

Install & distribution

  • cargo install sparrow-cli v0.5.8 on crates.io.
  • Homebrew tap, Scoop bucket, winget manifests with real SHA256 against the v0.5.4+ release artifacts.
  • sparrow launch β€” first-run wizard auto-detects 20+ provider keys, ranks by cost tier, offers Ollama as a free fallback.

Tier 2 hardening (carried forward from v0.5.x)

  • CLI rich rendering, streaming + chat composer, TTS/STT/file_search, Memory CLI + FTS5 session search, voice commands.
  • Encrypted credential fallback store; honest hardened-sandbox reporting.
  • Pre-commit secret scanner; typed knowledge graph; Playwright e2e for browser/computer-use.
  • Humanized French errors for HTTP 401/429/connection/config failures.

Why Explore It
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

Status

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.

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.

Quick Start

Available today β€” same sparrow binary either way:

# Universal (Rust toolchain) β€” published on crates.io
cargo install sparrow-cli

# macOS / Linux β€” one-liner (pulls the latest GitHub release)
curl -fsSL https://raw.githubusercontent.com/ucav/Sparrow/master/install.sh | sh

# Windows β€” PowerShell one-liner
irm https://raw.githubusercontent.com/ucav/Sparrow/master/install.ps1 | iex

Or grab a prebuilt binary directly from the latest release (Linux x86_64, macOS arm64, Windows x86_64).

Package managers (manifests ready, publishing in progress):

# macOS β€” Homebrew
brew install ucav/tap/sparrow

# Windows β€” Scoop
scoop bucket add ucav https://github.com/ucav/scoop-bucket && scoop install sparrow

# Windows 11 β€” winget
winget install ucav.Sparrow

Then:

sparrow launch       # first-run picks a free provider, opens cockpit
sparrow run "explain this repo and write TODO.md"

That's the 60-second tour. No API key required β€” the first-run wizard offers a free provider (Groq / Gemini / NVIDIA) or local Ollama (auto-installed if missing).

Launch Sparrow:

sparrow launch

sparrow 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-targets

Run 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 --list

Force 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"

First Configuration

cargo run -- setup

Useful environment variables:

NVIDIA_API_KEY=...
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GROQ_API_KEY=...
OPENROUTER_API_KEY=...
OLLAMA_HOST=http://127.0.0.1:11434

Config lives in the platform config directory (e.g. %APPDATA%\sparrow\config.toml on Windows). Sparrow never needs API keys in the repository.

Provider Routing

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.

Common Commands

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 doctor

Custom 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.

Architecture

              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

Docs

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)

Contributing

Before opening a PR:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets

Keep docs honest: mark features as Stable, Alpha, Partial, Experimental, or Planned based on tests and runnable examples. See CONTRIBUTING.md.

License

MIT β€” see LICENSE.