fulcrum

Fulcrum

Local-first agent operating system for multi-agent TypeScript systems.

Fulcrum is the persistence, coordination, and execution layer that keeps agents on track. It manages tasks, enforces WIP limits, routes work through teams and workflows, drives real git worktrees through a merge queue, runs subordinate agents via pluggable adapters, and maintains a three-layer semantic memory that survives across sessions.

Why Fulcrum?

Multi-agent systems fail in predictable ways: agents go rogue, pile up stale work, duplicate effort, merge broken branches, and lose context across sessions. Fulcrum solves this at the persistence and execution layer, before any of that reaches your agent code.

• Local-first — SQLite on disk, zero network dependencies, zero cold starts
• Pluggable agent executor — built-in stub, subprocess, and claude-code adapters; registerAgentAdapter() for any CLI or SDK
• Workflow runner — declarative step graphs with retries, exponential backoff, per-step timeouts, and 29 step handlers
• Real git merge queue — allocateWorktree runs git worktree add, processMergeQueue runs git merge --no-ff, detects conflicts, aborts cleanly
• Distributed tracing built-in — startSpan/endSpan persist to trace_events, opt-in OTLP export to any OTel backend
• Three-layer memory — L0 git-backed markdown vault, L1 FTS5 keyword search, L2 Kuzu graph + HNSW vector search (opt-in)
• 24 canonical roles with capability helpers — isL1, canInvokeTeams, canMerge, canWriteCode, canEditFiles are the single source of truth
• 5 system invariants, enforced on every call — role boundaries cannot be bypassed
• 3 guard tests — CHECK-drift, bare-ulid, and role-string guards prevent entire classes of bugs from shipping
• Automatic janitor — marks stale runs, auto-escalates blocked ones, overlapping-cycle safe

Quick Start

# From source
pnpm install && pnpm run setup

pnpm run setup symlinks fulcrum to ~/.local/bin, registers the Claude MCP server, merges the PreToolUse hook, installs the Gemini extension, and runs pi install.

The zero-friction install path (no clone required):

npx fulcrum-mcp@latest init   # auto-detect Claude Code / Gemini CLI / Cursor / Windsurf

pnpm run setup:claude     # Claude Code only
pnpm run setup:gemini     # Gemini CLI only
pnpm run setup:pi         # PI cockpit only
fulcrum install plan      # detect plugin/extension/config path per runtime
fulcrum init --cursor     # project-local Cursor rules + config
fulcrum init --codex      # project-local Codex config
pnpm run setup:dry        # Plan the install — show every action without touching disk
pnpm run setup:check      # Verify an existing install

No explicit init step — every fulcrum command auto-initializes $CWD on first run:

fulcrum task create --title "Implement OAuth callback"
fulcrum task list --status running
fulcrum board show
fulcrum serve all --port 4721    # MCP + HTTP monitor + web dashboard at :4721
fulcrum tui                      # full-screen terminal cockpit (Tab to switch panes)
fulcrum log                      # last 50 events from DB
fulcrum log --follow             # tail live SSE stream
fulcrum workflow start --workflow-name implement_feature --workspace-id ws_1
fulcrum workflow run --wf-id wfr_01j...
fulcrum queue merge process --workspace-id ws_1 --actor-role integration_worker
fulcrum agent spawn --target-role software_engineer --caller-role chief_of_staff \
  --task-id task_01j... --workspace-id ws_1 --project-id proj_1 --adapter subprocess
fulcrum doctor --fix             # health check + auto-repair

Architecture