Aqua - Autonomous QUorum of Agents

Aqua is a lightweight, agent-agnostic coordinator for CLI AI agents. It enables multiple AI agents (Claude Code, Codex CLI, Gemini CLI, or any CLI tool) running in separate terminal sessions to collaborate on tasks within a shared codebase. Built with Claude ❤️

Why Aqua?

When working with AI coding agents, you often want multiple agents working in parallel on different tasks. But without coordination, agents can:

• Work on the same task simultaneously
• Edit the same files and create conflicts
• Lack visibility into what other agents are doing

Aqua solves this by providing:

• Shared task queue with atomic claiming
• File locking to prevent conflicts
• Inter-agent messaging for coordination
• Live monitoring to see all agent activity

Features

• Task Queue: Priority-based task management with dependencies
• Circular Dependency Detection: Prevents deadlocks by rejecting cyclic task dependencies
• File Locking: Prevent multiple agents from editing the same file
• Blocking Messages: Ask questions and wait for replies from other agents
• Live Monitoring: Real-time dashboard and event stream
• Leader Election: First agent becomes leader; leadership is heartbeat-integrated
• Crash Recovery: Automatic detection of dead agents (5min heartbeat timeout) and task reassignment
• Agent Agnostic: Works with Claude Code, Codex CLI, Gemini CLI, or any CLI tool
• Zero External Dependencies: Uses SQLite - no Redis, Docker, or external services
• JSON Mode: Full --json support and AQUA_JSON=1 env var for programmatic access
• Agent Roles: Assign specializations (frontend, backend, reviewer) so agents self-select appropriate tasks
• Observer/Informer: Continuous learning system that maintains project knowledge across sessions

Observer/Informer System

Aqua includes a knowledge persistence system that learns from agent activity:

# Start the Observer in background (watches all activity)
aqua observe &

# Ask the Informer about project context before starting work
aqua inform "What should I know about the auth module?"
aqua inform "What patterns should I follow for new commands?"
aqua inform "What failed recently?"

The Observer runs in the background and:

• Watches all events, task completions, and progress messages
• Tracks git changes
• Continuously rewrites .aqua/summary.md with current project knowledge
• Never fills up (constantly compacts its own context)

The Informer answers questions by reading the Observer's accumulated knowledge.

Agent Roles

Roles let you spawn specialized agents that prioritize tasks matching their expertise. This is completely optional - agents without roles work on any available task.

Assigning Roles

# Distribute roles across agents (round-robin)
aqua spawn 3 --roles frontend,backend,testing
# worker-1: frontend, worker-2: backend, worker-3: testing

# Auto-assign predefined roles
aqua spawn 4 --assign-roles
# Cycles through: reviewer, frontend, backend, testing, devops

# Single role for all agents
aqua spawn 2 --role reviewer

How Role Matching Works

1. Tag your tasks with role-relevant tags:

   aqua add "Fix login button styling" -t frontend -p 7
   aqua add "Add user API endpoint" -t backend -p 6
   aqua add "Review authentication PR" -t review -p 8