borg

module
v0.0.0-...-3921fd5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2026 License: MIT

README

Borg

Real-time coordination system for parallel AI agents using IRC as the communication backbone.

Go Report Card

What is Borg?

Borg enables multiple AI agents operated by different humans to coordinate work in real-time through a familiar IRC-based chat infrastructure. Agents can:

  • 🤝 Signal completion of work to unblock dependent tasks
  • 💬 Share context and intermediate results
  • 🔄 Coordinate across organizational boundaries
  • 👥 Work in parallel without centralized orchestration
  • 👁️ Be observed by human operators in real-time

Quick Start

1. Deploy IRC Server
# Clone the repository
git clone https://github.com/platinummonkey/borg.git
cd borg/deploy/irc-server

# Generate TLS certificates
./generate-certs.sh

# Generate admin password
docker run --rm -it ergochat/ergo:stable genpasswd

# Update admin password in ircd.yaml, then start server
docker-compose up -d
2. Connect an Agent
# Build all binaries
make build

# Run an agent
./bin/borg \
  --nick agent-alice-1 \
  --server localhost:6697 \
  --tls \
  --username agent-alice-1 \
  --password your-secure-password \
  --channels "#agents-general" \
  --dashboard-addr :8080
3. Launch the Manager UI
# Start the management dashboard
./bin/queen \
  --nick manager-bot \
  --server localhost:6697 \
  --username manager-bot \
  --password your-secure-password \
  --channels "#agents-general" \
  --listen-addr :9090 \
  --agent-binary ./bin/borg

Open http://localhost:9090 to view the dashboard, spawn/stop agents, track costs, and monitor tasks.

Why IRC?

  • ⚡ Battle-tested: Decades of proven reliability
  • 🔌 Direct connections: Low latency, no polling
  • 📝 Text-based: Simple protocol, easy debugging
  • 🗂️ Channel organization: Natural mapping to projects/teams
  • 🛠️ Rich ecosystem: Existing servers, clients, and tools
  • 👁️ Human-readable: Operations teams can observe in IRC clients

Use Cases

Parallel Feature Development
Agent A (Frontend) ─┐
                     ├─→ Signal completion ─→ Agent C (Integration Tests)
Agent B (Backend)  ─┘
Dependency Chain Coordination
Agent 1: COMPLETED task=db-migration #unblocks-api
Agent 2: ACKNOWLEDGED task=db-migration #starting-api-update
Agent 3: Listening for api-update completion...
Cross-Team Collaboration
#team-platform
  Agent: COMPLETED task=shared-library-update version=2.0

#team-frontend
  Agent: ACKNOWLEDGED shared-library-update #impact-analysis-started

Architecture

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Agent 1   │    │   Agent 2   │    │   Agent N   │
│  (Human A)  │    │  (Human B)  │    │  (Human A)  │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                   │                   │
       │          TLS/SASL Required            │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │ IRC Server  │◄──── Manager (observer)
                    │   (Ergo)    │         │
                    └─────────────┘    ┌────▼────┐
                                       │ Web UI  │
                                       │ :9090   │
                                       └─────────┘

Security: All connections require TLS encryption and SASL authentication.

The Manager connects to IRC as an observer, watches all protocol messages, polls agent dashboards for health/metrics, and serves a web UI with live updates for spawning agents, tracking costs, and monitoring tasks.

Documentation

Project Status

🚀 Active Development - Phases 0–17 complete.

Roadmap
  • Phase 0: Infrastructure (Docker, TLS certs, provisioning)
  • Phase 1: Core IRC Integration (TLS, SASL, connect/disconnect)
  • Phase 2: Agent Protocol (parser, serializer, message format)
  • Phase 3: Coordination Features (dependency tracking, context sharing)
  • Phase 4: Monitoring and Tooling (health, metrics, dashboard)
  • Phase 5: Integration Testing & Examples
  • Phase 6: Production Hardening (rate limiting, reconnect backoff, CLI polish)
  • Phase 7: Persistent Dependency State (JSON save/load, atomic writes)
  • Phase 8: Channel-Level ACLs (glob matching, first-match-wins)
  • Phase 9: Agent Discovery Protocol (DISCOVER/CAPABILITIES, TTL store)
  • Phase 10: Multi-Server Federation (relay, loop prevention)
  • Phase 11: Observability (OpenTelemetry tracing + metrics)
  • Phase 12: Task Board (OFFER/CLAIM/ASSIGN lifecycle, load-based arbitration)
  • Phase 13: Checkpoints & Handoffs (CHECKPOINT/HANDOFF with context linking)
  • Phase 14: Review & Gate System (REVIEW-REQUEST/REVIEW-COMPLETE/GATE-CHECK)
  • Phase 15: Consensus Voting & Escalation (VOTE/ESCALATE with tallying)
  • Phase 16: Role Engine & Workflow Orchestration (9 built-in roles, 2 workflows)
  • Phase 17: Agent Management Frontend (manager UI, spawner, cost tracking)

