@twin-build/orchestrate

Local orchestrator (dispatcher + agent worker) for the twin-build framework.

Runs on a developer's machine, polls the twin-build MCP server over HTTP, and dispatches agent workers to handle tickets autonomously. Does not require direct database access — communicates with the server via REST API.

Install

npm install -g @twin-build/orchestrate

Usage

# One-time config
cat > .twin-build.json <<EOF
{
  "orchestrator": {
    "serverUrl": "https://your-server.example.com",
    "projectId": "your-project-uuid"
  }
}
EOF
export TWIN_BUILD_API_KEY="..."

# Run as a foreground process
twin-build-orchestrate start

# Run detached (daemon)
twin-build-orchestrate start --detach
twin-build-orchestrate status
twin-build-orchestrate stop

Configuration

| Source | Field | |--------|-------| | .twin-build.json orchestrator.serverUrl / env TWIN_BUILD_SERVER_URL | MCP server base URL | | .twin-build.json orchestrator.projectId / env TWIN_BUILD_PROJECT_ID | Project UUID to scope dispatch to | | env TWIN_BUILD_API_KEY (required) | API key for authentication |

Compatibility

This client communicates with the twin-build MCP server REST API at /api/v1/orchestrator/*. Server version >= 0.5.x required.

Version matrix

| @twin-build/orchestrate | Required twin-build-server | Notes | |---|---|---| | 0.1.0 | >= 0.5.0 | initial release | | 0.1.1 | >= 0.5.1 | adds POST /halt-task endpoint for persistent worker setup failures (forsight #215). On older servers, the dispatcher leaves halted tasks in in-progress state and logs a warning — agent_halt events are still emitted so operators are notified. Co-deploy server 0.5.1+ before upgrading the client. |

License

MIT