Concurrent Agent MCP Server

MCP server for coordinating multiple AI agents working on parallel development tasks. Enables atomic step claiming, dependency management, crash recovery, and cross-project coordination.

Overview

This MCP server provides a SQLite-backed coordination system for multi-agent concurrent development. It solves race conditions in task assignment, tracks agent health, and manages dependencies between work items.

Key Features:

✅ Atomic step claiming (prevents double-assignment)
✅ Dependency tracking (work only when dependencies satisfied)
✅ Heartbeat monitoring (detect crashed agents)
✅ Multi-project coordination (global work queue)
✅ Metrics and analytics (understand patterns)
✅ Transaction safety (SQLite with WAL mode)

Use Cases

1. Git Worktree Coordination

Multiple Claude instances working on different branches simultaneously:

Agent 1 → claim_step() → step1/api-add-endpoints
Agent 2 → claim_step() → step2/db-update-schema
Agent 3 → claim_step() → step3/ui-add-forms

2. Parallel Task Execution

Distribute any parallelizable work across multiple agents:

Agent 1 → Testing module A
Agent 2 → Testing module B
Agent 3 → Documentation updates

3. Crash Recovery

Automatically detect and recover from agent failures:

Agent 1 crashes → heartbeat stops
Monitor detects stale work after 15min
Agent 2 → claim_step() → picks up abandoned work

Architecture

Database: Single SQLite database with WAL mode for concurrent access Location: ~/.claude/agent-coordination.db Transport: stdio (MCP standard) Query Layer: sqlc-generated type-safe Go code

Schema:

projects - Top-level projects
steps - Individual work items
dependencies - Step dependencies
agent_events - Audit trail

Type Safety:

Custom ID types (ProjectID, StepID) prevent mixing IDs
Enum types (StepStatus, ProjectStatus, EventType) catch typos at compile time
sqlc generates type-safe query functions from annotated SQL

Installation

Prerequisites

Go 1.21+
SQLite 3.35+ (for WAL mode)

Build

make build
# Binary: ./bin/hq

Install

make install
# Installs to: /usr/local/bin/hq

MCP Configuration

Add to Claude Code MCP settings:

User scope (recommended - available to all Claude instances):

claude mcp add --scope user --transport stdio hq -- \
  /usr/local/bin/hq

Project scope (project-specific):

claude mcp add --scope project --transport stdio hq -- \
  /usr/local/bin/hq

Configuration File

If using .mcp.json:

{
  "mcpServers": {
    "hq": {
      "command": "/usr/local/bin/hq",
      "args": [],
      "env": {
        "AGENT_DB_PATH": "${HOME}/.claude/agent-coordination.db"
      }
    }
  }
}

MCP Tools

Project Management

`create_project`

Create a new project with steps.

Parameters:

name (string) - Project name
base_commit (string) - Git commit hash
steps (array) - Array of step definitions

Step definition:

step_num (number) - Step number (1, 2, 3...)
branch (string) - Git branch name
scope (string) - Scope (api, ui, db, etc)
depends_on (array) - Array of step numbers this depends on

Example:

{
  "name": "myapp-auth-feature",
  "base_commit": "abc123",
  "steps": [
    {
      "step_num": 1,
      "branch": "step1/auth-add-jwt-utils",
      "scope": "auth",
      "depends_on": []
    },
    {
      "step_num": 2,
      "branch": "step2/auth-add-middleware",
      "scope": "auth",
      "depends_on": [1]
    }
  ]
}

`get_project`

Get project details and all steps.

Parameters:

name (string) - Project name

Returns:

Project info with all steps and their current status

`list_projects`

List all projects.

Parameters:

status (string, optional) - Filter by status (active, completed, aborted)

Returns:

Array of projects with summary info

Step Operations

`claim_step`

Atomically claim the next available step.

Parameters:

project (string) - Project name
agent_id (string) - Agent identifier

Returns:

Step details if claimed, null if no work available

