convez.ai
AgenteDesenvolvimento WebIntermediário
eugine8248

Crewmap

eugine8248/crewmap

Canvas visual para design e monitoramento de sistemas multi-agente Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Canvas 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/crewmap

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

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)

crewmapEmdash
Primary viewCanvas — spatial graph of your agent systemKanban + tabbed terminals
Agent unit of workA persistent named role you wire to other rolesA run of work, isolated in a git worktree
Edits your agent definitions?Yes — reads + writes session-registry.yaml, surfaces frontmatter, draws edges between skill filesNo — agents are auto-detected and treated as black boxes
Multi-agent topologyFirst-class — PM → specialist → sub-specialist edges, handoff / dispatch / escalation as distinct typesNone — every run is independent
Live monitor of running agentsPer-node pulse ring + activity timeline (metadata only)Terminal tabs
Runtime / executioncrewmap does not run agents. It fires them in your normal terminal.Owns the execution surface (worktrees, providers, PRs)
FootprintTauri 2, ~3 MB Windows installerElectron, ~80-150 MB
Provider scopeClaude Code first-class; framework-agnostic for any file-based agent system27 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

  1. Launch crewmap. The welcome screen appears with a single Choose folder button (and a Recent list once you've opened anything before).
  2. Pick a folder containing your agent stack — anything with a builders/, quality/, research/, specialty/, _routines/, or _meta/ subdirectory and (optionally) a session-registry.yaml. The native folder picker honors your OS conventions.
  3. crewmap scans the tree, classifies every skill.md (and _routines/routine-*.md), and renders the canvas in a few hundred milliseconds.
  4. 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.
  5. Click a PM node → DispatchActions row shows Fire / Pause / Resume / Kill / Reset buttons. Fire opens a new terminal window with claude queued at that PM's project directory.
  6. Watch the pulse rings. While a claude session 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).
  7. Press ? anytime to see the full keyboard-shortcuts list. Press Shift+C to open the in-app concerns viewer for the scanned root.

Features

FeatureShips in
Folder picker, scanner, polymorphic Node/Edge display, three-pane layout, click-node detail, persistent layout, status pills sourced from session-registry.yamlv0.1
File watcher (notify + 200ms debounce) — canvas refreshes on external editsv0.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 indicatorsv0.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 runbookv0.7
Cross-platform Windows MSI / NSIS bundles · 5 production landing screenshots · canvas-core sibling-checkout wired into CI · BUILDS.md runbook · version-string lockstep enforcedv0.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

ActionShortcut
Open folderCmd/Ctrl + O
Refresh / re-scanCmd/Ctrl + R
UndoCmd/Ctrl + Z
RedoCmd/Ctrl + Shift + Z (or Cmd/Ctrl + Y)
Export canvas layout JSON to clipboardCmd/Ctrl + S
Focus filter (sidebar)Cmd/Ctrl + F
Fit to viewCmd/Ctrl + 0
Pan canvasArrow keys
Show this overlay?
View concerns logShift + C (also via toolbar)
Close detail / clear selectionEsc

Recognized file patterns

PathRecognized asRenders as
<root>/builders/<name>-pm/pm/skill.md OR <root>/builders/<name>-pm/skill.mdPMLarge parent node, "builders" frame
<root>/builders/<name>-pm/team/<specialist>/skill.mdSpecialistChild of that PM
Same pattern under quality/, research/, specialty/PM / SpecialistSame with respective category color
<root>/_routines/routine-*.mdRoutineDashed-border node, "routines" frame
<root>/_meta/**/SKILL.mdSpec / metaSmall node, "specs" frame
<root>/session-registry.yamllive-status sourceStatus pills on PM nodes (watched live in v0.2+)
<root>/.agent-context/concerns.mdconcerns logRead by the in-app Concerns view (v0.5+)
~/.claude/projects/<encoded-root>/*.jsonllive-activity sourcePulse ring + activity timeline on PM/specialist nodes (v0.6+, metadata-only)
<pm-root>/escalation.txt or breach-handoff.json non-emptyescalation markerBadge 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 ActivityEntry struct in monitor/mod.rs has exactly six fields: timestamp, tool, subagent_type, skill, is_error, session_id. There is no prompt, text, thinking, content, command, or input field.
  • The scan_session parser deliberately discards message.content[].text, message.content[].thinking, tool_use.input.* beyond literal subagent_type and skill, and tool_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-updater is 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.skill literal + Agent input.subagent_type literal. 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 static NodeStatus pathway (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-only BaseNode / Frame / EdgeWithLabel primitives 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 *.md files 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 in src/lib/shell/*.ts; business code calls shell.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 show to verify)
  • Bun 1.3+ (bun --version) — Bun is required on Windows, where npm install hits 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 install on @crewmap/canvas-core: known Bun + file-link + Windows issue. Workaround: after bun install, manually copy ../canvas-core/dist/ + package.json + README.md into node_modules/@crewmap/canvas-core/. Use bun install not npm install (EPERM trap).
  • cargo tauri dev fails to build: kill any running tsx watch / vite processes (Windows file-locking interaction), then retry.
  • scan_smoke example for quick scanner test:
    cd src-tauri
    cargo run --example scan_smoke -- "C:/Users/eugin/Documents/ClaudeAgent/"
    

Roadmap

VersionThemeStatus
v0.1 – v0.6Build cycles (read-only viewer → drawable edges → dispatch → polish → live monitor)shipped
v0.7 – v0.9Publication-track scaffolding (content → cross-platform bundles → signing infra)shipped
v1.0Feature-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 publishOAuth secret rotation · domain crewmap.dev registration · code-signing cert purchase · GitHub repo push · landing publish · launch postsgated 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 / EdgeWithLabel primitives were extracted from framedeck's canvas into the shared @crewmap/canvas-core package.
  • 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.
Ver o original no GitHub

Bom para

Relacionados