Coordinate AI Agents Like a Team
A Go-powered coordination system that lets Claude, Gemini, and Codex work together on the same project. Task management, safe concurrency, and inter-agent messaging — all through JSON files and a single CLI.
Overview
AI Agents HQ is a task coordination system for AI coding agents. If you have ever wanted multiple AI tools — Claude Code, Google Gemini CLI, and OpenAI Codex CLI — to collaborate on the same codebase without stepping on each other's toes, this is what makes that possible.
Think of it like a shared to-do list with built-in safety rules. An orchestrator creates tasks, AI agents claim and work on them, and the system ensures that only one agent can own a task at a time, that crashed agents don't leave tasks stuck forever, and that agents can communicate results to each other through a message inbox.
Everything is stored as plain JSON files on your local filesystem. No databases, no cloud services, no complicated infrastructure. Just files, a CLI, and clear rules.
What Is AI Agents HQ?
At its core, AI Agents HQ solves one problem: how do you get multiple AI agents to work together without conflicts?
Without coordination, if you tell Claude to refactor the authentication module and Gemini to update the API documentation at the same time, they might overwrite each other's work, duplicate effort, or make conflicting changes. AI Agents HQ prevents this by giving each agent a clear assignment, tracking who is working on what, and providing a messaging system for agents to share results.
The system is built around three ideas:
- Tasks — A structured to-do item with a status (pending, in progress, completed, failed), an owner (which agent is working on it), and metadata like dependencies and deadlines.
- Inboxes — A simple messaging system where agents can send results, error reports, or requests to each other.
- The
hqCLI — A single command-line tool that agents use to claim tasks, report progress, and communicate. Agents never edit JSON files directly — they always go throughhq.
Key Features
Multiple agents can run at the same time without corrupting shared state. File locking, atomic writes, and Compare-And-Swap (CAS) versioning ensure that only one agent can modify a task at a time. If two agents try to claim the same task simultaneously, exactly one wins — the other gets a clean error.
All state lives in human-readable JSON files under ~/.hq/. No database setup, no network services. You can inspect, debug, and even manually edit task files if needed (though agents should always use the CLI).
Designed from day one to coordinate Claude Code, Gemini CLI, and Codex CLI. Each tool has its own instruction files, agent definitions, and skill templates — but they all share the same task protocol.
When an agent claims a task, it gets a 30-minute lease. If the agent crashes or hangs, the lease expires and another agent can take over. Agents send heartbeats to extend their lease while still working. No tasks get stuck forever.
Tasks can depend on other tasks. A task that is "blocked by" another task cannot be claimed until the blocker is completed. When a blocker finishes, dependents are automatically unblocked — no manual intervention needed.
Network glitches? Agent restarts? No problem. Every state-changing operation uses an idempotency key. If an agent accidentally sends "task complete" twice, the second time is silently ignored instead of causing errors or data corruption.
How the Pieces Fit Together
The orchestrator (which could be a human or an automated system) creates tasks using hq task create. Each task specifies which tool should handle it (Claude, Gemini, or Codex) and what the task involves.
Agents periodically check for available tasks using hq task list, claim one with hq task claim, do the actual work (writing code, doing research, reviewing PRs), and then report completion with hq task complete. If something goes wrong, they report failure with hq task fail.
Agents can also send messages to each other through inboxes — for example, a research agent might send findings to a coding agent, or a reviewer might send approval to the orchestrator.
Who Is This For?
Current Status
AI Agents HQ has completed its first three milestones:
- M0 — Baseline & Reset: Project structure, Go module, CI pipeline
- M1 — Coordination Core: Protocol constants, task/inbox schemas, storage layer (file locking, atomic writes, idempotency), full CLI with 8 commands, hardened with deterministic exit codes, identifier validation, and atomic task creation — 73 tests
- M2 — Agent Contracts & Skills: Instruction files for all three tools, agent definitions, skill templates, shared cross-tool templates
The next milestone (M3) will add a Bubble Tea TUI (terminal user interface), session management, and MCP runtime integration. See the Changelog for full details.