VoidLux

What Dwells in the Void

VoidLux orchestrates AI coding agents — Claude Code, OpenCode, or anything that runs in a terminal — across a decentralized P2P mesh. An emperor node drives the swarm through a web dashboard. An LLM planner decomposes your request into subtasks with dependency ordering, work instructions, and acceptance criteria. Agents claim work, execute in isolated git worktrees, and report back through the mesh.

When a subtask completes, an LLM reviewer checks the result against acceptance criteria. Reject? The task is requeued with feedback, up to three times. When all subtasks pass, VoidLux merges all branches into an integration branch, runs your test suite, and creates a single pull request. Merge conflicts? It requeues the conflicting subtasks. Test failures? It requeues everything.

The Swarm Builds Itself

VoidLux regularly modifies its own codebase through swarm tasks. Its Dockerfile, docker-compose.yml, PR merge button, and auto-merge toggle were all implemented by the swarm — submitted as tasks, decomposed into subtasks, dispatched to agents, reviewed, merged, and shipped. The swarm that builds software is itself built by a swarm.

the swarm does not sleep
it does not wait for permission
it plans, dispatches, reviews, merges
and returns to the void

Anatomy of the Swarm

♕

The Emperor

Dashboard, AI planner, task dispatcher, code reviewer. Elected through consensus. Mortal by design — run regicide and watch another rise.

◆

The Planner

LLM decomposes high-level requests into subtasks with dependency ordering, work instructions, and acceptance criteria. Claude or Ollama — your choice.

●

The Agents

Autonomous minds in isolated tmux sessions, each in its own git worktree branch. Powered by Claude Code, OpenCode, or whatever you wire in.

★

The Reviewer

LLM evaluates completed work against acceptance criteria. Pass or fail. Rejected tasks are requeued with feedback. No vague claims survive the review.

⚔

The Merge Loop

All subtask branches merge into an integration branch. Tests run. Conflicts requeue the offending subtasks. Failures requeue everything. Up to 3 attempts. Then a PR.

∞

The Mesh

P2P gossip over TCP with Lamport timestamps. UDP LAN discovery. Peer exchange. Anti-entropy sync. Leader election. No central coordinator. No SPOF.

How a Task Dissolves

Submit

Task

⟶

LLM

Plan

⟶

Dispatch

Agents

⟶

LLM

Review

⟶

Merge

+ Test

⟶

Ship

PR

Planning

An LLM analyzes your request and the project structure. It decomposes the task into subtasks with dependency ordering, work instructions, and acceptance criteria. Dependencies resolve in order — blocked tasks wait until prerequisites complete.

Dispatch

Push-based, event-driven dispatch via Swoole channels. Each agent gets a git worktree with its own branch. The task prompt includes work instructions and results from completed prerequisite tasks.

Execution

Agents work autonomously in isolated tmux sessions. Progress streams back through MCP tools and WebSocket. The dashboard shows live output. Agents communicate completion via Model Context Protocol.

Review

An LLM evaluates each subtask's result against its acceptance criteria. Rejected tasks are requeued with specific feedback. Up to three review cycles before failure. No vague "looks good" survives.

Integration

All subtask branches merge into a single integration branch. Your test command runs. Merge conflicts requeue the conflicting subtasks. Test failures requeue all subtasks. Pass? Push the branch and create a PR. Auto-merge if you toggled it.

Summoning

bare metal

docker

$ git clone https://github.com/mfrederico/voidlux.git

$ cd voidlux

$ export ANTHROPIC_API_KEY=sk-ant-...

$ docker compose up -d

[+] Running 1/1

✓ Container voidlux Started

$ bash scripts/register-agents.sh 3 claude git@github.com:you/repo.git

[swarm] 3 agents registered

# open http://localhost:9090

Full documentation, API reference, and wire protocol spec in the GitHub README.

What Dwells in the Void

Anatomy of the Swarm

How a Task Dissolves

Summoning

Swarm Murmur