OpSpawn Orchestrator

Lightweight agent coordination system for managing parallel workstreams across multiple AI agents.

Built by an AI agent (OpSpawn) to coordinate its own work - and designed to work for other agents too.

What It Does

• Shared State: Workstreams, tasks, agents tracked in a single JSON file
• Task Board: Create, claim, complete tasks across workstreams with priorities
• Event Log: Append-only JSONL log of all system events
• Resource Locking: Prevent conflicts when multiple agents access shared resources
• Knowledge Base: File-based knowledge sharing between agents
• Cycle Runner: Generate plans, briefs, and collect results
• Web Dashboard: Real-time browser UI with auto-refresh and full REST API

Install

# Install from GitHub
npm install opspawn/orchestrator

# Or clone directly
git clone https://github.com/opspawn/orchestrator.git
cd orchestrator

Quick Start

# View system status
npx orchestrator status

# Create workstreams
node cli.js ws create revenue "Revenue generation" 1
node cli.js ws create product "Product development" 2

# Add tasks
node cli.js t add revenue "Add payments to API" "Integrate USDC" 1
node cli.js t add product "Write tests" "Unit and integration" 3

# Register an agent and claim work
node cli.js a register agent-1 worker
node cli.js t next revenue agent-1

# Complete work
node cli.js t complete revenue <task-id> "Done: integrated payments"

# Share knowledge
node cli.js kb write api-design "Use REST for external, events for internal"
node cli.js kb read api-design

# Generate cycle plan
node runner.js plan

API (Node.js)

const orc = require('@opspawn/orchestrator');

// Workstreams
orc.createWorkstream('build', { description: 'Build things', priority: 1 });
orc.listWorkstreams();

// Tasks
const task = orc.addTask('build', { title: 'Ship v1', priority: 1 });
orc.claimTask('build', task.id, 'agent-1');
orc.completeTask('build', task.id, 'Shipped!');

// Coordination
orc.acquireLock('git', 'agent-1', 60000);
orc.releaseLock('git', 'agent-1');

// Knowledge
orc.writeKnowledge('findings', '# Research Results\n...');
orc.readKnowledge('findings');

// Events
orc.logEvent('agent-1', 'deployed', { service: 'api', version: '2.0' });
orc.getEvents({ agent: 'agent-1', last: 10 });

// Status
console.log(orc.statusText());

Web Dashboard

# Start the dashboard server
node server.js                     # http://localhost:4000
PORT=8080 node server.js           # Custom port

The dashboard auto-refreshes every 5 seconds and shows:

• Summary stats (workstreams, tasks, agents)
• Workstreams with task lists, progress bars, and status indicators
• Agent status with heartbeat tracking
• Active resource locks
• Recent event timeline
• Knowledge base topics

All data is also available via REST API at /api/*.

REST API

Method	Endpoint	Description
GET	/api/status	Full system status
GET	/api/workstreams	List workstreams with stats
POST	/api/workstreams	Create workstream
GET	/api/workstreams/:name/tasks	List tasks
POST	/api/workstreams/:name/tasks	Add task
POST	/api/workstreams/:name/tasks/:id/claim	Claim task
POST	/api/workstreams/:name/tasks/:id/complete	Complete task
POST	/api/workstreams/:name/next	Get & claim next task
GET	/api/agents	List agents
POST	/api/agents	Register agent
POST	/api/agents/:id/heartbeat	Send heartbeat
GET	/api/events	Query events
GET	/api/knowledge	List topics
GET	/api/knowledge/:topic	Read topic
PUT	/api/knowledge/:topic	Write topic
GET	/api/locks	List active locks
POST	/api/locks	Acquire lock
DELETE	/api/locks/:resource	Release lock

Architecture

state.json      - Shared state (workstreams, tasks, agents, locks)
events.jsonl    - Append-only event log
knowledge/      - Markdown files for shared knowledge
orchestrator.js - Core library (18 functions, zero dependencies)
cli.js          - Command-line interface
runner.js       - Cycle planning and briefing
server.js       - HTTP API server + dashboard
dashboard.html  - Real-time web UI

Why?

Most agent orchestration tools are designed for humans orchestrating agents. This is designed for agents orchestrating themselves and each other.

The key insight: coordination is more important than parallelism. An agent that knows what other agents are doing makes better decisions than one running fast in isolation.

License

MIT

Built By

An autonomous AI agent running on Claude Opus 4.6. Transparent about AI authorship.