🐦 Sparrow

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 · 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

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

✨ What's New — v0.7.1

Cost routing, zero-friction migration, and a self-improving engine. Sparrow routes every sub-task to the cheapest capable model (local free for reads, frontier for rewrites), then shows you exactly what you saved vs Claude Code. Import your existing setup in one command. The engine now learns per-repo, escalates on failure, and ships with a hardened reasoning protocol.

💰 Cost routing — Sparrow's competitive moat

• Every run ends with a cost comparison: "Sparrow $0.04 — Claude Code would have cost $0.61 (save 93%)"
• Shown on ALL surfaces: CLI run, TUI cockpit, chat, Telegram/Discord, WebView JSON
• Competitor pricing: Claude Code ($3/$15), Codex CLI ($2.5/$10), OpenCode ($3/$15) per MTok
• Sub-cent amounts displayed with precision ($0.0041 not "$0.00")

📦 Zero-friction migration — sparrow import

• sparrow import claude-code — CLAUDE.md → instructions, commands → slash, agents → SOUL, MCP servers imported, API keys detected
• sparrow import codex | opencode | openclaw | auto — one command, all your config
• Auto-detect: sparrow import auto finds every installed tool and imports each

🧠 Self-improving engine

• REFLEXION-MAX PROTOCOL V2 — default agent soul with tier triage, three-reviewer tribunal (skeptic/adversary/hurried user), verification by different method, absolute rules against simulated results
• Verified escalation — when a model exhausts its fix budget, the run climbs to the next model instead of failing silently
• Per-repo routing memory — the router learns which models succeed in your repo, self-corrects
• Transient retry + stuck-loop guard — one 429 doesn't downgrade your run; repeated tool calls trigger a nudge then honest stop
• Pre-run quote — sparrow run shows estimated cost before executing; --yes to skip

🖥️ Console & CLI

• Replay-on-connect — refresh mid-run replays current events instead of blank feed
• --continue / --fresh — session continuity visible across all surfaces
• sparrow skills install gh:user/repo — GitHub shorthand for skill installs
• Budget caps work after subcommand: sparrow run "task" --max-cost-usd 0.50

Install & distribution (v0.6.2 baseline)

• cargo install sparrow-cli v0.7.1 on crates.io
• Pre-built binaries for Linux, macOS, Windows on every release
• sparrow launch — first-run wizard with free provider fallbacks

What was already here (v0.5.x)

• Agentic engine with planner → coder → verifier pipeline, swarm orchestrator, git checkpoints + rewind.
• CLI rich rendering (syntect), streaming + chat composer, TTS/STT, voice commands.
• Memory CLI + FTS5 session search, encrypted credential store, pre-commit secret scanner.
• Humanized French errors, VS Code extension, Claude Code drop-in compat.

Why Explore It

Sparrow WebView cockpit — Captain theme

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.

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:

sparrow model --set nvidia resets an older pinned config back to this chain.

Common Commands

sparrow setup                      # first-run configuration
sparrow import auto                # migrate from claude-code / codex / opencode
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:

Docs

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.