Troubleshooting¶

Most problems come down to one of two things: the editor can't see the venv the MCP servers live in, or a running server is holding stale code. Start with angelo doctor — it diagnoses the majority of cases.

`angelo: command not found`¶

The venv isn't active (or isn't on PATH). Activate it, or call the console script by its absolute path:

source .venv/bin/activate            # macOS / Linux
# .venv\Scripts\Activate.ps1         # Windows (PowerShell)

`pip install` is refused (externally-managed environment)¶

Modern Linux/macOS block a bare pip install into the system interpreter (PEP 668). Always install into a virtualenv — see Install. Don't reach for --break-system-packages.

MCP servers won't start¶

Cursor and Claude Code launch the servers with their own PATH. If the angelo-* console scripts live in a venv the editor can't see, the servers never start.

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

doctor checks that commands are on PATH, dependencies import, the editor config is present and current, and Python is ≥ 3.10. It prints the absolute paths to drop into mcp.json when the venv isn't visible — or --fix writes them for you (this is the machine-specific --local-paths layout; don't commit it to a shared repo).

New or changed MCP tools don't appear¶

A running MCP server holds its code — and its tool list — in memory. After editing server code or upgrading, restart the affected server in Settings → MCP (Cursor) or reopen the project (Claude Code). New tools also require the editor to re-discover the tool list, which the restart triggers.

Stale code after editing a server (dev)¶

Even with an editable install, the running process holds the old code. Restart the server as above. If changes still don't take effect, confirm the install is editable and resolves to the workspace — see .cursor/rules/dev-environment.mdc.

Stale memory data after a `git pull`¶

The memory server auto-syncs .memory/ before every tool call, so a pull or external edit is picked up on the next call — there is no sync() MCP tool to run by hand. To confirm state, call health(); it reports cache freshness, entry/skill/session counts, unpushed commits, and install info. If something still looks off, run angelo doctor and restart the memory server.

The zettelkasten server is missing¶

The zettelkasten is an optional extra. If its server or tools aren't present, install the extra and re-init:

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

angelo update reconciles a newer package's servers (e.g. memory-artifacts) into an existing config non-destructively — run it after upgrading.

The dashboard won't launch¶

The dashboard is the [dashboard] extra and its chat sidecar needs Node.js 18+. Install both, then relaunch:

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

See Use the dashboard.

A coordinator run is stuck or "stale"¶

A run goes stale when its chat/process ends or it records no activity for the abandon window. It isn't lost — resume or clear it:

Resume into the current process: manage_runs(action="resume", run_id=…) — done tasks keep their results; tasks that were mid-flight reset to pending.
Clear runs you won't resume: manage_runs(action="cleanup", …).

Nothing helps — force a clean restart¶

Kill every angelo process (and descendants), then reopen the editor so the servers relaunch:

angelo kill              # add --dry-run to preview

Then restart the MCP servers in your editor. If the problem persists, angelo doctor output is the best thing to include in a bug report.

Semantically related entries from the memory graph.