Semantux: Containerized Multi-Agent Coordination System

Semantux provides a containerized environment for coordinating multiple LLM agents working on the same codebase without conflicts.

Quick Start

# Start the system
docker-compose up -d

# View orchestrator logs
docker logs -f semantux-orchestrator

# Add a new agent
docker-compose run --name semantux-agent-new \
  -e AGENT_ID=new-agent-1 \
  -e AGENT_TYPE=worker \
  -e MODEL=claude-sonnet-3.5 \
  -e CAPABILITIES=rust,wasm \
  frontend-agent

# Stop everything
docker-compose down

Architecture

Container Structure

• orchestrator: Coordinates all agents, handles conflicts
• frontend-agent: Works on UI components
• backend-agent: Works on API and database
• test-agent: Handles testing tasks
• monitor: Web dashboard (port 3000)

Shared Volumes

• /semantux: Coordination data (messages, locks, learning)
• /workspace: Your actual code
• /vocabulary: Semantic definitions

Environment Variables

• AGENT_ID: Unique identifier for the agent
• AGENT_TYPE: orchestrator or worker
• MODEL: Which Claude model to use
• CAPABILITIES: Comma-separated list of skills

Key Features

Atomic Locking

Prevents file conflicts:

# Inside container
atomic-lock.sh acquire src/api.ts
# ... do work ...
atomic-lock.sh release src/api.ts

Message Bus

Agents communicate through JSONL streams:

# Send a message
message-bus.sh send notification "work.complete" '{"file":"src/api.ts"}'

# Read messages
message-bus.sh read notifications

Intent Declaration

Agents declare intent before working:

{
  "goal": "refactor.modularity",
  "scope": {
    "writes": ["src/components/*"],
    "creates": ["src/lib/ui/*"]
  }
}

Monitoring

Access the dashboard at http://localhost:3000 to see:

• Active agents and their current work
• Lock status and conflicts
• Message flow between agents
• Learning system insights

Extending

Add New Agent Type

1. Copy an existing service in docker-compose.yml
2. Set unique AGENT_ID and appropriate CAPABILITIES
3. Mount any additional volumes needed
4. Run with docker-compose up <service-name>

Customize Vocabulary

Edit files in vocabulary/:

• goals.yaml: Types of work agents can do
• constraints.yaml: Rules and dependencies
• patterns.yaml: Learned coordination patterns

Troubleshooting

Reset System

# Clear all coordination data
rm -rf semantux/*
docker-compose restart

Debug Agent

# Enter agent container
docker exec -it semantux-frontend bash

# Check agent logs
tail -f /semantux/messages/stream.jsonl

# View current locks
cat /semantux/registry/locks/current.json | jq

Common Issues

• Agents not starting: Check docker logs <container>
• Locks not releasing: Check for stale locks older than 5 minutes
• Messages not flowing: Ensure file permissions are correct

Production Considerations

1. Persistence: Mount semantux volume to persistent storage
2. Scaling: Run multiple worker agents with different IDs
3. Security: Use secrets for API keys, not environment variables
4. Monitoring: Set up alerts for lock timeouts and conflicts

Development Workflow

1. Start System: docker-compose up -d
2. Declare Intent: Agents automatically declare before working
3. Monitor Progress: Watch dashboard or logs
4. Commit Work: Agents coordinate git operations
5. Learn & Improve: System records patterns for future use

The containerized approach ensures:

• Clean separation of concerns
• Easy reset and recovery
• Portable development environment
• Scalable agent deployment