🐦‍⬛ Crow

Documentation

crow-cli is an Agent Client Protocol (ACP) coding agent that runs in your terminal and inside ACP-compatible editors. It reads and edits code, runs shell commands, searches the web, and remembers your work across sessions.

Most agent toolkits treat persistence as an afterthought. crow-cli treats it as the point: every session lives in a local sqlite database (~/.agents/crow/crow.db) with FTS5 full-text search, so agents recall past conversations and can delegate work to one another. Images are stored as files next to the database and hydrated only when sent to the LLM. Sessions get memorable coolname ids (like taupe-squirrel-of-splendid-potency) you can resume or read from any other agent.

Requirements

• Python 3.14+, managed with uv
• Docker, for the SearXNG service
• An API key for an OpenAI-compatible LLM provider (OpenRouter, OpenAI, your own endpoint, …)

Setup

Install the CLI:

git clone https://github.com/crow-cli/crow-cli.git
cd crow-cli
uv tool install . --python 3.14      # or run without installing: uvx --from . crow-cli --help

Initialize your configuration and start the backing services:

crow-cli init                          # scaffolds ~/.agents/crow (config.yaml, .env, docker-compose)
cd ~/.agents/crow && docker compose up -d     # starts SearXNG

crow-cli init walks you through provider and model selection and writes your secrets to ~/.agents/crow/.env, referenced from the config as ${VAR}.

Quick start

# 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 <session-id> "now add tests"

# Send a long, pre-written prompt from a file or stdin
crow-cli run -f delegation.md -s <session-id>
cat prompt.md | crow-cli run -

# Interactive REPL
crow-cli run -i

# Run as an ACP agent server (for editors)
crow-cli acp

Inspect stored sessions with crow-cli inspect (add --session <id> --messages to see a session's messages).

Using crow-cli in your editor

crow-cli speaks ACP, so it works with any ACP-compatible client. For Zed, add to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "crow-cli": {
      "type": "custom",
      "command": "crow-cli",
      "args": ["acp"]
    }
  }
}

The agent detects client capabilities (terminals, file read/write) and uses the native ACP versions when available, falling back to MCP tools otherwise.

What's in the box

The agent

An ACP-native agent: a streaming ReAct loop with tool calling, cancellation, conversation compaction, and multimodal input. Provider and model configuration lives in ~/.agents/crow/config.yaml.

Persistence — sqlite memory

Sessions persist to a single sqlite database (~/.agents/crow/crow.db, schema v5, WAL mode) with an FTS5 index for BM25 keyword search. Images in messages are written to ~/.agents/crow/images/ and referenced by path; they are hydrated to base64 data URLs only when the conversation is sent to the LLM. The same database backs the memory API, exposed to agents as three tools:

• list_sessions() — sessions ordered by recent activity (who's working on what)
• query_memory(query) — find which session discussed something, across all sessions
• query_session(session_id) — read or search within one session (spans all of that session's agents)

This is what makes multi-agent delegation work: launch a worker, then read its thoughts from any other agent. No service to run — the sqlite file is the integration point.

Built-in MCP tool server

The bundled MCP server (crow-cli mcp) providing the agent's tools:

Extensible by design: register any MCP server in ~/.agents/crow/config.yaml and its tools appear alongside these automatically.

⚠️ Tool names are not namespaced. The built-in server registers its tools as read, edit, terminal, … — not crow_read. When you add your own MCP servers, watch for name collisions.

SearXNG — web search

crow-cli ships a maintained SearXNG configuration (stored as JSON so the agent can drive it over MCP) so web search works out of the box, without hand-editing SearXNG settings.

Skills

Agents load reusable skills from ~/.agents/skills/ — each a directory with a SKILL.md describing when and how to use it. Skill distribution is still being worked out; today skills are local directories.

Configuration

~/.agents/crow/config.yaml holds providers, models, and MCP servers; secrets live in ~/.agents/crow/.env and are interpolated with ${VAR}.

providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    base_url: https://openrouter.ai/api/v1
models:
  my-model:
    provider: openrouter
    model: anthropic/claude-sonnet-4

Development

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):

uv run pytest tests

The persistence layer itself lives in src/crow_cli/memory and is tested in tests/memory/test_store.py. To run a single tier, point pytest at its directory:

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 $)

Project layout

src/crow_cli/           the agent — ACP server, ReAct loop, CLI
src/crow_cli/config/    config loading, defaults, overrides (shared by every layer)
src/crow_cli/mcp/       built-in MCP tool server (`crow-cli mcp`)
src/crow_cli/memory/    shared SQL persistence (sqlite default, postgres-ready)

License

MIT