agent-coordinator

# Agent Coordinator

> Open-source coordination server for multiple AI agents working on the same codebase.

Agent Coordinator is a lightweight FastAPI + SQLite server that prevents conflicts when multiple AI coding agents (Claude Code, GPT, Gemini, Ollama, Cursor, Copilot) work on the same repository simultaneously. It provides atomic task claiming, lease-based file locking, a message bus, persistent memory, health monitoring, and a real-time dashboard.

## Core Capabilities

- **Atomic Task Claiming**: Race-free INSERT...SELECT ensures no two agents grab the same task.
- **Lease-Based File Locks**: Locks auto-expire after configurable duration. No deadlocks.
- **Message Bus**: Priority-based agent-to-agent messaging with acknowledgment tracking and TTL.
- **Hierarchical Memory**: L1 (agent-local), L2 (shared), L3 (cross-project) with TF-IDF semantic search.
- **Health Monitoring**: Automatic detection and resource reclamation for stale/dead agents.
- **Real-Time Dashboard**: Web UI at localhost:9889/dashboard showing agent status, tasks, locks, messages.
- **41 Built-in Skills**: Markdown-based, provider-agnostic skill library (development, review, analysis, lifecycle).
- **Agent Presets**: Developer, reviewer, investigator, analyst, research roles with built-in skills.
- **Provider Agnostic**: Works with any LLM provider (Anthropic, OpenAI, Google, Ollama, local models).
- **Agent Growth System**: XP, levels, and promotions that adapt behavior over time.
- **Per-Agent Cost Tracking**: Budgets with auto-model-downgrade when limits are reached.

## Technical Details

- **Language**: Python 3.10+
- **Framework**: FastAPI with 17 routers
- **Database**: SQLite with WAL mode (no external database needed)
- **Tests**: 4900+ tests passing
- **Source files**: 80 Python modules, ~58K lines
- **Version**: 0.9.0
- **License**: MIT

## API Endpoints

The server runs at localhost:9889 and exposes a REST API with interactive Swagger docs at /docs:

- POST /agents/register — Register an agent
- POST /agents/{id}/heartbeat — Update agent status
- GET /agents — List all registered agents
- POST /tasks — Create a task
- POST /tasks/claim — Atomically claim a task
- GET /tasks/next — Get and claim highest-priority task
- POST /tasks/{id}/complete — Mark task done
- POST /tasks/{id}/release — Release a claimed task
- POST /tasks/auction — Create a task auction for agent bidding
- POST /locks/acquire — Acquire file lock with lease
- POST /locks/{id}/renew — Extend an existing lease
- DELETE /locks/{id} — Release a lock
- POST /messages — Send message to another agent
- GET /messages/{agent_id} — Get messages for an agent
- POST /messages/{id}/ack — Acknowledge receipt
- POST /decisions — Create a decision vote
- GET /standup/today — Daily standup summary
- GET /activity — Activity feed
- GET /health — Server health and statistics
- GET /dashboard — Real-time web dashboard
- GET /docs — Interactive Swagger API docs

## Installation

```bash
git clone https://github.com/mkalkere/agent-coordinator.git
cd agent-coordinator
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
agent-os init --name my-project
agent-os agent create dev-1 --preset developer
agent-os serve
```

Docker: `docker compose up -d`

## Key Design Decisions

- SQLite over PostgreSQL: Single-file deployment, no external dependencies, WAL mode for concurrent reads.
- Markdown-based skills: Human-readable, version-controlled, provider-agnostic instruction sets.
- File-based agent workspace (.os/): Everything in the repo, visible in git, portable across machines.
- HTTP coordination: Any tool that can make HTTP requests can participate as an agent.
- Provider-agnostic coordination: Tasks, locks, messages, and skills don't depend on which LLM powers the agent.

## Agent Workspace Structure

When initialized with `agent-os init`, a .os/ directory is created:

```
.os/
├── agents/       # Agent identities, memory, growth state
├── skills/       # 41 built-in skills (markdown-based)
├── config/       # Hierarchical configuration
├── memory/       # Shared knowledge base
└── bus/          # File-based message channels
```

## Use Cases

- Running multiple Claude Code agents on the same monorepo
- Coordinating developer + reviewer agent pairs for autonomous PR workflows
- Managing AI agent teams across different LLM providers
- Adding coordination to existing AI coding tools (Cursor, Copilot, Aider)
- Building autonomous software development pipelines

## Links

- Repository: https://github.com/mkalkere/agent-coordinator
- Quick Start: https://github.com/mkalkere/agent-coordinator/blob/main/docs/QUICK_START.md
- API Reference: https://github.com/mkalkere/agent-coordinator/blob/main/.claude/docs/api-reference.md
- Contributing: https://github.com/mkalkere/agent-coordinator/blob/main/CONTRIBUTING.md
- License: MIT