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

✨ What's New — v0.4.0

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 --release green, 0 warnings, 9.3 MB binary.

Why Explore It

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

Install from crates.io (recommended):

cargo install sparrow-cli

One-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 | sh

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