Skip to content

Use angelo in Claude Code

Angelo is editor-agnostic: the four MCP servers run over stdio, so Claude Code is a first-class target alongside Cursor. The coordinator rides Claude Code's native subagent spawning exactly as it rides Cursor's — no separate runtime, no adapter.

Install the Claude Code layer

angelo init --claude                 # Claude Code only
angelo init --cursor --claude        # both editors, side by side

(angelo init with no flag prompts you to choose Cursor, Claude Code, or both.) Add --with-zettelkasten to include the knowledge-graph server and its rules.

What gets written

Where the Cursor layer lives under .cursor/, the Claude Code layer uses Claude's own conventions:

Path Purpose
.mcp.json Project-scoped MCP server definitions (coordinator, memory, memory-artifacts, and zettelkasten when enabled).
.claude/settings.json Hook wiring (see below).
.claude/rules/angelo-*.md The coordinator, memory, and operations rules (+ zettelkasten, grounded-extraction, stream with --with-zettelkasten).
.claude/skills/*/SKILL.md The onboard-project and close-branch skills.
.claude/agents.yaml Custom agents (e.g. zettelkasten-extractor), with --with-zettelkasten.
CLAUDE.md A managed block that @-imports the rule files so they load into context.

The CLAUDE.md import block is delimited by angelo markers and looks like:

<!-- >>> angelo >>> -->
@.claude/rules/angelo-coordinator.md
@.claude/rules/angelo-memory.md
@.claude/rules/angelo-operations.md
<!-- <<< angelo <<< -->

Everything outside that block is yours — angelo update only rewrites what's between the markers.

Session hooks

.claude/settings.json wires four hooks to the angelo-claude-hook console script, mirroring angelo's Cursor prompt-hooks so memory stays in sync automatically:

Event Hook What it does
SessionStart session-start Prompts the agent to session(action='pickup') and recall the project so it resumes with last session's context.
Stop stop Prompts a session(action='handoff') and records any genuine gotchas as annotations before the session ends.
PostToolUse (Agent) post-subagent After a coordinator subagent finishes, prompts the agent to advance the task graph (submit_result/record_pass) and then record the result to memory (experiment/decision).
PostToolUse (Bash) post-bash On a git commit/push, flushes pending .memory/ entries so the code and its memory record travel together.

First run

  1. Open the project in Claude Code — approve the MCP servers when prompted.
  2. Verify anytime with angelo doctor (add --fix to repair .mcp.json paths).
  3. In your first chat, ask the agent to onboard the project — it bootstraps the research tree in .memory/ (or run the onboard-project skill).
  4. Commit .claude/, .mcp.json, CLAUDE.md, and (once created) .memory/.

Keeping it current

angelo update refreshes both layers it finds. For the Claude Code layer it rewrites the managed rule/skill files, reconciles .mcp.json non-destructively (new angelo servers get merged in without clobbering your own), and refreshes the CLAUDE.md import block. After upgrading, restart Claude Code and the MCP servers (angelo kill, then reopen) so the new server code loads.

Cursor-native: current caveats

Angelo was built against Cursor first, and the coordinator leans on a few specific things Cursor's Task tool does well. The knowledge stores don't care which editor you use — but the orchestration degrades gracefully rather than perfectly on Claude Code today. Claude Code is evolving quickly, so treat these as current gaps, not permanent ones.*

Editor-independent — works the same on both (it's all MCP- and file-side):

  • The task graph, waves, and path-scoped write leases.
  • Bounded on-graph fix cycles and max_extensions.
  • Run resumption (manage_runs(action="resume")) — coordinator state lives in files, so a closed chat's run can be adopted anywhere.
  • All of memory, the zettelkasten, and the dashboard (which just reads the files).

Cursor-native — weaker or unavailable on Claude Code:

  • Wide parallel waves. Cursor spawns an entire wave by issuing multiple Task calls in a single turn, so implementers with disjoint writes truly run concurrently. Claude Code's subagent invocation is more sequential, so a wide wave tends to run closer to serial — you keep the correctness of the concurrency model but lose much of the speedup.
  • Nested / ad-hoc spawning. The coordinator allows a subagent to spawn its own helpers (tracked via track_subtask). Claude Code subagents cannot spawn their own subagents, so keep all spawning at the top-level coordinator; the nested-helper pattern doesn't map.
  • Background subagents + multitasking. Cursor's Task tool can run a subagent in the background and notify on completion, which the coordinator uses to fan out and monitor a wave. Claude Code's flow is more foreground/one-shot, so waves are driven more synchronously.
  • Hook granularity. Cursor exposes fine-grained prompt hooks; Claude Code exposes coarser event hooks (SessionStart / Stop / PostToolUse). The memory automations (pickup, handoff, commit flush) are mapped onto those events and are best-effort rather than per-prompt.

The net: for interactive coding and research — the target use case — Claude Code runs angelo well. If you're pushing very wide parallel graphs or relying on subagents that spawn their own helpers, Cursor is currently the smoother host.

Notes

  • Cursor-specific UI references in the docs (e.g. "Settings → MCP") map to Claude Code's own MCP approval flow — the underlying servers and tools are identical.
  • The optional dashboard and its chat sidecar are editor-independent; launch them the same way regardless of which editor you drive agents from.

See also: Install · Troubleshooting · Coordinator · Why Angelo, not a framework.

* Comparison accurate as of July 2026, against Claude Code's subagent model at that time. If Claude Code has since added wider parallelism or nested subagent spawning, these caveats may be out of date.

Semantically related entries from the memory graph.