Example:

{
  "project": "myapp-auth-feature",
  "agent_id": "agent-1"
}

Response:

{
  "id": 1,
  "step_num": 1,
  "branch": "step1/auth-add-jwt-utils",
  "scope": "auth",
  "status": "claimed",
  "agent_id": "agent-1",
  "claimed_at": "2026-01-18T10:30:00Z"
}

`start_step`

Mark a claimed step as in progress.

Parameters:

step_id (number) - Step ID
worktree (string, optional) - Worktree path

`heartbeat`

Update step heartbeat (call every 30-60 seconds while working).

Parameters:

step_id (number) - Step ID
agent_id (string) - Agent identifier

`complete_step`

Mark step as completed.

Parameters:

step_id (number) - Step ID
commit_hash (string) - Final git commit hash
files_modified (array) - List of modified file paths
notes (string, optional) - Completion notes

`fail_step`

Mark step as failed.

Parameters:

step_id (number) - Step ID
reason (string) - Failure reason

`get_step`

Get step details.

Parameters:

step_id (number) - Step ID

Coordination

`get_available_steps`

Get all steps available to work on (no incomplete dependencies).

Parameters:

project (string, optional) - Filter by project
scope (string, optional) - Filter by scope

Returns:

Array of available steps across all (or filtered) projects

`detect_stale_work`

Find steps with stale heartbeats (crashed agents).

Parameters:

timeout_minutes (number, default: 15) - Minutes since last heartbeat

Returns:

Array of potentially abandoned steps

`recover_step`

Recover a stale step (reset to not_started).

Parameters:

step_id (number) - Step ID

Analytics

`get_metrics`

Get project and agent metrics.

Parameters:

project (string, optional) - Filter by project
agent_id (string, optional) - Filter by agent

Returns:

Completion times, step counts, scope breakdowns

`get_agent_events`

Get agent activity log.

Parameters:

agent_id (string, optional) - Filter by agent
project (string, optional) - Filter by project
limit (number, default: 100) - Max events to return

Usage Examples

Basic Worktree Workflow

1. Create project:

await mcp.call("create_project", {
  name: "myapp-auth",
  base_commit: "abc123",
  steps: [
    { step_num: 1, branch: "step1/auth-add-jwt-utils", scope: "auth", depends_on: [] },
    { step_num: 2, branch: "step2/auth-add-middleware", scope: "auth", depends_on: [1] },
    { step_num: 3, branch: "step3/api-add-endpoints", scope: "api", depends_on: [1, 2] }
  ]
});

2. Agent claims work:

const step = await mcp.call("claim_step", {
  project: "myapp-auth",
  agent_id: "agent-1"
});
// Returns: { step_num: 1, branch: "step1/auth-add-jwt-utils", ... }

3. Agent starts work:

await mcp.call("start_step", {
  step_id: step.id,
  worktree: "/Users/home/myapp-step1-auth-add-jwt-utils"
});

4. Agent sends heartbeats while working:

// Every 30 seconds
setInterval(() => {
  await mcp.call("heartbeat", {
    step_id: step.id,
    agent_id: "agent-1"
  });
}, 30000);

5. Agent completes work:

await mcp.call("complete_step", {
  step_id: step.id,
  commit_hash: "def456",
  files_modified: ["src/utils/jwt.go", "src/utils/jwt_test.go"],
  notes: "JWT signing and validation complete"
});

6. Next agent claims step 2:

const nextStep = await mcp.call("claim_step", {
  project: "myapp-auth",
  agent_id: "agent-2"
});
// Returns: { step_num: 2, branch: "step2/auth-add-middleware", ... }
// (step 1 dependency satisfied)

Crash Recovery

Monitor for stale work:

const staleSteps = await mcp.call("detect_stale_work", {
  timeout_minutes: 15
});

for (const step of staleSteps) {
  console.log(`Stale: ${step.branch} (agent: ${step.agent_id})`);

  // Recover it
  await mcp.call("recover_step", { step_id: step.id });
}

