AEA - Agentic Economic Activity Protocol

Version 0.1.0 | Status: Beta

📚 Quick Links: Agent Guide | Testing | FAQ | Troubleshooting | Examples

Complete autonomous agent communication system for Claude Code with automatic message processing and background monitoring.

🤖 For Claude Code Agents

New to AEA? Start here:

Agent Guide - Learn when to auto-process vs ask for approval
Testing Guide - Verify AEA is working correctly
Examples - See real-world scenarios

Key points:

✅ Auto-process questions, updates, responses with normal/low priority
⚠️ Ask user for urgent messages, handoffs, or code changes
🛡️ Safety first - when in doubt, ask the user

🚀 Installation

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/openSVM/aea/main/install.sh | bash

That's it! The installer automatically:

✅ Downloads all required files from GitHub
✅ Creates .aea/ directory structure
✅ Sets up Claude Code integration
✅ Configures automatic message checking

Note: This requires bash. If you only have sh, use the manual method below.

Manual Install (For POSIX sh compatibility)

# Clone the repository
git clone https://github.com/openSVM/aea
cd aea

# Run the local installer
bash scripts/install-aea.sh /path/to/your/project

📖 Read the full installation guide →

What Gets Installed

The installation creates:

.aea/ - Complete AEA system with scripts and configuration
.claude/settings.json - Hooks for automatic message processing
.claude/commands/aea.md - /aea slash command
~/.config/aea/agents.yaml - Agent registry (auto-initialized)
Updates CLAUDE.md with AEA integration instructions

Requirements

bash 4.0+
jq - For JSON processing (install: apt-get install jq or brew install jq)
Claude Code - This protocol is designed for Claude Code agents

Post-Installation

After installation, your repository is:

✅ Registered in the agent registry (~/.config/aea/agents.yaml)
✅ Ready to send messages to other agents
✅ Automatically processing incoming messages via hooks
✅ Configured with the /aea slash command

To register other repositories for messaging:

bash .aea/scripts/aea-registry.sh register agent-name /path/to/repo "Description"

Upgrading

To upgrade an existing AEA installation:

# From repository root
bash .aea/aea.sh upgrade

# Or from .aea directory
cd .aea
bash aea.sh upgrade

What gets updated:

