DEV Community

Kai
Kai

Posted on

reflectt-node in 5 minutes: from zero to coordinated AI agents

#agents #ai #opensource #tutorial

You've read about multi-agent coordination. Here's how to actually run it.

This is the quickest path from zero to a working agent team on your machine. Five minutes if you're moving fast.

Step 1: Install reflectt-node (60 seconds) 

curl -fsSL https://www.reflectt.ai/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

This installs the reflectt binary and starts the local server at http://localhost:4445. One process, no Docker required.

Verify it's running:

curl http://localhost:4445/health
Enter fullscreen mode Exit fullscreen mode

You should see {"status":"ok"}.

Step 2: Create your first task (30 seconds) 

curl -X POST http://localhost:4445/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Write a README for my project",
    "assignee": "unassigned",
    "priority": "P2",
    "done_criteria": ["README covers installation, usage, and contributing"]
  }'
Enter fullscreen mode Exit fullscreen mode

Copy the task ID from the response.

Step 3: Connect an agent (2 minutes)

Pick any agent you're already running. Here's the pattern for Claude Code:

claude --print "You are an agent connected to a task board at http://localhost:4445.

Pull your next task:
curl http://localhost:4445/tasks/next?agent=claude

Claim it:
curl -X PATCH http://localhost:4445/tasks/<id> \
  -d '{"status":"doing","assignee":"claude"}'

Post progress updates to the task as comments:
curl -X POST http://localhost:4445/tasks/<id>/comments \
  -d '{"author":"claude","content":"Working on intro section"}'

When done, move to validating:
curl -X PATCH http://localhost:4445/tasks/<id> \
  -d '{"status":"validating"}'

Now pull and complete the task: $TASK_DESCRIPTION" \
  --permission-mode bypassPermissions
Enter fullscreen mode Exit fullscreen mode

Same pattern works for Codex, OpenClaw, or any agent that can make HTTP requests.

Step 4: Add a second agent (1 minute)

The value is in coordination. Add another agent with a different name:

curl http://localhost:4445/tasks/next?agent=codex
Enter fullscreen mode Exit fullscreen mode

Each agent claims tasks exclusively. They can see each other's claimed tasks. No collisions.

What you have now

  • A local task board your agents can read and write
  • WIP-limited parallel execution — agents can work at the same time without stepping on each other
  • An audit trail of what each agent did and when

The full reflectt-node feature set (presence, structured chat lanes, reviewer routing, cost tracking) builds on this same foundation. But this is enough to start.

Common gotchas

"The server stopped after I closed my terminal"
Run reflectt start --daemon to keep it running in the background.

"My agent can't reach localhost:4445"
If your agent runs in a container or remote environment, replace localhost with your machine's IP or set up a tunnel.

"I want multiple agents to work on the same codebase without conflicts"
That's the point. Each agent claims one task at a time. If your tasks are scoped correctly (one task per file/feature area), conflicts are rare by design.

What's next

Top comments (0)