Hopper 🦗

Lightweight task pool for multi-agent coordination — MCP server + CLI.

Hopper gives AI agents a shared task queue backed by SQLite. Agents create, claim, update, and resolve tasks through MCP tools, with optimistic locking to handle concurrency.

Features

• 5 MCP tools: task_pool_create, task_pool_list, task_pool_next, task_pool_update, task_pool_resolve
• Priority queue: critical > high > medium > low
• Optimistic concurrency: revision-checked mutations prevent lost updates
• State machine: open → claimed → doing → done/cancelled with strict transition rules
• Dependency tracking: tasks can declare blocked_by and get unblocked notifications on resolve
• Event audit log: every mutation recorded, queryable via CLI tail
• Zero config: single SQLite file, auto-migrated on first run

Quick Start

# Install dependencies
npm install

# Run tests (34 tests)
npm test

# Build
npm run build

# Start MCP server
TASK_POOL_DB=./tasks.db TASK_POOL_AGENT=main node dist/index.js

CLI

# Initialize database
npx tsx src/cli.ts init --db ./tasks.db

# Tail event log
npx tsx src/cli.ts tail --db ./tasks.db --limit 20

MCP Tools

Tool	Description
task_pool_create	Create a task with priority, project, tags, dependencies
task_pool_list	Query tasks with filters (status, project, agent, priority)
task_pool_next	Claim the highest-priority open task
task_pool_update	Update task fields with revision check
task_pool_resolve	Complete or cancel a task, returns unblocked task IDs

Architecture

src/
├── index.ts          # MCP server entry point
├── db.ts             # SQLite database layer (better-sqlite3)
├── types.ts          # TypeScript type definitions
├── state-machine.ts  # State transitions + error codes
├── cli.ts            # CLI (init / tail)
└── tools/
    ├── create.ts     # Create task + auto-create project
    ├── list.ts       # List/filter + summary stats
    ├── next.ts       # Claim next task (priority-ordered)
    ├── update.ts     # Modify task with revision check
    └── resolve.ts    # Resolve task + evidence + unblocked calc

State Machine

open ──→ claimed ──→ doing ──→ done
  │         │          │
  └─────────┴──────────┴──→ cancelled

Environment Variables

Variable	Default	Description
TASK_POOL_DB	~/.openclaw/state/task-pool.db	SQLite database path
TASK_POOL_AGENT	unknown-agent	Agent identity for claims

Roadmap

• Dependency-aware next (skip tasks with unresolved blockers)
• Claim TTL with automatic release
• TaskFlow integration
• Auto-scope (agent sticky to project subtree)

License

MIT