Cross-Project Work Queue

Get next available work from any project:

const availableSteps = await mcp.call("get_available_steps", {});
// Returns all steps ready to work on across all projects

// Prioritize UI work
const uiWork = await mcp.call("get_available_steps", {
  scope: "ui"
});

Metrics

Project completion time:

const metrics = await mcp.call("get_metrics", {
  project: "myapp-auth"
});
// { total_steps: 5, completed: 3, avg_time_hours: 2.5, ... }

Agent productivity:

const agentMetrics = await mcp.call("get_metrics", {
  agent_id: "agent-1"
});
// { steps_completed: 10, avg_time_hours: 1.8, scopes: {...} }

Development

Run Tests

make test

Run Server (development mode)

make dev
# Runs with verbose logging

Database Management

View database:

sqlite3 ~/.claude/agent-coordination.db

Common queries:

-- Active projects
SELECT * FROM projects WHERE status = 'active';

-- All steps in a project
SELECT * FROM steps WHERE project_id = 1;

-- Available work
SELECT s.* FROM steps s
LEFT JOIN dependencies d ON s.id = d.step_id
LEFT JOIN steps ds ON d.depends_on_step_id = ds.id
WHERE s.status = 'not_started'
AND (ds.status = 'completed' OR ds.id IS NULL);

-- Agent activity
SELECT * FROM agent_events ORDER BY timestamp DESC LIMIT 20;

Reset database:

rm ~/.claude/agent-coordination.db
# Will be recreated on next server start

Troubleshooting

"Database is locked"

Check WAL mode is enabled: PRAGMA journal_mode; should return wal
Increase busy timeout: PRAGMA busy_timeout=5000;
Ensure no long-running transactions

Stale work not detected

Check heartbeat interval (should be 30-60s)
Verify timeout_minutes parameter
Check agent_events table for heartbeat entries

Steps not claiming

Verify dependencies are satisfied
Check step status (should be not_started)
Ensure no other agent claimed it

Performance

Tested with:

1000 concurrent agents
10,000 steps across 100 projects
<10ms average claim_step latency
WAL mode handles concurrent writes gracefully

SQLite limits:

Max concurrent readers: unlimited
Max concurrent writers: 1 (queued via WAL)
Database size: effectively unlimited
Performance: excellent for <1M rows

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
internal		internal
migrations		migrations
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
CONS.md		CONS.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
REVIEW-RESULTS.md		REVIEW-RESULTS.md
SCHEMA.md		SCHEMA.md
START.md		START.md
TEST_RESULTS.md		TEST_RESULTS.md
TODO.md		TODO.md
go.mod		go.mod
go.sum		go.sum
justfile		justfile
main.go		main.go
sqlc.yaml		sqlc.yaml

License

hegner123/hq

Folders and files

Latest commit

History

Repository files navigation

Concurrent Agent MCP Server

Overview

Use Cases

1. Git Worktree Coordination

2. Parallel Task Execution

3. Crash Recovery

Architecture

Installation

Prerequisites

Build

Install

MCP Configuration

Configuration File

MCP Tools

Project Management

create_project

get_project

list_projects

Step Operations

claim_step

start_step

heartbeat

complete_step

fail_step

get_step

Coordination

get_available_steps

detect_stale_work

recover_step

Analytics

get_metrics

get_agent_events

Usage Examples

Basic Worktree Workflow

Crash Recovery

Cross-Project Work Queue

Metrics

Development

Run Tests

Run Server (development mode)

Database Management

Troubleshooting

"Database is locked"

Stale work not detected

Steps not claiming

Performance

License

See Also

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`create_project`

`get_project`

`list_projects`

`claim_step`

`start_step`

`heartbeat`

`complete_step`

`fail_step`

`get_step`

`get_available_steps`

`detect_stale_work`

`recover_step`

`get_metrics`

`get_agent_events`

Packages