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

Qu'est-ce que tu veux faire ? · What do you want to do?

N'importe qui peut utiliser Sparrow. Décris ton problème avec tes mots — Sparrow le règle, te montre, et garantit que rien n'est jamais perdu.

sparrow bonjour                 # accueil : Sparrow regarde ton dossier et propose
sparrow fix "mon site plante"   # décris le problème → diagnostic + correction
sparrow explique src/app.js     # comprends un fichier ou une erreur, en clair
sparrow idees                   # tout ce que tu peux faire, par profil
sparrow whatis token            # c'est quoi ce mot ? (définition instantanée)
sparrow annule                  # reviens en arrière — rien n'est jamais perdu

Sparrow te parle en langage simple par défaut (sparrow mode simple|pro). Pour le détail technique complet, tout le mode pro est là — rien n'est retiré.

Why Sparrow vs Claude Code / Codex / Aider

¹ Static registry of ~34 keyed providers; Ollama and NVIDIA are the routes verified end-to-end today — others depend on your credentials and provider availability. See the status table. ² ✅ = implemented and tested at the kernel level. 🔶 alpha = code is present and exercised by unit tests, but not yet end-to-end validated with live accounts. Labels are kept honest against the status table, not marketing.

See docs/comparison/vs-competitors.md for the long form (incl. OpenCode, Hermes, Continue, Cursor). This table reflects capabilities that exist in Sparrow today — it is a feature comparison, not a claim that Sparrow is universally "better" than mature tools.

✨ What's New — v0.9 « Anyone »

Radical accessibility. Anyone should understand and use Sparrow — a child, a grandparent, a teacher, a mechanic, an engineer. The engine doesn't change; the surface does. Focus mode for humans, Cockpit for pros. Same power, two depths.

🗣️ Zero jargon — Mode Simple / Pro

• sparrow mode simple|pro|auto — choose how Sparrow talks to you, persisted in config
• Every engine Event now has a human-language phrase (FR/EN) — no more run a3f2 · route · tier T1
• Exhaustive match at compile time: adding a new event without a human phrase fails to compile — anti-regression lock

🔧 sparrow fix — the universal fixer

• Paste an error message, describe a problem, or just run sparrow fix — it scans your directory, diagnoses in one sentence, and proposes a fix
• Automatic checkpoint before any change, one-word undo: sparrow annule

👋 sparrow bonjour — the warm welcome

• Detects your context (git conflict, uninstalled project, photo folder) and suggests the best next action
• No jargon, no flags — just "What are we fixing today?"

💡 sparrow idees — the idea gallery

• 50+ concrete recipes organized by persona: teacher, grandparent, child, artisan, builder, developer
• Pick a recipe, press Enter, watch Sparrow work — the recipe IS the tutorial

🖥️ Focus / Cockpit — one console, two views

• Focus (default): one column, large text, three buttons — [✅ Okay] [↩️ Undo] [❓ Explain]
• Cockpit: full 3-column view with swarm lanes, config, routing — zero power lost
• Right-side tools panel: Preview, Diff, Terminal, Files, Background tasks, Plan — every panel fed by real events, never mock data. Opens manually (Ctrl/⌘+Shift+S) or auto-opens on diffs, failed tasks, and plan updates with priority rules that never nag.
• Live preview detection: probes common dev ports (3000, 4200, 5173, 8080…) and embeds your running app in an iframe — or type any URL.
• Replay, finally one click: ▸ replay lists your recorded runs and re-renders any transcript — no more pasting run IDs.
• Ghost-text autocomplete: fish-style inline suggestion from your real command history — Tab to accept.
• Rich Markdown in chat: streamed prose renders bold, headings, lists, tables, links, and inline code.
• Keyboard cheat-sheet: Ctrl/⌘+/ shows every shortcut, grouped and platform-aware.
• New white theme alongside Captain and Paper — clean, high-contrast light UI.

🛡️ Safety net

• sparrow budget 2€ — set spending cap in human language
• sparrow annule — one-word undo, back to last checkpoint
• Contract displayed before ANY file modification: "I'll modify 2 files. Checkpoint created ✓. Proceed?"

Install & distribution

• cargo install sparrow-cli v0.9.2 on crates.io
• Pre-built binaries for Linux, macOS, Windows on every release
• sparrow launch — zero-question first launch with free/local fallbacks; --pro keeps the expert wizard

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

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, the GitHub Action, and most provider routes are alpha — present and unit-tested, but not yet end-to-end validated with live accounts.

Safety model (read before granting autonomy):

• Local-first, zero telemetry by default — nothing leaves your machine unless you call a cloud provider.
• Credentials stay local — OS keychain → encrypted auth.enc → env vars; never written to config or HTML in plaintext, redacted from logs/transcripts/model context.
• Checkpoints before mutating actions, one-word sparrow annule / sparrow rewind to restore.
• Autonomy gates: Supervised (asks before exec/mutate), Trusted, Autonomous. ⚠️ The current default is Trusted, which auto-runs exec and network tools (you are notified but not prompted); Destructive actions always ask. Set Supervised in config if you want a prompt before every command.
• Sandbox: local-hardened confines the working directory to your workspace and blocks known secret paths (.ssh, .env, …). On Linux it additionally wraps commands with firejail/bwrap (FS scoped to workspace, network denied) when those tools are installed; otherwise it falls back to in-process path checks. For strong isolation use the docker or ssh sandbox backend. See SECURITY.md.

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

Trust note. Piping a script to sh/iex runs code from the network. Read install.sh / install.ps1 first if you prefer. The installers verify the release SHA256 against the .sha256 published with each release, install to a user directory, print the exact binary path, and do not auto-launch — run sparrow launch yourself when ready (--launch / -Launch to opt in).

Or grab a prebuilt binary directly from the latest release (Linux x86_64, macOS arm64, Windows x86_64) — each ships a matching .sha256.

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 prepares a free/local fallback, opens Focus cockpit
sparrow run "explain this repo and write TODO.md"

That's the 60-second tour. No API key required — first launch prepares a free/local fallback and lets you start from the prompt. Use sparrow launch --pro if you want the detailed provider wizard.

Launch Sparrow:

sparrow launch

sparrow launch prepares Sparrow silently when needed, then opens the WebView Focus cockpit on http://127.0.0.1:9339/. Use sparrow launch --tui for the terminal cockpit, or sparrow launch --pro for the expert setup wizard.

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

Known limitations

Sparrow is honest about its edges:

• Provider routes other than Ollama and NVIDIA depend on your credentials and the provider's availability — they are implemented but not yet end-to-end verified.
• Gateways (Telegram/Discord/Slack) and the GitHub Action are alpha: the code paths exist and are unit-tested, but live token/account round-trips are not yet part of CI.
• Cloud sandboxes (Modal, Daytona, Vercel, Singularity) are experimental placeholders; for real isolation use the docker or ssh backend.
• WebView and TUI cockpits are evolving; expect rough edges on less common terminals.
• Default autonomy is Trusted — it runs exec/network tools without prompting. Switch to Supervised if you want a gate before each command.
• Package-manager installs (Homebrew/Scoop/winget) and crates.io/docs.rs availability may lag a release — if a badge or command doesn't resolve yet, use the release binary or --from-source.

Support & Sponsors

Sparrow is built in the open under MIT. If it helps you, the best support is trying it, filing precise issues, and contributing.

If you'd like to fund the work, GitHub Sponsors will be the only official sponsorship channel once the profile is active (see .github/FUNDING.yml). There are no crypto wallets, no private payment flows, and no third-party funding links — ignore anyone who asks you to send money any other way.

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.