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

Public distribution pass — one-click installers, simplified launch, and release metadata are ready for broader testing.

• One-click installers: Windows PowerShell plus macOS/Linux shell installers pull the latest GitHub release and fall back to source builds when needed.
• Simplified launch: sparrow launch runs first-launch setup when needed, then opens the WebView cockpit; sparrow launch --tui keeps the terminal path.
• Release workflow hardening: GitHub release publishing has explicit permissions and stable Windows asset naming for sparrow-windows-x86_64.exe.
• Syntax-highlighted code cards: fenced code is rendered in compact collapsible cards with language labels, line counts, copy actions, and local editor-style highlighting.
• Prompt caching controls: Anthropic Messages and OpenAI-compatible/Responses requests now carry cache controls for stable Sparrow prefixes.
• Reasoning-state continuity: DeepSeek/Qwen/Moonshot-style reasoning_content is captured, persisted, and re-injected without showing it as visible assistant text.
• Persistent knowledge graph: SQLite memory now stores typed graph nodes/edges with a knowledge_graph tool and optional Neo4j sync.
• Playwright browser/computer-use: real headless browser automation plus screenshot/click/type computer actions gated as sandboxed exec.
• Safer plan flow: WebView /plan has explicit run, edit, and reject actions before execution.
• Per-hunk diff review UI: diff cards and the side panel group patches by hunk with accept/reject review states.
• No metric spam: high-frequency token/cost events update live meters without flooding the transcript.
• Cleaner typography: WebView uses system UI fonts with SF Mono-style code rendering.
• Repo hygiene: local handoffs, scratch files, and presentation-only artifacts are kept out of the public tree.
• Release metadata: version, changelog, and README status align on v0.3.6.

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

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.