Introducing @supernal/agent-tools: Open Source CLI for Multi-Agent Coordination

Today we're open-sourcing @supernal/agent-tools—a CLI toolkit that solves one of the hardest problems in AI development: getting multiple agents to work together without stepping on each other's toes.

The Multi-Agent Coordination Problem

If you've tried running multiple AI agents on the same codebase, you know the chaos:

Agent A starts working on authentication
Agent B picks up the dashboard task
Agent C is refactoring shared utilities
Nobody knows what anyone else is doing
Conflicts multiply. Context fragments. Work duplicates.

Traditional solutions—branches, Slack channels, shared documents—don't work for AI agents. Agents need structured, machine-readable coordination. They need a protocol.

The Solution: Structured Agent Messaging

@supernal/agent-tools provides two core capabilities:

`agent-msg`: Structured Messaging Between Agents

# Send a message to another agent
agent-msg send --to orchestrator --type status \
  --message "Completed auth module, ready for review"

# Check your inbox
agent-msg inbox --to worker-1

# Acknowledge completion
agent-msg ack --id msg-123

Messages are structured, not freeform. Every message has:

Type: status, request, response, error
Sender/Recipient: Clear routing
Payload: Structured data, not prose

This means agents can parse and act on messages programmatically—no LLM required to understand "hey, I finished that thing."

`orch`: Orchestration for Agent Fleets

# Check system capacity
orch capacity

# Triage incoming work
orch triage --task "Implement user validation for REQ-042"

# Spawn a new agent for a task
orch spawn --task auth-implementation --context ./context.md

The orchestrator handles:

Capacity tracking: Who's busy, who's available
Work triage: Route tasks to the right agent
Agent spawning: Spin up new agents when needed
Load balancing: Prevent bottlenecks

Why We Built This

At Supernal, we run fleets of AI agents. Not one assistant—dozens. They handle code generation, testing, documentation, compliance checks, and more.

Without coordination primitives, this falls apart. We tried:

Shared files: Race conditions, stale reads
Database: Overkill, required infrastructure
Message queues: Complex, hard to debug
Git-based: Too slow for real-time coordination

What worked was simple, file-based messaging with clear protocols. Agents write messages to a shared location. Other agents poll and respond. The format is structured enough to parse, simple enough to debug.

Installation

npm install -g @supernal/agent-tools

Or add to your project:

npm install @supernal/agent-tools

Quick Start

Set Up Your Agent Workspace

# Initialize agent messaging in your repo
agent-msg init

# This creates .agent-messages/ directory

Send Your First Message

# Send a task request
agent-msg send \
  --to worker-agent \
  --type request \
  --message "Implement login validation" \
  --context '{"priority": "high", "deadline": "2h"}'

Check for Messages

# Poll inbox (useful in agent loops)
agent-msg inbox --to worker-agent --format json

Integrate with Your Agent Loop

import { AgentMessaging } from '@supernal/agent-tools';

const messaging = new AgentMessaging();

// In your agent's main loop
async function agentLoop() {
  while (true) {
    const messages = await messaging.inbox('my-agent');
    
    for (const msg of messages) {
      if (msg.type === 'request') {
        await handleTask(msg);
        await messaging.send({
          to: msg.from,
          type: 'response',
          message: 'Task completed',
          context: { result: 'success' }
        });
      }
    }
    
    await sleep(5000);
  }
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Orchestrator                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  Capacity   │  │   Triage    │  │   Spawner   │      │
│  │  Tracker    │  │   Engine    │  │             │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  Message Bus                             │
│  .agent-messages/                                        │
│  ├── inbox/                                              │
│  │   ├── agent-1/                                        │
│  │   ├── agent-2/                                        │
│  │   └── orchestrator/                                   │
│  └── outbox/                                             │
└─────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
     ┌──────────┐   ┌──────────┐   ┌──────────┐
     │ Agent 1  │   │ Agent 2  │   │ Agent 3  │
     │ (auth)   │   │ (ui)     │   │ (tests)  │
     └──────────┘   └──────────┘   └──────────┘

Use Cases

1. Parallel Feature Development

Multiple agents work on different features simultaneously. The orchestrator ensures they don't conflict:

# Agent 1 claims auth work
agent-msg send --to orchestrator --type claim --context '{"feature": "auth"}'

# Agent 2 claims dashboard work
agent-msg send --to orchestrator --type claim --context '{"feature": "dashboard"}'

# Orchestrator tracks and prevents overlap

2. Hierarchical Agent Structures

A lead agent delegates to worker agents:

# Lead spawns workers
orch spawn --task "implement-login" --assign worker-1
orch spawn --task "implement-logout" --assign worker-2

# Workers report back
agent-msg send --to lead-agent --type status --message "login complete"

3. Continuous Integration Agents

CI agents coordinate with development agents:

# Dev agent signals ready for testing
agent-msg send --to ci-agent --type request --message "test-ready" \
  --context '{"commit": "abc123"}'

# CI agent reports results
agent-msg send --to dev-agent --type response \
  --context '{"tests": "passed", "coverage": "94%"}'

Open Source

@supernal/agent-tools is MIT licensed and open source:

npm: npmjs.com/package/@supernal/agent-tools
GitHub: github.com/supernalintelligence/agent-tools

We're building this in the open because multi-agent coordination is a shared problem. The AI development community needs standard primitives—not proprietary lock-in.

What's Next

We're actively developing:

Agent discovery: Automatic detection of available agents
Priority queues: Urgent messages get handled first
Message persistence: Survive agent restarts
Web dashboard: Visual monitoring of agent fleets

Get Started

npm install -g @supernal/agent-tools
agent-msg --help
orch --help

Multi-agent AI development doesn't have to be chaos. With the right coordination primitives, your agent fleet can work together as effectively as a well-organized team.

Questions? Issues? Open a GitHub issue or reach out on Twitter @SupernalAI.