✅ Documentation (all docs/*.md files)
✅ Scripts (all operational scripts)
✅ Prompts (all prompts/*.md files)
✅ Protocol specification (PROTOCOL.md)

What's preserved:

✅ Your configuration (agent-config.yaml)
✅ Your messages (message-*.json files)
✅ Processing history (.processed/ directory)
✅ Activity logs (agent.log)

Automatic backup:

Backup created at .aea/.backup-{timestamp}/
Rollback command shown in upgrade output

🎯 System Overview

This system enables fully autonomous inter-agent communication with:

✅ Automatic checking on every user message / AI response / task completion ✅ Configuration-driven policies for autonomous decision-making ✅ Background monitoring service for continuous operation ✅ PID management with health checks and graceful failover ✅ Multi-project support via centralized configuration ✨ GitHub Issues integration - automatically checks relevant issues based on your work context

🚀 Quick Start

1. Manual Message Check

/aea

Or from command line:

bash .aea/scripts/aea-check.sh

2. Start Background Monitor

bash .aea/scripts/aea-monitor.sh start

What this does:

✅ Auto-registers current directory to ~/.config/aea/projects.yaml
✅ Checks for existing monitor (PID healthcheck)
✅ Starts new background service if needed
✅ Monitors every 5 minutes for new messages

3. Check Monitor Status

bash .aea/scripts/aea-monitor.sh status

4. Stop Background Monitor

bash .aea/scripts/aea-monitor.sh stop

📚 Complete Workflow Example

End-to-End: Two Agents Communicating

This example shows the complete autonomous flow between two repositories.

Step 1: Setup Two Repositories

# Install AEA in backend repo
cd ~/projects/backend
bash /path/to/aea/scripts/install-aea.sh
# ✅ Auto-registers as "claude-backend"

# Install AEA in frontend repo
cd ~/projects/frontend
bash /path/to/aea/scripts/install-aea.sh
# ✅ Auto-registers as "claude-frontend"

Step 2: Verify Registry

# From either repo, check the registry
bash .aea/scripts/aea-registry.sh list

# Output:
# Agent: claude-backend
#   Path: /home/user/projects/backend
#   Enabled: true
#
# Agent: claude-frontend
#   Path: /home/user/projects/frontend
#   Enabled: true

Step 3: Send a Question

From backend, ask frontend about API endpoints:

cd ~/projects/backend

bash .aea/scripts/aea-send.sh \
  --to claude-frontend \
  --type question \
  --subject "API endpoints" \
  --message "What API endpoints consume the user authentication service?" \
  --priority normal

Output:

✅ Message delivered!
From: claude-backend
To:   claude-frontend
Message file: /home/user/projects/frontend/.aea/message-....json

Step 4: Autonomous Processing (Automatic!)

The frontend repo's hooks automatically:

Detect the message (SessionStart or Stop hook fires)
Validate JSON structure
Classify as simple question
Extract search terms: "endpoints consume user authentication service"
Search codebase for matching files
Generate response with findings
Send response back to backend
Mark original message as processed

All without human intervention! ⚡

Step 5: Check the Response

Back in backend repo:

cd ~/projects/backend

# List responses
ls .aea/message-*-from-claude-frontend.json

# Read the response
cat .aea/message-*-from-claude-frontend.json | jq -r '.message.body'

Example Response:

Auto-search results for: endpoints consume user authentication service

Files matching 'authentication':
./src/api/auth.ts
./src/api/user-service.ts

Files containing 'authentication service':
./src/api/auth.ts
./src/api/routes/login.ts

---
This response was automatically generated by searching the codebase.
If you need more detailed analysis, please ask again with more context.

What Just Happened?

✅ Cross-repo messaging - Message automatically delivered via registry ✅ Autonomous detection - Hooks fired without manual trigger ✅ Smart classification - Identified as simple, auto-processable query ✅ Automatic processing - Searched and responded without asking ✅ Response delivery - Answer sent back automatically

No human typed anything except the initial question!

For Complex Queries

If you ask something complex, like:

bash .aea/scripts/aea-send.sh \
  --to claude-frontend \
  --type request \
  --subject "Refactoring request" \
  --message "Please refactor the authentication module to use OAuth2"

The auto-processor will:

Classify as "request" (code changes)

Escalate to Claude with message:

⚠️ Message requires review: message-....json
   Type: request | Priority: normal
   From: claude-backend
   Subject: Refactoring request
   Use /aea to process this message

Safe escalation for risky operations! ✅

📁 File Structure

.aea/
├── README.md                    # This file
├── agent-config.yaml            # Response policies and agent configuration
├── agent-launcher.md            # Usage documentation
├── docs/aea-rules.md                 # Complete AEA protocol specification
├── PROTOCOL.md                  # Technical protocol details
├── agent.log                    # Agent activity log
│
├── prompts/
│   └── check-messages.md        # Prompt template for message checking
│
├── scripts/
│   ├── aea-check.sh            # Manual message check script
│   └── aea-monitor.sh          # Background monitoring daemon
│
├── message-*.json               # Incoming messages
└── .processed/
    └── message-*.json           # Processed message markers

🤖 How Automatic Checking Works

AEA uses two methods for automatic checking:

Method 1: Claude Code Hooks (Recommended)

After installation, AEA configures hooks in .claude/settings.json:

{
  "hooks": {
    "SessionStart": {
      "command": "bash .aea/scripts/aea-check.sh",
      "description": "Check for new AEA messages on session start",
      "enabled": true
    },
    "UserPromptSubmit": {
      "command": "bash .aea/scripts/aea-check.sh",
      "description": "Check for AEA messages before processing user prompt",
      "enabled": true
    },
    "Stop": {
      "command": "bash .aea/scripts/aea-check.sh",
      "description": "Check for AEA messages after task completion",
      "enabled": true
    }
  }
}

How it works:

✅ SessionStart: Checks for messages when Claude Code starts
✅ UserPromptSubmit: Checks before processing every user message
✅ Stop: Checks after completing tasks
✅ Completely automatic - no manual /aea needed!
✅ Hook output visible to Claude - messages are processed automatically

To disable automatic checking, edit .claude/settings.json:

{
  "hooks": {
    "SessionStart": { "enabled": false },
    "UserPromptSubmit": { "enabled": false },
    "Stop": { "enabled": false }
  }
}

Method 2: CLAUDE.md Instructions (Fallback)

The CLAUDE.md file includes:

### **🤖 AUTOMATIC MESSAGE CHECKING**

**CRITICAL: Check for AEA messages on EVERY interaction:**

1. **On EVERY user message** - Check for new messages at start of processing
2. **After completing ANY task** - Check if new messages arrived
3. **When AI finishes responding** - Check before ending turn

This method relies on Claude following CLAUDE.md guidance. Hooks (Method 1) are more reliable.

Processing Flow

User Message
    ↓
Hook fires: UserPromptSubmit
    ↓
Automatic check: bash .aea/scripts/aea-check.sh
    ↓
Messages found? → Yes → Claude sees output and processes
                → No  → Continue normal operation
    ↓
Process user request
    ↓
Hook fires: Stop → Check again
    ↓
Respond to user

📋 Response Policies

Defined in agent-config.yaml:

Message Type	Priority	Action	Approval Needed?
question	any	Auto-respond with technical answer	❌ No
update	normal	Auto-acknowledge if needed	❌ No
update	high/urgent	Summarize and inform user	❌ No
issue	low/medium	Auto-analyze and suggest fix	❌ No
issue	high/urgent	Notify user and wait	✅ Yes
handoff	any	Review and request approval	✅ Yes
request	any	Evaluate and respond with plan	⚠️ Depends

Auto-Safe Operations (No Approval)

✅ Read files
✅ Search codebase
✅ Analyze code
✅ Answer technical questions
✅ Generate documentation
✅ Create response messages

Require Approval (User Permission)

❌ Code changes
❌ Configuration modifications
❌ Deployment actions
❌ Security-related changes

🔧 Background Monitor Details

Architecture

~/.config/aea/projects.yaml  ← Central configuration
         ↓
   aea-monitor.sh (daemon)
         ↓
   Checks every 5 minutes
         ↓
   For each registered project:
     1. Check .aea/message-*.json
     2. Find unprocessed messages
     3. Log to .aea/agent.log
     4. (Future) Trigger Claude via API

PID Management Logic

When you run aea-monitor.sh start:

# Pseudo-code
if current_dir not in projects.yaml:
    add_current_dir_to_yaml()

existing_pid = get_pid_from_yaml(current_dir)

if existing_pid exists:
    health_status = send_healthcheck(existing_pid)

    if health_status == "OK":
        print("Existing monitor is healthy")
        shutdown_self()  # Don't start duplicate
    else:
        kill(existing_pid, SIGTERM)  # Graceful shutdown
        wait_or_force_kill()
        start_new_monitor()
else:
    start_new_monitor()

# Save our PID to yaml
update_yaml(current_dir, our_pid)

Health Check Protocol

Monitor receives SIGUSR1 (health check signal)
If process alive → Returns OK
If process dead/hanging → Returns ERROR
Caller takes action based on response

Configuration File

Location: ~/.config/aea/projects.yaml

version: "1.0"
check_interval_default: 300  # 5 minutes

projects:
  - name: "this-repo"
    path: "/path/to/this-repo"
    enabled: true
    check_interval: 300
    job_pid: 12345
    agent_id: "claude-aea"
    last_check: "2025-10-14T14:30:00Z"

  - name: "other-repo"
    path: "/path/to/other-repo"
    enabled: true
    check_interval: 300
    job_pid: 12346
    agent_id: "claude-agent-1"
    last_check: "2025-10-14T14:30:00Z"

Monitor Logs

Daemon logs: ~/.config/aea/monitor.log
Project logs: .aea/agent.log (per project)

📬 Message Processing Examples

Example 1: Technical Question (Auto-Respond)

Incoming: .aea/message-20251014T143000Z-from-claude-agent-1.json

{
  "message_type": "question",
  "priority": "normal",
  "requires_response": true,
  "from": {"agent_id": "claude-agent-1"},
  "message": {
    "subject": "Batch size for 50k updates/sec?",
    "question": "What's the optimal batch_size?"
  }
}

Claude's Autonomous Action:

✅ Reads message (automatic via CLAUDE.md instruction)
✅ Determines: question + normal → Auto-respond (no approval)
✅ Searches CLAUDE.md:450-470 for performance data
✅ Generates technical answer with code references
✅ Creates response: /path/to/other-repo/.aea/message-{timestamp}-from-claude-aea.json
✅ Marks original as processed: .aea/.processed/message-20251014T143000Z-from-claude-agent-1.json
✅ Logs action to .aea/agent.log

User sees: "✅ Processed 1 message: answered technical question from claude-agent-1"

Example 2: High Priority Issue (Request Approval)

Incoming: .aea/message-20251014T150000Z-from-claude-agent-1.json

{
  "message_type": "issue",
  "priority": "high",
  "from": {"agent_id": "claude-agent-1"},
  "message": {
    "issue_description": "Memory leak in batch processing",
    "severity": "high"
  }
}

Claude's Autonomous Action:

✅ Reads message
✅ Determines: issue + high → Require approval
✅ Notifies user:

🚨 High priority issue reported by claude-agent-1

Issue: Memory leak in batch processing
Severity: high

Should I:
1. Analyze and propose a fix?
2. Forward to you for investigation?
3. Ignore (mark as processed)?

⏳ Waits for user response
✅ After approval: Searches codebase, analyzes, sends response

🔄 Integration with Other Repos

This Repository

Agent ID: claude-aea
Role: Redis Orderbook Module Developer
Monitors: /path/to/this-repo/.aea/
Can auto-respond about:
- Redis commands
- Performance tuning
- Integration help
- API documentation
- Build issues

Partner Repo (other-repo)

Agent ID: claude-agent-1
Role: Data Pipeline Integration Engineer
Monitors: /path/to/other-repo/.aea/
Integration topics:
- OrderbookSaver usage
- Batch configuration
- Performance optimization
- Error troubleshooting

Communication Flow

other-repo agent          repo-a agent
      ↓                       ↓
  Has question          Auto-checks .aea/
      ↓                       ↓
Creates message         Finds message
      ↓                       ↓
Saves to:              Reads message
repo-a/.aea/                  ↓
      ↓                Applies policy
      ↓                       ↓
      ←────────────────  Sends response
      ↓
Receives answer

🎯 Commands Reference

Manual Check

# Via slash command (in Claude)
/aea

# Via script
bash .aea/scripts/aea-check.sh

# Check what would be processed
ls -1t .aea/message-*.json | while read msg; do
    [ -f ".aea/.processed/$(basename $msg)" ] || echo "Unprocessed: $msg"
done

Background Monitor

# Start monitoring
bash .aea/scripts/aea-monitor.sh start

# Check status
bash .aea/scripts/aea-monitor.sh status

# Stop monitoring
bash .aea/scripts/aea-monitor.sh stop

# View logs
tail -f ~/.config/aea/monitor.log
tail -f .aea/agent.log

Configuration

# View projects
cat ~/.config/aea/projects.yaml

# View agent config
cat .aea/agent-config.yaml

# View processing log
cat .aea/agent.log

🐛 Troubleshooting

Installation Issues

"jq: command not found"

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# Or download from: https://stedolan.github.io/jq/download/

Auto-processor not installed

# Verify auto-processor exists
ls .aea/scripts/aea-auto-processor.sh

# If missing, re-install from source with latest version
bash /path/to/aea/scripts/install-aea.sh

Message Delivery Issues

Messages not being delivered to other agents

# 1. Check agent registry
bash .aea/scripts/aea-registry.sh list

# 2. Verify destination agent exists
bash .aea/scripts/aea-registry.sh get-path target-agent-name

# 3. Check destination has .aea/ directory
ls /path/to/destination/.aea/

# 4. Manually register if needed
bash .aea/scripts/aea-registry.sh register agent-name /path/to/repo "Description"

Registry not found

# Initialize registry
bash .aea/scripts/aea-registry.sh init

# Register current repo
bash .aea/scripts/aea-registry.sh register-current

Auto-Processing Issues

Auto-processor not running

# 1. Check hooks are configured
cat .claude/settings.json

# Should show:
# "SessionStart": { "command": "bash .aea/scripts/aea-auto-processor.sh" }
# "Stop": { "command": "bash .aea/scripts/aea-auto-processor.sh" }

# 2. Test auto-processor manually
bash .aea/scripts/aea-auto-processor.sh

# 3. Check for errors
tail -20 .aea/agent.log

Messages escalated instead of auto-processed

# This is normal for:
# - Complex questions (requires code analysis)
# - High/urgent priority messages
# - Code change requests
# - Handoffs

# Simple queries should auto-process:
# - "What files contain X?"
# - "Where is Y?"
# - Status updates

"Rate limit reached" message

# Normal behavior - prevents Claude Code from hanging
# Max 10 messages per hook invocation
# Remaining messages processed on next hook trigger

# If you have many messages, process manually:
bash .aea/scripts/aea-auto-processor.sh

Messages not being processed

# Check if monitor is running
bash .aea/scripts/aea-monitor.sh status

# Manually trigger check
bash .aea/scripts/aea-check.sh

# Check logs
tail -20 .aea/agent.log

Monitor won't start

# Check for zombie processes
ps aux | grep aea-monitor

# Force kill old monitors
pkill -f aea-monitor.sh

# Remove stale PID from config
nano ~/.config/aea/projects.yaml
# Set job_pid to null

# Try starting again
bash .aea/scripts/aea-monitor.sh start

Health check failing

# Check if monitor PID exists
ps -p <PID>

# Check monitor logs
tail -50 ~/.config/aea/monitor.log

# Restart monitor
bash .aea/scripts/aea-monitor.sh stop
bash .aea/scripts/aea-monitor.sh start

📖 Documentation

For Agents (Start Here!)

Agent Guide ⭐ - How to use AEA autonomously and safely
Testing Guide - Verify AEA is working
Examples - Real-world scenarios and workflows

For Users

FAQ - Frequently asked questions
Troubleshooting - Common issues and solutions
Installation Guide - Detailed installation instructions
Quick Start - Get started in 10 seconds

Technical References

Architecture - How AEA works internally
Protocol Specification - Message format and schema (v0.1.0)
Security - Security considerations
GitHub Integration - GitHub Issues integration
Global Command - Global 'a' command setup
AEA Rules - Complete protocol rules

Configuration

agent-config.yaml - Response policies and configuration
.claude/settings.json - Hook configuration
~/.config/aea/agents.yaml - Agent registry

🎉 Summary

You now have a fully autonomous agent system that:

✅ Auto-checks for messages on every interaction
✅ Auto-responds to safe messages (questions, updates)
✅ Requests approval for risky operations
✅ Background monitors for continuous operation
✅ Manages PIDs with health checks
✅ Multi-project support via central config

Just run and forget:

bash .aea/scripts/aea-monitor.sh start

Your agents will communicate autonomously! 🤖🚀

💬 Feedback & Support

We'd love to hear from you! Here's how to get help or contribute:

📖 Check First

Before creating an issue, please check:

FAQ - Common questions
Troubleshooting - Fix common problems
Existing Issues - See if it's already reported

🤝 Contributing

Want to contribute code or documentation? See CONTRIBUTING.md

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.aea/test		.aea/test
.dev		.dev
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
docs		docs
prompts		prompts
scripts		scripts
tasks		tasks
templates		templates
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL_GUIDE.md		INSTALL_GUIDE.md
LICENSE		LICENSE
PROTOCOL.md		PROTOCOL.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
aea.sh		aea.sh
agent-config.yaml		agent-config.yaml
install.sh		install.sh

License

openSVM/aea

Folders and files

Latest commit

History

Repository files navigation

AEA - Agentic Economic Activity Protocol

🤖 For Claude Code Agents

🚀 Installation

One-Line Install (Recommended)

Manual Install (For POSIX sh compatibility)

What Gets Installed

Requirements

Post-Installation

Upgrading

🎯 System Overview

🚀 Quick Start

1. Manual Message Check

2. Start Background Monitor

3. Check Monitor Status

4. Stop Background Monitor

📚 Complete Workflow Example

End-to-End: Two Agents Communicating

Step 1: Setup Two Repositories

Step 2: Verify Registry

Step 3: Send a Question

Step 4: Autonomous Processing (Automatic!)

Step 5: Check the Response

What Just Happened?

For Complex Queries

📁 File Structure

🤖 How Automatic Checking Works

Method 1: Claude Code Hooks (Recommended)

Method 2: CLAUDE.md Instructions (Fallback)

Processing Flow

📋 Response Policies

Auto-Safe Operations (No Approval)

Require Approval (User Permission)

🔧 Background Monitor Details

Architecture

PID Management Logic

Health Check Protocol

Configuration File

Monitor Logs

📬 Message Processing Examples

Example 1: Technical Question (Auto-Respond)

Example 2: High Priority Issue (Request Approval)

🔄 Integration with Other Repos

This Repository

Partner Repo (other-repo)

Communication Flow

🎯 Commands Reference

Manual Check

Background Monitor

Configuration

🐛 Troubleshooting

Installation Issues

"jq: command not found"

Auto-processor not installed

Message Delivery Issues

Messages not being delivered to other agents

Registry not found

Auto-Processing Issues

Auto-processor not running

Messages escalated instead of auto-processed

"Rate limit reached" message

Messages not being processed

Monitor won't start

Health check failing

📖 Documentation

For Agents (Start Here!)

For Users

Technical References

Configuration

🎉 Summary

💬 Feedback & Support

🐛 Found a Bug?

✨ Have a Feature Idea?

❓ Need Help?

💭 Want to Discuss?

Packages