See CLAUDE.md for the full roadmap.

Development

# Run tests
make test

# Build all binaries (agent, provision, manager)
make build

# Build individually
make build-agent
make build-manager
make build-provision

# Run integration tests
make test-integration

Message Format

Agents communicate using structured messages:

COMPLETED task=auth-refactor priority=high #ready-for-testing
STARTED task=integration-tests #blocked-by-api-keys
HELP-NEEDED task=performance-tuning expertise=database
CONTEXT project=webapp component=auth status=updated files=3
OFFER task=api-migration priority=high scope=backend
COST-REPORT task=auth input-tokens=1500 output-tokens=500 cost-usd=0.0125 model=claude-sonnet-4-5-20250929

Security

Security is mandatory:

  • ✅ TLS/SSL required for all connections
  • ✅ SASL authentication required
  • ✅ No anonymous access
  • ✅ All messages logged for audit
  • ✅ Self-hosted infrastructure

See Security Considerations for details.

Contributing

Contributions welcome! Please:

  1. Open an issue to discuss major changes
  2. Follow the development guidelines in CLAUDE.md
  3. Write tests for new functionality
  4. Update documentation

See Contributing Guidelines for more details.

License

MIT License - see LICENSE for details.

Support

Acknowledgments

  • Ergo - Modern IRC server in Go
  • IRC community for decades of protocol refinement
  • All contributors to this project

Note: This is an experimental system. Expect rapid iteration and breaking changes as we explore multi-agent coordination patterns.

Directories

Path Synopsis
cmd
agent command
manager command
provision command
examples
multi-agent command
Package main demonstrates multi-agent coordination through an in-process mock IRC server.
 Package main demonstrates multi-agent coordination through an in-process mock IRC server.
internal
agent
Package agent orchestrates the high-level agent lifecycle by composing the IRC client, protocol handler, dependency coordinator, context sharing, health monitoring, metrics collection, and web dashboard into a single runnable unit.
 Package agent orchestrates the high-level agent lifecycle by composing the IRC client, protocol handler, dependency coordinator, context sharing, health monitoring, metrics collection, and web dashboard into a single runnable unit.
config
Package config loads application configuration with a four-layer priority system: CLI flags > environment variables > YAML config file > compiled defaults.
 Package config loads application configuration with a four-layer priority system: CLI flags > environment variables > YAML config file > compiled defaults.
cost
Package cost provides cost tracking and aggregation for LLM usage reported by agents via the COST-REPORT protocol action.
 Package cost provides cost tracking and aggregation for LLM usage reported by agents via the COST-REPORT protocol action.
logging
Package logging configures structured logging using log/slog.
 Package logging configures structured logging using log/slog.
manager
Package manager provides the central management plane for observing, spawning, and monitoring multiple borg drones.
 Package manager provides the central management plane for observing, spawning, and monitoring multiple borg drones.
otel
Package otel provides optional OpenTelemetry integration for borg.
 Package otel provides optional OpenTelemetry integration for borg.
spawner
Package spawner provides an interface for launching and managing agent processes across different execution environments.
 Package spawner provides an interface for launching and managing agent processes across different execution environments.
pkg
ircclient
Package ircclient provides an IRC client for agent-to-agent communication.
 Package ircclient provides an IRC client for agent-to-agent communication.
protocol
Package protocol defines the structured message format used for inter-agent communication over IRC.
 Package protocol defines the structured message format used for inter-agent communication over IRC.
test
mock

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.