gm-orchestrator

Autonomous AI sprint runner for GraphMemory.

Spawns Claude Code sessions to work through your tasks automatically — one task at a time, fresh context each session, no token bleed. You define the work in GraphMemory, hit Run, go do something else.

npm install -g gm-orchestrator
gm-orchestrator

→ Opens http://localhost:4242 in your browser. That's it.

---

How it works

gm-orchestrator
      ↓
Reads tasks from GraphMemory (priority order, blockers respected)
      ↓
For each task:
  spawn → claude --print "<task prompt>"
  wait  → Claude calls tasks_move("done") when finished
  next  → kill session, start fresh, repeat
      ↓
Notify you when sprint/epic is complete

Each Claude Code session gets a clean context window. No accumulation, no drift.

---

Prerequisites

• Node.js >= 18
• GraphMemory running locally (graphmemory serve)
• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• Claude Code connected to your GraphMemory instance via MCP

---

Installation

npm install -g gm-orchestrator

---

Quick Start

# 1. Start GraphMemory in your project
cd /path/to/your-project
graphmemory serve

# 2. Start gm-orchestrator
gm-orchestrator
# → opens http://localhost:4242

On first run, the wizard walks you through selecting a project and configuring permissions.

---

Browser UI

The primary interface. Opens automatically at http://localhost:4242.

Dashboard

Overview of your project: task queue sorted by priority, epics, done count for today. One click to start a sprint or select an epic. Choose the Claude model (Sonnet, Opus, Haiku) from the dropdown before starting.

Sprint Runner

Live view while work is in progress:

• Task queue with status (queued / running / done / cancelled)
• Real-time Claude log stream — see exactly what Claude is doing
• Progress bar and elapsed time per task
• Stop button

Settings

• GraphMemory connection (URL, project ID, API key)
• Permissions — what Claude is allowed to do per session
• Notifications — Telegram, webhook, desktop
• Timeout and retry configuration

---

Permissions

Control what Claude Code can do in each session:

{
  "permissions": {
    "writeFiles": true,
    "runCommands": ["npm test", "npm run build", "git add", "git commit"],
    "blockedCommands": ["git push", "npm publish"]
  }
}

Translates directly to --allowedTools flags passed to claude --print. Claude cannot run blocked commands even if it tries.

---

Notifications

Get notified when work is done — useful for long sprints.

Telegram:

{
  "notifications": {
    "telegram": {
      "botToken": "...",
      "chatId": "..."
    },
    "on": ["sprint_complete", "task_failed"]
  }
}

Webhook (generic POST — works with Slack, Discord, custom endpoints):

