Skip to content

Installation

Install angelo into a virtual environment, then scaffold the editor config for Cursor, Claude Code, or both.

Prerequisites

  • Python 3.10+ (hard floor — set by the MCP SDK and the scientific stack).
  • Git (the system Git CLI is assumed available alongside Dulwich).
  • Cursor IDE or Claude Code (MCP servers run over stdio in either).
  • Node.js 18+ (optional) — only for the dashboard's chat sidecar.

Quick start

# 1. Create and activate a virtualenv
python3 -m venv .venv
source .venv/bin/activate            # macOS / Linux
# .venv\Scripts\Activate.ps1         # Windows (PowerShell)

# 2. Install Angelo and scaffold the editor config
pip install git+https://github.com/natashahirt/angelo
cd /path/to/your-project
angelo init                          # asks: Cursor, Claude Code, or both

A virtualenv isn't just tidy — modern Linux and macOS refuse a bare pip install into the system interpreter (PEP 668). The venv you install into is also the environment the MCP servers launch from, so keep it around.

Verify any time with:

angelo doctor                        # add --fix to repair mcp.json paths

doctor checks that the angelo-* console scripts are on PATH, dependencies import, the editor config is present and current, and Python is ≥ 3.10.

Choosing an editor

angelo init prompts for the editor layer when you don't pass a flag. You can pin it explicitly, or install both side by side:

angelo init --cursor                 # Cursor only  -> .cursor/mcp.json
angelo init --claude                 # Claude Code  -> .mcp.json + .claude/
angelo init --cursor --claude        # both layers

Both layers can coexist in one repo. For the Claude Code specifics — what gets written, the CLAUDE.md imports, and the session hooks — see Use Angelo in Claude Code.

Adding the zettelkasten

The zettelkasten (and the stream ingestion package it enables) is an optional extra. Install it and re-init with the flag:

pip install "angelo[zettelkasten] @ git+https://github.com/natashahirt/angelo"
angelo init --with-zettelkasten

This adds the angelo-zettelkasten MCP server, the zettelkasten agent rules, and the zettelkasten-extractor agent to agents.yaml.

Optional extras

Angelo's heavier capabilities are opt-in extras, so a base install stays lean:

Extra Adds Docs
zettelkasten Multi-source literature-review graph + stream Zettelkasten
dashboard Web UI for the memory tree, sessions, and chat Dashboard
artifacts DVC/S3 artifact backups, manifests, cloud reruns Experiments
stream Provider SDKs (Anthropic, OpenAI) for headless ingestion Stream

Combine them in one install, e.g.:

pip install "angelo[zettelkasten,dashboard] @ git+https://github.com/natashahirt/angelo"

Shared vs. machine-specific paths

By default init writes portable console-script names (angelo-coordinator, …) into the MCP config, so the committed config works for teammates who run their own angelo init. If your editor can't see the venv's PATH, pin absolute paths for your machine only:

angelo init --local-paths            # or: angelo doctor --fix

Don't commit --local-paths output to a shared repo — those paths are machine-specific. Teammates regenerate their own.

First run

  1. Open the project in your editor. The MCP servers start automatically — check Settings → MCP (Cursor) for green indicators, or approve the servers when Claude Code prompts.
  2. In your first chat, ask the agent to onboard the project — it bootstraps the research tree in .memory/.
  3. Commit the editor config (.cursor/ and/or .claude/ + .mcp.json + CLAUDE.md) and .memory/ — .memory/ is the source of truth for the knowledge graph and persists across machines.

If the servers don't start, the usual cause is the editor's PATH not seeing your venv — run angelo doctor --fix. See Troubleshooting.

New to angelo? Follow the getting-started tutorial next.

Semantically related entries from the memory graph.