aqua

# Aqua - Autonomous QUorum of Agents

[![PyPI version](https://badge.fury.io/py/aqua-coord.svg)](https://badge.fury.io/py/aqua-coord)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**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 Gemini ❤️

![Aqua in action](https://vignesh07.github.io/aqua/assets/images/aqua-demo.gif)

## 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`