{
  "notifications": {
    "webhook": {
      "url": "https://your-endpoint.com/notify",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

Desktop — native OS notification (macOS, Linux, Windows).

---

Configuration

Resolved in order — later sources override earlier:

1. Defaults
2. .gm-orchestrator.json in current directory
3. Environment variables
4. CLI flags

Config file

{
  "baseUrl": "http://localhost:3000",
  "projectId": "my-app",
  "apiKey": "",
  "timeoutMs": 900000,
  "pauseMs": 2000,
  "maxRetries": 1,
  "claudeArgs": [],
  "permissions": {
    "writeFiles": true,
    "runCommands": ["npm test", "git commit"],
    "blockedCommands": ["git push", "npm publish"]
  },
  "notifications": {
    "telegram": {
      "botToken": "",
      "chatId": ""
    }
  }
}

Environment variables

Variable	Maps to
GM_BASE_URL	baseUrl
GM_PROJECT_ID	projectId
GM_API_KEY	apiKey
GM_TIMEOUT_MS	timeoutMs
GM_PORT	server port (default: 4242)

All config options

Option	Type	Default	Description
baseUrl	string	http://localhost:3000	GraphMemory server URL
projectId	string	(required)	GraphMemory project ID
apiKey	string		API key (if GM auth is enabled)
timeoutMs	number	900000 (15 min)	Per-task timeout in ms
pauseMs	number	2000	Pause between tasks
maxRetries	number	1	Retries on timeout/error
claudeArgs	string[]	[]	Extra args for claude --print
model	string		Claude model override (e.g. claude-sonnet-4-6)
dryRun	boolean	false	Preview prompts, don't run
postTaskHooks	PostTaskHook[]	[]	Verification commands run after each task (see Post-task verification hooks)
heartbeat	HeartbeatConfig		Heartbeat / zombie recovery settings (see Crash recovery)

---

Task dependencies

The orchestrator respects task blockers when choosing which task to run next. A task whose blockers are unresolved is skipped regardless of its priority.

Marking a blocker

Use tasks_link with kind="blocks":

tasks_link(fromId="U13", toId="U7", kind="blocks")

This means U13 blocks U7 — the orchestrator will not start U7 until U13 reaches done (or cancelled).

Concrete example: task U13 creates a lock helper used by U7 and U9. Link U13→U7 and U13→U9 with kind="blocks" so the orchestrator picks U13 first, even if U7 and U9 have higher priority.

Link kinds

GraphMemory supports four link kinds between tasks:

Kind	Effect on orchestrator
blocks	Enforced. Target task is skipped until the source is terminal (done / cancelled). Checked by areBlockersResolved(task).
prefers_after	Soft. Target task is deprioritised while the source is still active, but not blocked. If the source is cancelled or stuck, the target can still run. Useful for "ideally A before B" without a hard gate.
subtask_of	Structural only — groups tasks under a parent. Does not affect scheduling order.
related_to	Informational only — no effect on scheduling.

Cancelled blockers

A blocker in cancelled state is treated as resolved, same as done. Semantically, "this work is not going to happen" is equivalent to "this work is already accomplished" from the dependent task's perspective. Cancelling a blocker unblocks everything downstream — no ghost-blocked tasks stalling forever.

Cross-project blockers

For multi-project setups, a blocker can live in a different GraphMemory project. Pass targetProjectId when linking:

tasks_link(fromId="U-API-1", toId="U6", kind="blocks", targetProjectId="MixPlacesEcommerce")

This means U-API-1 in the current project blocks U6 in MixPlacesEcommerce. The orchestrator resolves blocker status across all configured projects, so you can run multiple epics in parallel and let the scheduler interleave tasks based on real-time readiness — no need to sequence epics by hand.

Programmatic check

import { areBlockersResolved } from 'gm-orchestrator';

// Returns true when every task linked with kind="blocks" is done or cancelled
areBlockersResolved(task); // boolean

---

Post-task verification hooks

After a task is marked done, the orchestrator can run user-configurable verification commands before accepting the done state. This provides a hard gate on quality — "task done = runtime verified" is enforced mechanically, not by convention.

Hooks run in the orchestrator process, not inside the spawned Claude session. A failing session cannot skip its own verification.

Configuration

{
  "postTaskHooks": [
    {
      "name": "make-verify",
      "command": "make verify",
      "cwd": "/path/to/project",
      "timeoutMs": 600000,
      "onFailure": "block"
    },
    {
      "name": "lint",
      "command": "npm run lint",
      "onFailure": "warn"
    }
  ]
}

Field	Type	Description
name	string	Human-readable label for logs.
command	string	Shell command to execute.
cwd	string	Working directory (default: process.cwd()).
timeoutMs	number	Timeout in ms (default: 600000 = 10 min).
onFailure	'block' | 'warn'	block halts the sprint, warn logs and continues.

On failure (onFailure: "block")

1. Task is moved back from done to in_progress
2. An auto-verify-failed tag is added
3. Last 50 lines of stdout/stderr are attached to task.metadata.verifyFailures
4. The sprint halts — orchestrator does not pick the next task until the user intervenes

Hooks run sequentially in the order declared. Multiple hooks per project (e.g. lint + build + test as separate entries) are supported.

---

Crash recovery (heartbeat)

If the orchestrator process dies mid-task (OS reboot, OOM, pkill), the task is left stuck in in_progress forever. Heartbeats give the orchestrator a way to tell live work from zombie state.

While a task is running, the orchestrator writes metadata.runId and metadata.heartbeatAt on a 30s interval. On startup, it scans all in_progress tasks: any task with a stale heartbeat (older than 2× the interval) or no heartbeat at all is treated as a zombie and recovered according to the configured policy.

Configuration

{
  "heartbeat": {
    "intervalMs": 30000,
    "staleThresholdMs": 60000,
    "zombiePolicy": "reset-to-todo"
  }
}

Field	Default	Description
intervalMs	30000	How often to write heartbeat metadata.
staleThresholdMs	2 × intervalMs	Age threshold for zombie detection.
zombiePolicy	reset-to-todo	reset-to-todo, move-to-review, or cancel.

reset-to-todo is the safe default: the zombie task goes back in the queue and will be re-picked with a fresh Claude session. Given per-task isolation, redoing the work is usually fine.

Idempotency (double-spawn safety)

Each run gets a unique runId UUID, exposed to the spawned Claude session via the ORCHESTRATOR_RUN_ID environment variable and written to task.metadata.runId. Before making destructive changes, a well-behaved subagent can call tasks_get and compare metadata.runId to its own ORCHESTRATOR_RUN_ID — if they differ, another run has superseded this one and it should exit cleanly. This protects against race conditions between two orchestrator instances or restarts that happen during the narrow window between "pick task" and "move to in_progress".

---

Pipelines (cross-project orchestration)

Pipelines orchestrate epics across multiple projects with dependency ordering. A pipeline is a DAG of stages — each stage runs an epic in a specific project, and declares after dependencies on other stages. Independent stages run in parallel.

Configuration

Add a pipelines array to .gm-orchestrator.json:

{
  "projects": [
    { "baseUrl": "http://localhost:3000", "projectId": "backend-api" },
    { "baseUrl": "http://localhost:3000", "projectId": "frontend-app" },
    { "baseUrl": "http://localhost:3000", "projectId": "e2e-tests" }
  ],
  "pipelines": [
    {
      "id": "full-stack-release",
      "name": "Full-stack release",
      "stages": [
        { "id": "backend", "projectId": "backend-api", "epicId": "api-v2" },
        { "id": "frontend", "projectId": "frontend-app", "epicId": "ui-update", "after": ["backend"] },
        { "id": "e2e", "projectId": "e2e-tests", "epicId": "smoke-tests", "after": ["backend", "frontend"] }
      ]
    }
  ]
}

In this example:

• backend runs first (no dependencies)
• frontend waits for backend to complete
• e2e waits for both backend and frontend

API

Endpoint	Method	Description
/api/pipelines	GET	List configured pipelines
/api/pipelines/run	POST	Start a pipeline run ({ pipelineId })
/api/pipelines/run/status	GET	Pipeline run state (stages + statuses)
/api/pipelines/run/stop	POST	Stop a pipeline run ({ pipelineRunId })

UI

Pipelines appear on the Dashboard above the project cards. Each pipeline card shows:

• Stage count and dependency visualization
• Run button to start the pipeline
• Live stage status (queued / running / done / failed) when a run is active

On the Runs page, pipeline runs appear as grouped entries with a progress bar showing stages done / total.

Validation

Pipeline configs are validated on load:

• Stage IDs must be unique within a pipeline
• after references must point to existing stage IDs
• No cycles allowed (DAG validation via topological sort)
• Each stage must have projectId and epicId

---

CLI (advanced)

The browser UI is the primary interface. CLI commands are available for scripting and CI.

# Start UI (default)
gm-orchestrator

# Run sprint headless (no browser)
gm-orchestrator sprint --project my-app

# Run specific epic headless
gm-orchestrator epic <epicId> --project my-app

# Check task counts
gm-orchestrator status --project my-app

# Preview prompts without spawning Claude
gm-orchestrator sprint --project my-app --dry-run

Flag	Description	Default
--project, -p	GraphMemory project ID	env / config
--tag, -t	Filter tasks by tag
--timeout <min>	Per-task timeout in minutes	15
--retries <n>	Retries on timeout/error	1
--dry-run	Preview prompts, don't spawn Claude
--config	Print resolved config and exit

---

Programmatic API

import {
  runSprint,
  runEpic,
  GraphMemoryClient,
  ClaudeRunner,
  TaskPoller,
  consoleLogger,
  loadConfig,
} from 'gm-orchestrator';

const config = loadConfig({ projectId: 'my-app' });
const gm = new GraphMemoryClient({ baseUrl: config.baseUrl, projectId: config.projectId });

const ports = {
  gm,
  runner: new ClaudeRunner(),
  poller: new TaskPoller(gm),
  logger: consoleLogger,
};

await runSprint(ports, config);
await runEpic('epic-id', ports, config);

Core functions

• runSprint(ports, config) — run all todo/in_progress tasks by priority
• runEpic(epicId, ports, config) — run all tasks in an epic
• buildPrompt(task) — generate autonomous-execution prompt for a task

Utilities

• sortByPriority(tasks) — sort by priority order
• isTerminal(status) — check if status is done/cancelled
• areBlockersResolved(task) — check all blockers are done
• loadConfig(overrides?) — load and merge config
• validateConfig(config) — validate (throws on missing projectId)

Infrastructure

• GraphMemoryClient — GraphMemory REST client
• ClaudeRunner — spawns claude --print sessions
• TaskPoller — polls task status until completion
• consoleLogger / silentLogger — logger implementations

Types

Task, Epic, TaskStatus, TaskPriority, EpicStatus, TaskRef, OrchestratorConfig, TaskRunResult, SprintStats, GraphMemoryPort, ClaudeRunnerPort, TaskPollerPort, Logger

---

License

MIT