GitHub

Crow is an extensible AI agent that runs in your terminal. Point it at a project, describe the outcome you want, and it reads files, runs commands, and makes the edits.

Quickstart

To run Crow you need access to a language model through a supported provider — a subscription, an API key, or a locally hosted model.

1. Install Crow

Pick your platform above — Linux, Windows, or npm (Node.js 22.19 or newer). Confirm the installation with crow --version.

2. Start Crow

Terminal
cd /path/to/folder
crow

The working directory decides which files, instructions, and saved sessions Crow uses.

3. Choose a model

Inside Crow, run /login, select a provider, and follow the prompts to authenticate with a subscription or store an API key. Run /model afterwards to switch between the models available to you.

4. Give Crow a task

Describe the outcome you want in plain language. Crow shows every file read, command, and edit as it works, and you can steer it at any point.

Usage

Work in the terminal is a conversation: type a prompt, watch Crow plan and execute, and reply to redirect it. You can steer while it runs, or change the model mid-task.

  • Reference files and folders directly in your prompt so Crow reads the right context.
  • Run terminal commands yourself from the same interface when you want to check something.
  • Switch work modes with /mode: plan is read-only analysis, build uses the full tool set, and ask is Q&A only.

Everyday slash commands

/settingsOpen the settings screen
/model [provider/model]Pick a model
/mode [plan|build|ask]Switch work mode
/login [provider]Register provider authentication
/newOpen a new session
/resumeMove to another saved session
/treeBrowse the session tree

Configuration

Crow reads configuration from two places: a per-user agent directory and a per-project .crow directory, so personal defaults and project-specific setup stay separate.

  • Agent directory — global settings, stored credentials, personal MCP servers, skills, and themes. Override its location with the CROW_CODING_AGENT_DIR environment variable.
  • Project .crow directory — project settings (.crow/settings.json), project MCP servers (.crow/mcp.json), and project-scoped extensions, skills, prompts, and themes.
  • Context files — instruction files such as .crow/SYSTEM.md and .crow/APPEND_SYSTEM.md shape how Crow behaves in a project.

Models

A model produces Crow's responses; a provider is the service or account Crow uses to reach it. Use /model to pick from everything your connected providers offer, and /scoped-models to set the short list used for interactive cycling.

  • Subscription and API-key providers, authenticated once with /login.
  • Local models, including a llama.cpp router administered with /llama.
  • Fully custom providers, declared in configuration when a service is not built in.

Providers

The fastest path is interactive: run /login and authenticate through a browser or device flow backed by OAuth, or paste an API key. Run /logout to remove stored authentication.

  • API keys can also come from environment variables, so a key exported in your shell is picked up automatically.
  • Cloud platforms are supported directly: Azure OpenAI, Amazon Bedrock, Cloudflare AI Gateway, Cloudflare Workers AI, and Google Vertex AI.

Sessions

Sessions are saved per project and hold the full conversation — prompts, tool calls, and results. Resume earlier work with /resume, start fresh with /new, and name sessions with /name so they are easy to find.

Branching

/treeNavigate inside the current session file — best when related alternatives belong together
/forkBuild a new session from an earlier user message — best when the alternative deserves its own work
/cloneCopy the active branch into a new session — an independent copy of the current state

Extensions

Extensions are TypeScript modules that plug into Crow's runtime: they can add tools, react to lifecycle events, register commands, and shape the terminal UI. If a workflow needs behaviour Crow does not have, an extension is usually the smallest way to add it.

  • Extensions load from the agent directory, from a project's .crow/extensions (trust-gated), or from installed Crow packages.
  • Tools added by an extension appear alongside the built-in ones and can be activated dynamically.

MCP

Crow connects to Model Context Protocol servers to use their tools. Manage servers from the shell — no session required:

Terminal
crow mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
crow mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
crow mcp list
crow mcp login <server>
crow mcp remove docs
  • Personal servers and servers holding credentials belong in ~/.crow/agent/mcp.json; keep project servers in .crow/mcp.json, and only in projects you trust.
  • crow mcp list connects to every enabled server and reports its state, its tools, and any startup problems.

Skills and Prompts

Skills are reusable instruction bundles — a SKILL.md file, optionally with supporting files — that teach Crow a repeatable workflow. Crow loads the skills a task needs from the agent directory, the project, or installed packages.

  • Create a skill when you find yourself explaining the same procedure twice; write it once and Crow reuses it.
  • Prompt templates turn a long, precise prompt into a short reusable command.

CLI Reference

Running crow with no arguments opens the interactive terminal UI in the current directory. The same binary also works non-interactively from scripts and other programs.

--mode jsonRun the given prompts, emit JSONL events to stdout, then exit
--mode rpcRead JSONL commands from stdin and write responses and events to stdout until shutdown
--export <input> [output]Convert a session file to HTML and exit
--provider <provider>Select the provider for a run or credential lookup
--model <model>Select the model for a run; combinable with --provider

Related command groups cover credentials (crow auth …), MCP servers (crow mcp …), and installing, updating, and removing Crow packages.

Settings

Open the settings screen with /settings, or edit the settings files directly — global settings live in the agent directory and project settings in .crow/settings.json, with project values taking precedence.

  • Model and reasoning — default model, provider, and thinking level (/thinking).
  • Tools — which tools are available and how they run.
  • Sessions and context — storage, automatic compaction, and branch summaries.
  • Terminal and display — themes and rendering options.

Security

Crow's tools and extensions execute with the same operating-system permissions as the Crow process itself. Project trust gates which project resources load, but it does not sandbox tool execution — treat Crow like running any other program on your machine.

What project trust protects

  • .crow/settings.json and other project settings
  • .crow/mcp.json and the MCP servers it declares
  • .crow/extensions, .crow/skills, .crow/prompts, and .crow/themes
  • .crow/SYSTEM.md and .crow/APPEND_SYSTEM.md
  • Packages a project declares through its settings
GitHubnpmHome