Angela

Angela is a terminal-based AI coding assistant built in Go, forked from Crush. It connects to LLMs and gives them tools to read, write, and execute code in your terminal.

Key capabilities:

• Multi-provider — Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, Ollama, and any OpenAI-compatible API
• Multi-agent — built-in coder, explore, plan, deep-research agents with configurable dispatch
• LSP integration — uses language servers for code intelligence, just like your editor
• MCP support — extend with Model Context Protocol servers (stdio, http, sse)
• Image input — paste images from clipboard or attach files for vision-capable models
• Hooks — user-defined shell scripts that fire before tool execution for policy enforcement
• Agent Skills — reusable instruction packages (Agent Skills standard)
• Cross-platform — macOS, Linux, Windows, Android, FreeBSD, OpenBSD, NetBSD

Installation

From GitHub Releases (pre-built binaries for all platforms), or with Go:

go install github.com/NaturalSelect/angela@latest

Getting Started

1. Run angela in your project directory.
2. Press Ctrl+L to open the model picker.
3. Choose a provider, paste your API key, and start coding.

Set API keys via environment variables to skip the manual step:

Variable	Provider
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI
GEMINI_API_KEY	Google Gemini
OPENROUTER_API_KEY	OpenRouter
AWS_PROFILE	Amazon Bedrock

See the full provider list for all supported variables.

Configuration

Angela is configured with angela.json. No config is required to get started.

{
  "$schema": "https://raw.githubusercontent.com/NaturalSelect/angela/main/schema.json",
  "providers": {
    "ollama": {
      "type": "ollama",
      "base_url": "http://localhost:11434/v1"
    }
  },
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer $GH_PAT" }
    }
  }
}

Config files are discovered by walking up from the working directory to the git worktree root. Multiple layers are deep-merged (project overrides global):

Priority	Path
1	./.angela.json or ./angela.json
2	~/.config/angela/angela.json

Selected string fields (API keys, headers, URLs) support $VAR and $(cmd) shell expansion.

For the full reference, see docs/config/.

Agents

Angela uses a multi-agent system. The main coder agent can delegate to specialized sub-agents:

Agent	Purpose
coder	Primary agent with all tools
explore	Fast read-only codebase search
plan	Interactive implementation planning (branch)
deep-research	Root cause analysis and design (branch)
general	Multi-step tasks with inherited tools
web-fetch	Web search and page fetching

Custom agents can be defined in angela.json or as markdown files. See docs/agents/.

Hooks

Experimental — no compatibility guarantee; may change or be removed in a future release.

Hooks are shell commands that fire before tool execution. Use them to block dangerous commands, rewrite tool input, inject context, or auto-approve safe operations.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "^Bash$", "command": "./hooks/no-rm-rf.sh" }
    ]
  }
}

See docs/hooks/ for the full guide.

Permissions

Angela asks before running tools. Configure allowed tools and declarative rules in angela.json:

{
  "permissions": {
    "allowed_tools": ["Read", "LS", "Grep"],
    "rules": [
      { "action": "deny", "tool": "read", "path": "**/.env" },
      { "action": "allow", "tool": "bash", "pattern": "git status*" }
    ]
  }
}

Use --yolo to skip all prompts (at your own risk). Use --auto-accept-edits to auto-approve file edits while still being asked about everything else; it cannot be combined with --yolo.

Use --sandbox to restrict the process itself with OS-level isolation (Linux via Landlock, macOS via Seatbelt) instead of relying on approval prompts. By default it leaves the working directory, Angela's own data directories, and outbound network access writable/reachable, and makes the rest of the filesystem read-only:

angela --sandbox
angela run --sandbox "..."

# Add extra directories on top of the defaults (repeatable)
angela run --sandbox --sandbox-rw /extra/writable --sandbox-ro /extra/readable "..."

# Also block outbound network access for commands the agent runs
# (Angela's own provider requests are unaffected; Linux only, refused on macOS)
angela run --sandbox --sandbox-no-network "..."

The default set is also widened with any directory an unconditional filesystem allow rule under permissions.rules (see Permissions above) already covers, so an edit or read the permission policy already approves without a prompt doesn't instead run into a confusing sandbox I/O error.

--sandbox is independent from --yolo and only supported in local (non-ANGELA_CLIENT_SERVER) mode, since the restriction is irreversible for the life of the process. Both Linux and macOS restrict the running process in place and return normally on success, so the interactive /sandbox command works the same way on both, not just at startup. --sandbox-no-network is Linux-only: an already-sandboxed macOS process can't apply a second, tighter profile to just the commands it spawns, so --sandbox --sandbox-no-network fails at startup on macOS instead of silently leaving those commands' network access open. macOS enforcement goes through sandbox_init(3), the same deprecated-but-still-present API sandbox-exec(1) itself is built on; if a future release removes it, --sandbox fails at startup instead of silently skipping the restriction.

When Angela runs inside VS Code's integrated terminal with the GitHub Copilot Chat extension active, an edit-shaped permission prompt also opens a native VS Code diff tab with Accept/Reject buttons, alongside the usual terminal dialog — whichever you answer first settles the request. Pass --no-vscode-diff to always use the terminal dialog only.

Local Models

Angela auto-discovers models from Ollama, LM Studio, llama.cpp, and other local providers:

{
  "providers": {
    "ollama": {
      "type": "ollama",
      "base_url": "http://localhost:11434/v1/"
    }
  }
}

Logging

Logs are stored in .angela/logs/angela.log relative to the project.

angela logs              # last 1000 lines
angela logs --follow     # real-time

Enable debug logging with --debug or "options": { "debug": true }.

License

Code inherited from charmbracelet/crush is FSL-1.1-MIT; original work added since is MIT. See LICENSE.md for the exact split.