# π¦ββ¬ Crow
[Documentation](https://crow-ai.dev)
`crow-cli` is an [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) coding agent: a streaming ReAct loop that reads and edits code, runs shells, searches the web and sees images.
This repo is the **agent**. The first-party clients (terminal, TUI, IDE, browser) that drive it over the same wire live in their own repo, [`crow-cli/crow`](https://github.com/crow-cli/crow) β `crates/crow-client` for the `crow-agent` TUI, `packages/crow-gui` for the IDE build, `packages/vscode-acp` + `packages/chat` for the chat extension. `crow-cli init` clones it beside this one and `crow-cli install crow` builds from it.
Two ideas hold the whole thing together.
**Persistence is the point.** Every session lives in a SQL database (`~/.agents/crow/crow.db` β sqlite by default, PostgreSQL when you want one store shared across machines) with full-text search over every message. Agents recall past conversations, read each other's sessions and delegate work to one another through that store; there is no bespoke agent-to-agent protocol, just a shared database and a read query. Images are content-addressed files beside the database, hydrated to base64 only when they are actually sent to the LLM. Sessions get memorable coolname ids (`taupe-squirrel-of-splendid-potency`) you can resume, fork, or read from any other agent.
**The client owns the tools.** The agent has *no* builtin tool supply. Whatever MCP servers the client hands it at `session/new` are exactly the tools that session gets β see [Tools](#tools-the-client-owns-the-supply). crow's own clients pass crow's own MCP server, which is why a fresh install works; a third-party client passes its own.
## Requirements
The agent:
- Python 3.13+, managed with [uv](https://docs.astral.sh/uv/)
- Docker, for the SearXNG service that backs web search
- An API key for an OpenAI-compatible LLM provider (OpenRouter, OpenAI, your own endpoint, β¦)
The clients, if you want to build them β a clone of [`crow-cli/crow`](https://github.com/crow-cli/crow), which `crow-cli init` leaves at `~/.agents/crow/src/crow`:
- Rust (`rustup` + `cargo`) for the `crow-agent` TUI
- node matching that repo's `packages/crow-gui/vscodium/.nvmrc` (24.x), `npm`, `bun`, `jq`, `curl`, `unzip`, the libx11/libxkbfile/libsecret headers, and `fakeroot` + `dpkg-dev` for the `.deb` β all of it for the IDE build, which is a from-source VS Code
| Platform | Notes |
|----------|-------|
| Linux | glibc 2.35+ (Ubuntu 22.04+, Debian 12+, or equivalent); the IDE build and installer are Linux-only today |
| macOS | 13+ (Ventura), Intel and Apple Silicon |
| Windows | 10+ (64-bit); WSL2 recommended |
## Setup
```bash
uv tool install crow-cli --python 3.13 # from PyPI
```
β¦or from a clone, which you want anyway if you mean to build the clients β `install crow` builds them from a checkout of their own repo:
```bash
git clone https://github.com/crow-cli/crow-cli.git
cd crow-cli
uv tool install . --python 3.13 # or run without installing: uvx --from . crow-cli --help
```
Then configure it and start the backing services:
```bash
crow-cli init # wizard: provider, model, secrets, services
cd ~/.agents/crow && docker compose up -d # starts SearXNG (written by init, not started by it)
```
`crow-cli init` walks you through provider and model selection and writes:
| Path | What it is |
|------|------------|
| `~/.agents/crow/config.yaml` | providers, models, `mcpServers`, `agent_servers`, `db_uri` |
| `~/.agents/crow/.env` | secrets, referenced from the config as `${VAR}` (chmod 600) |
| `~/.agents/crow/compose.yaml` + `searxng/settings.yml` | the services init offers: SearXNG, PostgreSQL, RustFS |
| `~/.agents/crow/prompts/` | `system_prompt.jinja2` β edit it, it is yours |
| `~/.agents/crow/src/` | checkouts init clones and `uv sync`s: `crow-cli`, `crow` (the clients) and `crow-cli.github.io` (the website). `--no-source` skips them |
| `~/.agents/skills/crow-cli` | the crow-cli skill, installed globally on purpose: it is the BIOS, so an agent can repair a broken spawn |
**Nothing runs from that checkout implicitly.** What init does with it is write one `agent_servers` entry into `config.yaml` β ordinary config, which you can read, edit or delete:
```yaml
agent_servers:
crow-cli:
type: custom
command: uv
args: ["--project", "/home/you/.agents/crow/src/crow-cli", "run", "crow-cli", "acp"]
```
A bare `crow-cli run` drives the top entry, so on a fresh init that is the checkout; delete the entry and crow drives its own agent β always the code that is actually running, never a directory it chose for you. (An implicit "re-exec into `~/.agents/crow/src`" override used to exist and is gone: it fought worktrees and project checkouts.) `crow-cli agents` prints what will run.
## Quick start
```bash
# One-shot prompt β prints the response and exits
crow-cli run "explain what this repo does"
# Continue an existing session by id
crow-cli run -s "now add tests"
# Send a long, pre-written prompt from a file or stdin
crow-cli run -f delegation.md -s
cat prompt.md | crow-cli run -
# Interactive REPL
crow-cli run -i
# Machine-readable: one JSONL event per line (session, thinking, message, tool_call, usage, result, error)
crow-cli run -j "refactor the parser" > run.jsonl
# Run as an ACP agent server (for editors and other clients)
crow-cli acp # ACP v1, stdio β spawned by a client
crow-cli acp2 # ACP v2, stdio β spawned by a client
crow-cli acp2 --http # β¦or one server for every dialling client: ws://127.0.0.1:2771/acp
```
`--http` is the one you leave running in a terminal of its own: a single instance serves the IDE, the browser client and anything else that dials it. See [Clients](#clients) for who starts what.
Which agent runs is config, not code: `crow-cli agents` lists the `agent_servers` entries, `-a NAME` drives one, and a bare `run` drives the top entry (crow's own v2 agent when nothing is configured).
The rest of the CLI is observability into the same store:
| Command | What it does |
|---------|--------------|
| `crow-cli inspect` | session state and messages (`--session --messages`) |
| `crow-cli list-sessions` | every session, most-recently-active first β who's working now |
| `crow-cli query-memory` | BM25 search across all sessions |
| `crow-cli query-session` | read or search one session across all its agents |
| `crow-cli models` / `agents` | what config.yaml offers |
| `crow-cli mcp` / `mcp2` | serve crow's tools to any MCP client |
| `crow-cli timers` | the worker that fires scheduled wakes |
| `crow-cli install crow` | build the IDE `.deb`, `dpkg -i` it, install the agent TUI β from a clone, since that is where the build lives |
## Clients
One agent, several front doors. Every one of them is an ACP client; they differ in where the pixels come from β and in who starts the agent.
Two shapes, and only two:
- **Diallers** β the IDE's chat panel and the browser client. They spawn nothing. In another terminal, run a single instance of the agent and leave it running:
```bash
crow-cli acp2 --http # one server for every client on this machine: ws://127.0.0.1:2771/acp
```
- **Spawners** β `crow-cli run` and `crow-agent`. They start their own agent over stdio (the top `agent_servers` entry, or `--agent`), so they need no server.
| Client | What it is | The agent | Run it |
|--------|-----------|-----------|--------|
| `crow-cli run` | the reference client: one-shot, REPL, JSONL, session forks | spawns its own over stdio | `crow-cli run "β¦"` |
| `crow-agent` | Rust ratatui TUI (`crates/crow-client` in the `crow` repo) | spawns its own over stdio β `--agent`, default `crow-cli acp2` | `crow-agent` |
| crow IDE | VS Code built from source by the `crow` repo's `packages/crow-gui`, with the crow chat extension bundled as a built-in β desktop app and browser server | dials `crowAcp.endpoint`, default `ws://127.0.0.1:2771/acp` | `crow` |
| any ACP client | Zed and friends, over stdio or WebSocket | the client spawns the command you give it | `crow-cli acp` / `acp2` |
**The args, exactly.** `acp --http` serves protocol v1 on **2769**; `acp2 --http` serves v2 on **2771**; `--host` (default `127.0.0.1`) and `--port` move either. One v2 instance is enough for every dialler β the IDE panel's `crowAcp.endpoint` defaults to `ws://127.0.0.1:2771/acp`. A client that only speaks v1 needs `crow-cli acp --http` instead, on 2769. `acp2 --no-default-tool` starts an agent with no tools of its own: config.yaml's `mcpServers` are not merged into a session, so the session's tools are exactly the ones its client sent in `session/new`. That is how a client gives an agent a single purpose β a conductor whose only arm is the three tools it was handed β by construction rather than by asking nicely in a prompt.
### `crow-agent` β the terminal client
A ratatui ACP client in the `crow` repo's `crates/crow-client`. It spawns the agent itself (`--agent`, default `crow-cli acp2`) so there is nothing to start first, and it is a real terminal citizen: markdown rendering, syntax-highlighted diffs, drag-to-select copy, tool calls that expand in place, `!` for a shell line and `/` for commands.
```bash
cd ~/.agents/crow/src/crow # the clients repo; `crow-cli init` clones it
cargo build --release --bin crow-agent
crow-agent # in the current workspace
crow-agent -w ~/src/project --session-id # resume a durable session
crow-agent --model # ask the agent for a model (default: $CROW_MODEL)
crow-agent --demo # scripted turns, no agent needed
```
### crow β the IDE
The `crow` repo's `packages/crow-gui` builds crow's IDE from Microsoft's open-source VS Code using a **vendored copy of VSCodium's build pipeline**, rebranded, with crow's patches in `packages/crow-gui/vscodium/patches/user/`. Two artifacts come out and both are first-class:
| Artifact | What it is | Entry point |
|----------|-----------|-------------|
| `vscodium/VSCode-linux-/` | the Electron desktop app | `bin/crow` |
| `vscodium/vscode-reh-web-linux-/` | the browser server (`reh-web`) | `bin/crow-server` |
The chat panel is that repo's `packages/vscode-acp` (`crow-acp`), built with bun and copied into every packaged tree as a **built-in** extension alongside the Jupyter + Python stack pinned in `packages/crow-gui/bundled-exts.json` β so notebooks get a kernel picker with no marketplace install.
```bash
uv run crow-cli install crow # from the clone: builds the .deb, installs it with dpkg, builds the TUI
```
The IDE is a dialler β it does not start the agent. In another terminal, run a single instance and leave it running:
```bash
crow-cli acp2 --http # ws://127.0.0.1:2771/acp, which is what crowAcp.endpoint already points at
```
Then open whichever front door you want:
```bash
crow # the desktop IDE
crow serve-web # the same IDE in a browser, through the IDE's own CLI, which prints a tokenised URL
crow agent # the crow-agent TUI β the one front door that spawns its own agent
```
The chat panel is a webview that dials the agent directly and spawns nothing: `crowAcp.endpoint` (default `ws://127.0.0.1:2771/acp`, i.e. `acp2 --http`), `crowAcp.protocol` (`1`, `2` or `auto`), `crowAcp.cwd`, and `crowAcp.mcpConfig` β the tool supply it hands over at `session/new`, by default `crow-cli mcp2`. Nothing listening at that endpoint, nothing to chat with.
`serve-web` starts the `reh-web` server that ships **beside** the IDE (`/usr/share/crow/web`, or `$CROW_WEB_DIR`): crow publishes no release tarballs, so there is nothing to download and no update check to fail.
The install **is** the `.deb`, and that is not pedantry: `dpkg -i` is the only route that gets a root-owned `4755 chrome-sandbox`, which Chromium requires β without it the desktop app can die silently on kernels that restrict unprivileged user namespaces (Ubuntu 24.04+). So `install crow` runs the pipeline with `--deb` (it wants `fakeroot` + `dpkg-dev`, and says so *before* a 40-minute build rather than after) and then installs it.
`install crow` works from anywhere: it builds from the clients checkout it is running in, and a packaged install (pip / uv tool) with no checkout beside it falls back to `~/.agents/crow/src/crow`, cloning it first if that is missing. The whole install, by hand, is:
```bash
cd ~/.agents/crow/src/crow # if it exists; otherwise git clone https://github.com/crow-cli/crow.git there
cd packages/crow-gui && ./build.sh --arch x64 --deb # IDE + web server + the .deb; ~40 min the first time
sudo dpkg -i vscodium/assets/crow_*.deb # system-wide: /usr/share/crow, /usr/bin/crow, /usr/bin/crow-web
cd ../.. && cargo build --release --bin crow-agent # the agent TUI
mkdir -p ~/.local/bin && install -m 755 target/release/crow-agent ~/.local/bin/
crow-cli install crow --no-build # writes the ~/.local/bin/crow shim; the deb is already built
```
There is no separate `bun install` / `bun run build` step: `build.sh` builds `packages/vscode-acp` (the `crow-acp` chat extension) and drops it into every packaged tree as a built-in, together with the Jupyter + Python stack. The last line is the only one with no shell equivalent β the `crow` shim is forty lines of POSIX sh (`launcher_text()` in `src/crow_cli/cli/install_crow.py`), and `--no-build` writes it without touching the pipeline.
A deb that is already built is installed without rebuilding (`--rebuild` forces the pipeline). `--no-deb` is the rootless fallback: it copies the trees to `~/.local/share/crow/{ide,web}` and writes a user-level `.desktop` entry β a build you can run, not an install, with no setuid sandbox, and it says so up front. The deb route deletes that user-level entry instead of letting it shadow the package's.
### Any other ACP client
For [Zed](https://zed.dev/), declare the agent *and* its tool supply β Zed forwards `context_servers` to external agents over ACP, and an agent handed nothing runs with zero tools:
```json
{
"agent_servers": {
"crow-cli": { "command": "crow-cli", "args": ["acp"] }
},
"context_servers": {
"crow-mcp": { "command": "crow-cli", "args": ["mcp"], "env": {} }
}
}
```
## Tools: the client owns the supply
This is the part that surprises people, so it is worth stating plainly: **the agent has no builtin MCP servers.** `mcpServers` in `~/.agents/crow/config.yaml` is consumed by the *client* β `crow-cli run` converts it to ACP `mcpServers` and passes it at `session/new`/`load_session`. Empty or absent means the session runs with zero tools. `crow-cli init` writes the entry below, which is the only reason a fresh install has tools at all:
```yaml
mcpServers:
crow-mcp:
transport: stdio
command: crow-cli
args: [mcp]
```
An `agent_servers` entry may carry its own `mcpServers`, which *replaces* the global supply for that agent only β that is how a v2 agent gets `crow-mcp2` without changing what the v1 sessions on the same box are handed.
One binary serves two tool surfaces:
### `crow-cli mcp` β the flat tool set (ACP v1)
| Tool | What it does |
|------|--------------|
| `read` / `write` / `edit` | File access β `edit` does precise, fuzzy-matched string replacement |
| `terminal` | Run shell commands in the workspace |
| `execute` | The persistent IPython kernel (below) |
| `web_search` / `web_fetch` | Search the web (via SearXNG) and fetch pages as markdown |
| `capture_webcam` / `read_image_file` | Vision input |
| `list_sessions` / `query_memory` / `query_session` | Memory |
| `task` | Launch, re-prompt and cancel subagents |
`--include-tools` narrows it to an allowlist (spawn the server several times to get several servers out of one codebase), `--transport http` serves it as a streamable HTTP service, and `--list-tools` prints the names.
### `crow-cli mcp2` β `execute`, and only `execute` (ACP v2)
The v2 surface is one tool: a **persistent IPython kernel** that survives the whole session. Variables, imports, open handles and cwd carry from one cell to the next, so work is written as successive cells rather than as one-shot shell invocations β and crow's capabilities are ambient inside it, bound by a prelude as lazy facades:
| Subtool | What it does |
|---------|--------------|
| `fs` / `write` / `edit` | File access β read/stat/list, write, and precise edits that return a diff |
| `web` | `search`, `fetch`, `run` (headless browser), `close` |
| `memory` | Read-only SQL over the whole session store |
| `rlm` | Delegate a subtask to another model, blocking |
| `vision` | Bring an image into the conversation |
| `sg` | ast-grep: structural search and rewrite |
| `task` / `task_read` / `task_send` / `task_cancel` | Subagents and their mailboxes (v2 kernels) |
| `goal_start` / `goal_done` / `goal_blocked` / `goal_reset` | The continuation loop that keeps a long sprint running (v2 kernels) |
| `reload` | Re-bind the tool facades in place, without losing kernel state |
`help(tool)` works out of the box on every one of them.
> β οΈ **Tool names are not namespaced.** `crow-cli mcp` registers `read`, `edit`, `terminal`, β¦ β not `crow_read`. When you add your own MCP servers, watch for collisions.
### Persistence β SQL memory
sqlite by default (single machine, zero setup); point `db_uri` at PostgreSQL for memory shared across machines, so agents on any box see the same sessions, messages and task mailboxes. Search is a real index on both backends β an FTS5 virtual table with bm25 ranking on sqlite. The layer lives in `src/crow_cli/memory` and is tested in `tests/memory/test_store.py`.
### SearXNG β web search
crow-cli ships a maintained SearXNG configuration (stored as Python, so it survives a PyInstaller freeze β sorry) so search works out of the box without hand-editing SearXNG settings. `crow-cli init` writes `compose.yaml` and `searxng/settings.yml`; `docker compose up -d` in `~/.agents/crow` starts it.
### Skills
Agents load reusable skills from `~/.agents/skills/` β each a directory with a `SKILL.md` saying when and how to use it, scanned at session creation and injected into the system prompt. Skill distribution is still being worked out; today skills are local directories.
## Configuration
`~/.agents/crow/config.yaml` holds providers, models, MCP servers and the agent registry; secrets live in `~/.agents/crow/.env` and are interpolated with `${VAR}`.
```yaml
providers:
openrouter:
api_key: ${OPENROUTER_API_KEY}
base_url: https://openrouter.ai/api/v1
models:
my-model:
provider: openrouter
model: anthropic/claude-sonnet-4
agent_servers:
my-agent:
protocol: acp2
command: uv
args: ["--project", "~/.agents/crow/src/crow-cli", "run", "crow-cli", "acp2"]
mcpServers:
crow-mcp2:
transport: stdio
command: crow-cli
args: [mcp2]
```
The first model is the default; the top `agent_servers` entry is the agent a bare `crow-cli run` drives. Every entry is a command honored exactly as written β crow never substitutes its own agent for a configured one. `protocol` is optional: leave it out and the client asks the agent at `initialize`, then drives whatever it answers, so an entry cannot disagree with its own agent.
## Development
```bash
git clone https://github.com/crow-cli/crow-cli.git
cd crow-cli
uv sync
```
Run the test suite β every tier runs unconditionally (unit + integration + e2e live LLM):
```bash
uv run pytest tests
```
To run a single tier, point pytest at its directory:
```bash
uv run pytest tests/unit # fast, hermetic
uv run pytest tests/integration # real sqlite, agent spawn
uv run pytest tests/e2e # live LLM calls (costs $)
```
The clients build in their own repo β `cd ~/.agents/crow/src/crow`. There: the Rust client with cargo (`cargo build --release --bin crow-agent`; `crates/crow-client` is the workspace's only member), the chat webview and the extension with bun (`bun install` at the root, then `bun run ext:build`), and the IDE with `packages/crow-gui/build.sh` (`--help` lists its flags; `--prepare-only` stops after fetch + patch + `npm ci`). Its CI is `.github/workflows/build-ide.yml` and `build-tui.yml` in that repo.
## Project layout
```
src/crow_cli/ the agent β ACP v1 + v2 servers, ReAct loop, CLI
src/crow_cli/agent/ the v1 agent: session, tools, MCP client, memory
src/crow_cli/agent2/ the v2 agent: the execute-kernel driver
src/crow_cli/client/ the v1 client (`crow-cli run`)
src/crow_cli/client2/ the v2 client
src/crow_cli/mcp/ the flat MCP tool server (`crow-cli mcp`)
src/crow_cli/mcp2/ the execute-only MCP server (`crow-cli mcp2`)
src/crow_cli/tools/ the in-kernel subtools the prelude binds
src/crow_cli/config/ config loading, defaults, overrides (shared by every layer)
src/crow_cli/memory/ shared SQL persistence (sqlite default, PostgreSQL supported)
tests/ unit, integration, e2e
```
The clients are a separate repo β [`crow-cli/crow`](https://github.com/crow-cli/crow), cloned by `init` to `~/.agents/crow/src/crow`:
```
crates/crow-client/ crow-agent β the ratatui ACP client TUI
packages/chat/ the chat webview source (@crow/chat) β the extension's UI
packages/aui/ vendored assistant-ui, as built dist
packages/vscode-acp/ crow-acp β the chat extension bundled into the IDE
packages/crow-gui/ the IDE build pipeline (vendored VSCodium + crow's patches)
```
## License
MIT β see [LICENSE.md](./LICENSE.md).