<div align="center">
# ๐ฆ Sparrow
**A local-first Rust agent cockpit โ route, run, replay, rewind.**
[](https://github.com/ucav/Sparrow/actions/workflows/ci.yml)
[](https://github.com/ucav/Sparrow/actions/workflows/audit.yml)
[](https://github.com/ucav/Sparrow/releases)
[](LICENSE)
[](https://rust-lang.org)
[](https://crates.io/crates/sparrow-cli)
[](https://docs.rs/sparrow-cli)
[](https://github.com/ucav/Sparrow/releases/latest)
[](https://github.com/ucav/Sparrow/releases/latest)
[](https://github.com/ucav/Sparrow/releases/latest)
[](https://crates.io/crates/sparrow-cli)
[](https://github.com/ucav/Sparrow/stargazers)
<img src="assets/brand/sparrow-mascot.svg" width="140" alt="Sparrow mascot" />
*One event stream. Terminal UI, WebView cockpit, JSON output, or gateway โ your choice.*
[](https://ucav.github.io/Sparrow/demo.html)
[Quick Start](#quick-start) ยท [Why Sparrow](#why-sparrow-vs-claude-code--codex--aider) ยท [Commands](#common-commands) ยท [Architecture](#architecture) ยท [Docs](#docs) ยท [Releases](https://github.com/ucav/Sparrow/releases)
</div>
---
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
| 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`](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 |
<br>
<p align="center">
<img src="docs/screenshots/webview-captain.png" alt="Sparrow WebView cockpit" width="90%">
<br><em>Sparrow WebView cockpit โ Captain theme</em>
</p>
---
## 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.
<details>
<summary><strong>Full status table</strong> (click to expand)</summary>
| 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 |
</details>
See [docs/AUDIT.md](docs/AUDIT.md) for module-by-module proof.
---
## Quick Start
**Available today โ same `sparrow` binary either way:**
```bash
# Universal (Rust toolchain) โ published on crates.io
cargo install sparrow-cli
# macOS / Linux โ one-liner (pulls the latest GitHub release)
# Windows โ PowerShell one-liner
Or grab a prebuilt binary directly from the
[latest release](https://github.com/ucav/Sparrow/releases/latest)
(Linux x86_64, macOS arm64, Windows x86_64).
**Package managers (manifests ready, publishing in progress):**
```bash
# 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:**
```bash
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](docs/getting-started.md). No API key required โ
the first-run wizard offers a free provider (Groq / Gemini / NVIDIA) or local
Ollama (auto-installed if missing).
**Launch Sparrow:**
```bash
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:**
```bash
git clone https://github.com/ucav/Sparrow.git
cd Sparrow
cargo build
cargo test --all-targets
```
**Run the WebView cockpit:**
```bash
cargo run -- launch
# โ open http://127.0.0.1:9339/
```
**Routing smoke test:**
```bash
cargo run -- --json run "how does Sparrow choose the best model?"
```
**List detected providers and models:**
```bash
cargo run -- model --list
```
**Force a specific route:**
```bash
# 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
```bash
cargo run -- setup
```
Useful environment variables:
```bash
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:**
| `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
```bash
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:**
| [`src/event.rs`](src/event.rs) | Canonical event stream |
| [`src/provider/mod.rs`](src/provider/mod.rs) | `Brain` abstraction |
| [`src/router/mod.rs`](src/router/mod.rs) | Model ranking and fallbacks |
| [`src/engine/mod.rs`](src/engine/mod.rs) | Agent loop |
| [`src/tools/mod.rs`](src/tools/mod.rs) | Tool contracts |
| [`src/gateway/mod.rs`](src/gateway/mod.rs) | External message routing |
---
## Docs
| [docs/AUDIT.md](docs/AUDIT.md) | Module-by-module proof |
| [docs/architecture.md](docs/architecture.md) | System architecture |
| [docs/cli-reference.md](docs/cli-reference.md) | Full CLI reference |
| [docs/routing.md](docs/routing.md) | Routing and provider chains |
| [docs/autonomy.md](docs/autonomy.md) | Permission modes and hooks |
| [docs/sandboxing.md](docs/sandboxing.md) | Sandbox policy and backends |
| [docs/browser-computer.md](docs/browser-computer.md) | Playwright browser and computer-use tools |
| [docs/replay.md](docs/replay.md) | Replay and checkpoints |
| [docs/swarm.md](docs/swarm.md) | Multi-agent swarm |
| [docs/keyboard.md](docs/keyboard.md) | Keyboard shortcuts |
| [docs/configuration.md](docs/configuration.md) | Configuration reference |
| [assets/brand/](assets/brand/) | Brand assets (SVG, HTML, ASCII) |
---
## Contributing
Before opening a PR:
```bash
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](CONTRIBUTING.md).
---
## License
MIT โ see [LICENSE](LICENSE).