Crewmap
eugine8248/crewmap
Canvas visual para design e monitoramento de sistemas multi-agente Claude Code
Ver no GitHubCanvas visual node-based para projetar, executar e monitorar sistemas de agentes Claude Code locais. Funciona como um 'Figma para diretórios .claude/', permitindo desenhar a topologia multi-agente, editar definições de agentes e observar execução em tempo real com pulsos de atividade por nó.
Instalação
npx convez-ai eugine8248/crewmap1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Projetar topologia de agentes PM → especialistas com dispatch/handoff/escalation
- Monitorar execução live de agentes com pulse rings e timeline de atividade
- Editar e gerenciar definições de agentes via interface visual integrada
Veredito

Ferramenta madura (v1.0) e altamente especializada para quem trabalha com arquiteturas multi-agente Claude Code. Desktop app Tauri 2 leve (~3MB) que preenche gap real entre design visual e execução em terminal, complementando bem o Emdash. Aguarda apenas formalidades de domain e certificados antes do lançamento público.
README
A tradução para o português deste README ainda está na fila.
crewmap
Design your Claude Code agent system. Watch it run.
Emdash runs your agents. Crewmap is where you design them — and where you watch them run. They work side-by-side.
crewmap is a Tauri 2 desktop app that reads any .claude/ or builders/quality/research/specialty/ agent directory and renders it as a live node-based canvas. PMs as parent frames, specialists nested inside, dispatch / handoff / escalation as arrows. Fire a PM from the canvas, pause / resume / kill it, and watch each node's pulse ring light up green while its agent is live.
Status: v1.0 — feature-complete, awaiting domain + signing certs before public release.
This is the frozen v1.0 launch build. Reads your agent stack, draws edges between PMs and specialists, lets you fire / pause / resume PMs from the canvas, supports undo / redo / keyboard shortcuts, surfaces concerns logs, and overlays a live monitor on every node by tailing Claude Code's per-session JSONL logs (metadata-only — never prompt or response bodies). The codebase is shipped through to v1.0; the public release is gated only on the three external prerequisites in LAUNCH_CHECKLIST.md.
Why crewmap (not Emdash)
| crewmap | Emdash | |
|---|---|---|
| Primary view | Canvas — spatial graph of your agent system | Kanban + tabbed terminals |
| Agent unit of work | A persistent named role you wire to other roles | A run of work, isolated in a git worktree |
| Edits your agent definitions? | Yes — reads + writes session-registry.yaml, surfaces frontmatter, draws edges between skill files | No — agents are auto-detected and treated as black boxes |
| Multi-agent topology | First-class — PM → specialist → sub-specialist edges, handoff / dispatch / escalation as distinct types | None — every run is independent |
| Live monitor of running agents | Per-node pulse ring + activity timeline (metadata only) | Terminal tabs |
| Runtime / execution | crewmap does not run agents. It fires them in your normal terminal. | Owns the execution surface (worktrees, providers, PRs) |
| Footprint | Tauri 2, ~3 MB Windows installer | Electron, ~80-150 MB |
| Provider scope | Claude Code first-class; framework-agnostic for any file-based agent system | 27 CLI agents auto-detected |
Use both. Author your system in crewmap. Execute runs in Emdash. Crewmap reads ~/.claude/projects/ to show you what's live, regardless of how it was launched.
See landing/comparison.md for the long-form side-by-side.
Install
Note on v1.0 status. The code is feature-complete. Pre-built installers ship from GitHub Releases once the domain is registered and code-signing certs are provisioned — see LAUNCH_CHECKLIST.md for the three external prerequisites. Until then, build from source as documented in BUILDS.md.
Windows
When public release lands, download the MSI installer from GitHub Releases. Until then, build from source:
# Prerequisites: Rust 1.77+, Bun 1.3+, Node 22+
cd ../canvas-core
bun install
bun run build
cd ../crewmap
bun install
bun run tauri:build
# Installer at: src-tauri/target/release/bundle/msi/crewmap_1.0.0_x64_en-US.msi
# Standalone exe at: src-tauri/target/release/crewmap.exe
First-run SmartScreen warning is expected on unsigned self-builds: More info → Run anyway.
macOS
Pre-built .dmg ships from GitHub Releases once the Apple Developer ID cert is provisioned. Build from source on macOS:
# Prerequisites: Rust 1.77+, Bun 1.3+, Node 22+, Xcode Command Line Tools
xcode-select --install
rustup target add aarch64-apple-darwin x86_64-apple-darwin
cd ../canvas-core && bun install && bun run build
cd ../crewmap && bun install
bun tauri build --target universal-apple-darwin --bundles dmg,app
First-run Gatekeeper block is expected on unsigned self-builds: xattr -d com.apple.quarantine /Applications/crewmap.app.
Linux
Pre-built .AppImage + .deb ship from GitHub Releases at v1.0+. Build from source on Linux:
sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf build-essential libxdo-dev libssl-dev
cd ../canvas-core && bun install && bun run build
cd ../crewmap && bun install
bun tauri build --bundles appimage,deb
Full per-platform build runbook: BUILDS.md.
Quickstart
- Launch crewmap. The welcome screen appears with a single Choose folder button (and a Recent list once you've opened anything before).
- Pick a folder containing your agent stack — anything with a
builders/,quality/,research/,specialty/,_routines/, or_meta/subdirectory and (optionally) asession-registry.yaml. The native folder picker honors your OS conventions. - crewmap scans the tree, classifies every
skill.md(and_routines/routine-*.md), and renders the canvas in a few hundred milliseconds. - Click a node → DetailPane on the right shows frontmatter + body preview + in/out relations. Buttons open the file in your default editor or reveal it in File Explorer / Finder / your file manager.
- Click a PM node → DispatchActions row shows Fire / Pause / Resume / Kill / Reset buttons. Fire opens a new terminal window with
claudequeued at that PM's project directory. - Watch the pulse rings. While a
claudesession is running for a node, the outer pulse ring lights up (green = activity in the last 30s; yellow = activity in the last 5 min; red = error; gray = no matching activity). - Press
?anytime to see the full keyboard-shortcuts list. Press Shift+C to open the in-app concerns viewer for the scanned root.
Features
| Feature | Ships in |
|---|---|
Folder picker, scanner, polymorphic Node/Edge display, three-pane layout, click-node detail, persistent layout, status pills sourced from session-registry.yaml | v0.1 |
File watcher (notify + 200ms debounce) — canvas refreshes on external edits | v0.2 |
Drawable edges (handle-drag) + EdgeTypePicker (dispatch / handoff / escalation) + scanner-survives-user-edges (Path A source discriminator) | v0.3 |
| Fire / Pause / Resume / Kill / Reset PMs from the canvas (Path B terminal-spawn dispatch) | v0.4 |
Undo / redo (mod+z / mod+shift+z / 50-op cap) · keyboard shortcuts (mod+o/r/z/y/s/f/0 + bare ?/Shift+C/Esc/Arrow) · ShortcutsHelp ? overlay · Concerns viewer · canvas export to clipboard JSON · toast surface · welcome screen polish · scan-progress / scan-error / watcher-offline indicators | v0.5 |
Live monitor overlay — tails ~/.claude/projects/*.jsonl, drives green / yellow / red / gray pulse rings + ActivityTimeline panel + TopBar live chips. Metadata-only (struct-enforced + cybersec-tested). | v0.6 |
Polished README, framework-free landing scaffolding in landing/, GitHub Actions release workflow (.github/workflows/release.yml), LAUNCH_CHECKLIST.md runbook | v0.7 |
| Cross-platform Windows MSI / NSIS bundles · 5 production landing screenshots · canvas-core sibling-checkout wired into CI · BUILDS.md runbook · version-string lockstep enforced | v0.8 |
| Code-signing infrastructure scaffolded. Tauri.conf + entitlements.plist + scripts/sign-windows.ps1 + scripts/notarize-macos.sh + 2 conditional CI sign steps. All OFF by default (no-op without env vars / secrets); flipping any single env var activates the corresponding path. | v0.9 |
v1.0 lock. All version files at 1.0.0. Final inventory audit (V1_0_REPORT.md). LAUNCH_CHECKLIST pre-flight added. Bundles re-built green at v1.0.0. Feature-complete, awaiting domain + signing certs for public release. | v1.0 |
Keyboard shortcuts
| Action | Shortcut |
|---|---|
| Open folder | Cmd/Ctrl + O |
| Refresh / re-scan | Cmd/Ctrl + R |
| Undo | Cmd/Ctrl + Z |
| Redo | Cmd/Ctrl + Shift + Z (or Cmd/Ctrl + Y) |
| Export canvas layout JSON to clipboard | Cmd/Ctrl + S |
| Focus filter (sidebar) | Cmd/Ctrl + F |
| Fit to view | Cmd/Ctrl + 0 |
| Pan canvas | Arrow keys |
| Show this overlay | ? |
| View concerns log | Shift + C (also via toolbar) |
| Close detail / clear selection | Esc |
Recognized file patterns
| Path | Recognized as | Renders as |
|---|---|---|
<root>/builders/<name>-pm/pm/skill.md OR <root>/builders/<name>-pm/skill.md | PM | Large parent node, "builders" frame |
<root>/builders/<name>-pm/team/<specialist>/skill.md | Specialist | Child of that PM |
Same pattern under quality/, research/, specialty/ | PM / Specialist | Same with respective category color |
<root>/_routines/routine-*.md | Routine | Dashed-border node, "routines" frame |
<root>/_meta/**/SKILL.md | Spec / meta | Small node, "specs" frame |
<root>/session-registry.yaml | live-status source | Status pills on PM nodes (watched live in v0.2+) |
<root>/.agent-context/concerns.md | concerns log | Read by the in-app Concerns view (v0.5+) |
~/.claude/projects/<encoded-root>/*.jsonl | live-activity source | Pulse ring + activity timeline on PM/specialist nodes (v0.6+, metadata-only) |
<pm-root>/escalation.txt or breach-handoff.json non-empty | escalation marker | Badge on the PM node (failed status) |
Files in node_modules/, target/, .git/, dist/, build/, _vendor/, vendor/ are ignored.
Privacy posture (v0.6 live monitor)
The live monitor reads ~/.claude/projects/*.jsonl, which contain your prompts, code being reviewed, secrets you pasted into chats, and assistant thinking blocks. None of that crosses the crewmap IPC boundary. Enforced architecturally:
- The
ActivityEntrystruct inmonitor/mod.rshas exactly six fields:timestamp,tool,subagent_type,skill,is_error,session_id. There is noprompt,text,thinking,content,command, orinputfield. - The
scan_sessionparser deliberately discardsmessage.content[].text,message.content[].thinking,tool_use.input.*beyond literalsubagent_typeandskill, andtool_result.content[]. - A cybersec unit test (
activity_entry_carries_no_body_fields) JSON-serializes an entry and asserts none of the forbidden words appear in the serialization. - An integration test plants forbidden strings in synthetic JSONLs and asserts they never reach the serialized payload.
Adding a body-content field would require modifying the struct definition — a change visible in code review that breaks the cybersec test. Defense in depth.
Known limitations
- No public binaries yet. v1.0 code is feature-complete; releases wait on domain registration + code-signing cert provisioning. See LAUNCH_CHECKLIST.md for the gate.
- Unsigned self-builds. First-run will trigger macOS Gatekeeper / Windows SmartScreen warnings. Code-signing scaffolding (v0.9) is in place ready to activate when certs exist.
- No auto-update.
tauri-plugin-updateris a v1.1+ candidate gated on code-signing being live (no point shipping updates for unsigned binaries). - Live monitor agent-to-node mapping is fuzzy. Matches by Skill
input.skillliteral + Agentinput.subagent_typeliteral. PMs dispatched via prompt body (e.g. "Run the framedeck PM..." in an Agent input.prompt) won't light up — the privacy guard forbids reading prompt bodies. The staticNodeStatuspathway (v0.4) still covers Fire-from-canvas dispatch, so the inner pill still shows running. - Claude Code JSONL schema is not a stable public API. Defensive parsing degrades to all-Gray on schema drift rather than panic. The rest of crewmap stays functional.
- Undo does NOT cover dispatch actions. Fire / Pause / Resume / Kill / Reset write to
session-registry.yaml, which is your actual project state — undoing those would silently rewrite intent. - Reconnect is two-step (create + delete) and not atomic. Idempotent edge id (sha256 of src|tgt|type|'user') self-heals on retry.
- session-registry.yaml writes normalize whitespace + drop comments. Fine for machine-managed registries; UX regression for hand-edited + commented registries.
- Kill writes status='failed' but does NOT terminate the claude-code process. crewmap doesn't own the terminal process; close the terminal window to fully stop.
- Single canvas at a time. Multi-canvas / multi-project tabs are deferred to v1.x.
- Mouse-only edge drawing. Touch + keyboard edge drawing positions the EdgeTypePicker at (0, 0) — fall-back is harmless but ugly. Accessibility pass deferred.
See .agent-context/concerns.md for the full DONE_WITH_CONCERNS log.
Architecture
- Shell: Tauri 2.x (Rust backend + Webview2 / WKWebView / WebKitGTK frontend)
- Frontend: React 18 + TypeScript + Vite + TailwindCSS
- Canvas:
@crewmap/canvas-core— sibling package, geometry-onlyBaseNode/Frame/EdgeWithLabelprimitives over@xyflow/react - Backend: Rust (
src-tauri/) — scanner (walkdir+serde_yaml) + SQLite (rusqlite, bundled) + 25 IPC commands + monitor module (notify + notify-debouncer-mini tailing~/.claude/projects/) - Storage: SQLite at OS app-data-dir (
crewmap.db). The filesystem IS the source of truth; SQLite is a cache + layout-persistence layer. Deleting the DB is non-destructive (next open re-scans). Live-monitor cache is in-memory. - Write surface: crewmap writes ONLY to
<root>/session-registry.yaml(atomic-by-rename) and its own SQLite cache. All*.mdfiles under agents-root are read-only. JSONLs under~/.claude/projects/are read-only (never written, renamed, or deleted).
Full architecture details: see architecture-report.md and ARCHITECTURE.md.
Modular + Portable design
- ONE polymorphic Node table with type discriminator (no parallel pm/specialist/routine tables)
- ONE polymorphic Edge table (no parallel containment/dispatch/escalation tables)
- ONE xyflow node type registered —
<CrewmapBaseNode>wraps per-type content components - Shell-API abstraction — every
@tauri-apps/*import lives insrc/lib/shell/*.ts; business code callsshell.dialog.openFolder(),shell.nodes.list(),shell.monitor.start(), etc. - ONE signing scaffold per OS — Windows signtool + macOS notarytool each have exactly one canonical config slot + one canonical script + one CI conditional step
- Adding a 4th node type requires editing ≤ 3 files (Zod enum + new XContent.tsx + one branch in CrewmapBaseNode.tsx)
- Adding a 5th monitor state (e.g. "throttled") requires editing exactly 3 files (Rust enum + Zod schema + StatusPill ring-class lookup)
Develop
Requires:
- Rust 1.77+ (
rustup showto verify) - Bun 1.3+ (
bun --version) — Bun is required on Windows, wherenpm installhits EPERM file-locking - Node 22+ (for compatible Tauri CLI runtime)
# 1. Build the sibling canvas-core package (one-time)
cd ../canvas-core
bun install
bun run build
# 2. Crewmap
cd ../crewmap
bun install
# 3a. Dev — runs Vite at :1430 + Tauri shell
bun run tauri:dev
# 3b. Or just the renderer in a browser (no Tauri commands work):
bun run dev
# 4. Production bundle (.msi/.exe on Windows, .dmg on macOS, .AppImage on Linux)
bun run tauri:build
See BUILDS.md for the per-platform build runbook (including signing + notarization provisioning once certs are purchased).
Troubleshooting
- Windows EPERM during
bun installon@crewmap/canvas-core: known Bun + file-link + Windows issue. Workaround: afterbun install, manually copy../canvas-core/dist/+package.json+README.mdintonode_modules/@crewmap/canvas-core/. Usebun installnotnpm install(EPERM trap). cargo tauri devfails to build: kill any runningtsx watch/viteprocesses (Windows file-locking interaction), then retry.scan_smokeexample for quick scanner test:cd src-tauri cargo run --example scan_smoke -- "C:/Users/eugin/Documents/ClaudeAgent/"
Roadmap
| Version | Theme | Status |
|---|---|---|
| v0.1 – v0.6 | Build cycles (read-only viewer → drawable edges → dispatch → polish → live monitor) | shipped |
| v0.7 – v0.9 | Publication-track scaffolding (content → cross-platform bundles → signing infra) | shipped |
| v1.0 | Feature-lock + final inventory. Version files locked at 1.0.0; bundles re-built green; LAUNCH_CHECKLIST pre-flight added; V1_0_REPORT.md final inventory. | shipped — awaiting publish gates |
| v1.0 publish | OAuth secret rotation · domain crewmap.dev registration · code-signing cert purchase · GitHub repo push · landing publish · launch posts | gated on user trigger |
| v1.1+ | tauri-plugin-updater (depends on signing being live) · multi-canvas tabs · OS notifications · MCP-based dispatch (hard-kill semantics) · native parsing for non-Claude agent formats (AutoGen / CrewAI / AgentScope) | deferred |
The full publish gate is documented in LAUNCH_CHECKLIST.md. The v1.0 final-cycle inventory + bundle audit is in V1_0_REPORT.md.
License
TBD pending v1.0 public release. Currently private during pre-launch development; license decision is part of the publish gate (recommended: MIT, matching the framedeck precedent and the wider OSS-agent-tools convention). See LAUNCH_CHECKLIST.md § Phase 5.
Contributing
Currently private during pre-launch development. The repo goes public on GitHub once the publish gate clears (OAuth secret rotation + domain registration + code-signing decision — see LAUNCH_CHECKLIST.md). Contribution guidelines will be added at that time.
Acknowledgments
- Anthropic — for Claude Code itself and the skill/agent file conventions crewmap reads. The
~/.claude/projects/JSONL log format is the substrate that makes the live-monitor overlay possible without integrating with any runtime API. - framedeck — sibling project from the same author. The original
BaseNode/Frame/EdgeWithLabelprimitives were extracted from framedeck's canvas into the shared@crewmap/canvas-corepackage. - xyflow / React Flow (
@xyflow/react) — the canvas substrate that makes the visual graph practical. - Tauri 2 — the shell framework. ~3 MB Windows installer vs Electron's 80-150 MB is a real moat.
- Emdash (generalaction/emdash, YC W26) — for running agents better than anyone else. crewmap is positioned to complement, not compete with, their execution surface.