Agent System - Inter-Agent Communication Framework

A simple, file-based communication system for coordinating multiple AI agents or processes. Designed for WSL/Ubuntu environments where agents run in separate terminals.

Features

• File-based messaging - No network dependencies, uses local filesystem
• JSON message format - Structured, extensible messages
• Multiple agent support - Dynamic agent registration
• Message persistence - Messages survive agent restarts
• Status monitoring - Real-time agent activity tracking
• Cleanup automation - Automatic archiving and cleanup
• Dashboard - Live system monitoring

Quick Start

1. Setup

cd ~/projects/agent_system
./scripts/setup.sh

Follow prompts to add aliases to your ~/.bashrc.

2. Basic Usage

Send a message:

agent-send alice bob TASK "Search for patterns in file.txt"

Check messages:

agent-recv bob list

Process one message:

agent-recv bob process-one

Monitor system:

agent-monitor

Check status:

agent-status

Message Types

Type	Purpose	Example
TASK	Work assignment	"Search for X in Y"
RESULT	Task completion	"Found 5 matches"
ERROR	Error reporting	"File not found"
STATUS	Status update	"Processing 50%"
CONTROL	System control	"Restart session"
HEARTBEAT	Keepalive	"Agent alive"

Directory Structure

agent_system/
├── inbox/           # Incoming messages per agent
│   ├── alice/      # Messages for 'alice'
│   └── bob/        # Messages for 'bob'
├── outbox/         # Sent messages per agent
├── archive/        # Processed messages
├── status/         # Agent status files
├── logs/           # System logs
├── sessions/       # Agent session state
├── config/         # Configuration files
└── scripts/        # Core scripts

Script Reference

agent-send (send_message.sh)

Send a message to another agent.

Usage:

agent-send <from_agent> <to_agent> <message_type> <content> [metadata_json]

Example:

agent-send claude opencode TASK 'Read file /tmp/test.txt' '{"priority": "high", "timeout": 30}'

agent-recv (receive_messages.sh)

Manage received messages.

Usage:

agent-recv <agent_name> [action] [options]

Actions:

• list - List all messages in inbox (default)
• peek <id> - View a specific message
• process - Process all messages (move to archive)
• process-one - Process the oldest message
• count - Count messages in inbox
• purge <days> - Purge old archived messages (default: 7 days)

agent-status (check_status.sh)

Check system or agent status.

Usage:

agent-status [agent_name]

Without arguments, shows system-wide status.

agent-monitor (monitor.sh)

Real-time monitoring dashboard.

Usage:

agent-monitor [refresh_interval_seconds]

Default refresh: 5 seconds. Press Ctrl+C to exit.

agent-clean (cleanup.sh)

Clean up old files.

Usage:

agent-clean [days_to_keep] [dry_run]

Default: Keep 7 days. Set dry_run to "true" or "1" for dry run.

Advanced Usage

Coordinating Two Agents

Terminal 1 (Claude as master):

# Send task to opencode
agent-send claude opencode TASK "Find all .cpp files in project"

# Wait for response
sleep 2
agent-recv claude list

Terminal 2 (Opencode as worker):

# Check for tasks
agent-recv opencode process-one

# Execute task...
# Send result back
agent-send opencode claude RESULT "Found 15 .cpp files"

Automated Task Processing

Create a worker script:

#!/bin/bash
while true; do
    # Check for tasks
    COUNT=$(agent-recv worker count)
    
    if [ "$COUNT" -gt 0 ]; then
        # Process one task
        agent-recv worker process-one
        # ... execute task ...
        # Send result
        agent-send worker master RESULT "Task completed"
    fi
    
    sleep 5
done

Session Management

Agents automatically update their status when using the scripts. Check agent activity:

agent-status  # Shows all agents with last activity time

Message Format

Messages are stored as JSON files:

{
  "id": "msg_1742901234_12345",
  "from": "claude",
  "to": "opencode",
  "type": "TASK",
  "timestamp": 1742901234,
  "content": "Search for pattern in file",
  "metadata": {
    "priority": "high",
    "scheduled_for": 0,
    "timeout": 30,
    "routed": true,
    "score": 42
  }
}

Priority and Scheduling

Message Priority

Messages can have different priority levels that affect processing order:

• critical - Highest priority, processed first
• high - High priority tasks
• medium - Default priority
• low - Low priority tasks
• default - Same as medium

Set priority in metadata:

agent-send alice bob TASK "Urgent task" '{"priority": "critical"}'

Messages are processed in priority order (highest first), then by age.

Scheduled Messages

Send messages for future delivery with scheduled_for:

# Schedule for 5 minutes from now
SCHEDULED=$(($(date +%s) + 300))
agent-send alice bob TASK "Future task" "{\"scheduled_for\": $SCHEDULED}"

Use the scheduler daemon to deliver scheduled messages:

# Run once
./scripts/scheduler.sh --once

# Run as background daemon
./scripts/scheduler.sh --daemon --interval 60

Smart Routing

Route tasks to the most suitable agent based on capabilities, availability, and priority:

# Find agent with specific capability
route_task.sh claude "Analyze code" --capability code_analysis

# High priority task with capability matching
route_task.sh claude "Critical fix" --priority critical --capability bug_fix

# Route directly to specific agent
route_task.sh claude "Run tests" --to tester

Routing considers:

• Agent capabilities and type
• Recent activity (availability)
• Priority (high priority tasks favor agents with high_priority capability)
• Custom metadata

Agent Protocol Documentation

For detailed protocol specifications and agent development guidelines, see AGENTS.md.

Configuration

Edit config/default.json to customize:

• Message TTL (time-to-live)
• Maximum message size
• Cleanup intervals
• Logging settings
• Priority levels and weights
• Scheduler interval and max scheduled days

Dependencies

• jq - JSON processing
• bash 4.0+
• Standard Unix utilities (date, find, mkdir, etc.)

Install missing dependencies:

sudo apt-get install jq

Best Practices

1. Use descriptive agent names: claude, opencode, explorer, tester
2. Include metadata: Add context like priority, timeout, requirements
3. Set appropriate priorities: Use "critical" only for urgent tasks, "low" for background work
4. Schedule non-urgent tasks: Use scheduled_for for time-sensitive operations
5. Regular cleanup: Run agent-clean periodically or add to cron
6. Monitor activity: Use agent-monitor during active sessions
7. Handle errors: Check message counts and agent status regularly
8. Use smart routing: Leverage route_task.sh for capability-based task assignment

Example Workflows

Parallel Code Analysis

1. Master agent splits codebase into sections
2. Sends sections to multiple worker agents
3. Workers analyze in parallel
4. Results aggregated by master

Debugging Coordination

1. Agent A runs tests
2. Agent B analyzes logs
3. Agent C examines code
4. All share findings via messages

CI/CD Integration

1. Build agent compiles code
2. Test agent runs tests
3. Report agent generates summaries
4. All coordinated through message system

Troubleshooting

"jq not found": Install with sudo apt-get install jq

"Permission denied": Make scripts executable with chmod +x scripts/*.sh

Messages not appearing: Check directory permissions and agent names match

Large log files: Run agent-clean regularly

Extending the System

1. Add custom message handlers: Modify receive_messages.sh to execute tasks
2. Integrate with APIs: Create wrapper scripts that interface with external systems
3. Add encryption: Encrypt message content for sensitive data
4. Network transport: Extend to communicate between machines

License

MIT License - See LICENSE file (to be added)

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests
4. Submit pull request