Quickstart

This page walks you through installing AI Agents HQ and running your first task coordination workflow. By the end, you will have created a task, claimed it as an agent, and marked it complete — the same workflow that AI agents use in production.

Installation

Prerequisites

You need two things installed on your machine:

1. Go 1.23 or later — the programming language the project is written in
2. Git — to clone the repository

If you are not sure whether Go is installed, run this in your terminal:

If you see a version number, you are good. If you see "command not found", you need to install Go first.

Installing Go

Clone and Build

Verify the Installation

Run the test suite to make sure everything is working correctly on your machine:

If all three packages show ok, you are good to go. The -race flag enables the race detector, which checks for concurrency bugs.

Your First Task

Let us walk through the complete lifecycle of a task. This is exactly what happens when AI agents coordinate — you are just doing it by hand to understand each step.

Step 1: Create a Task

Create a new task assigned to the "claude" tool in a team called "demo":

The system responds with JSON confirming the task was created. It has ID 1 and starts in pending status — meaning it is available for an agent to pick up.

Step 2: List Available Tasks

Check what tasks are available:

You can filter by tool, status, or only show tasks that are ready to claim (no unresolved dependencies):

Step 3: Claim the Task

An agent claims the task by providing its name, tool, and the current protocol version:

Notice what changed:

• Status went from pending to in_progress
• Owner is now my-agent
• Version bumped from 1 to 2 (every change increments the version)
• A lease was set (the agent has 30 minutes to finish or send a heartbeat)

If another agent tries to claim the same task now, it gets rejected:

Step 4: Send a Heartbeat (for Long Tasks)

If the work takes more than a few minutes, the agent should send periodic heartbeats to extend its lease:

This resets the 30-minute timer. Without heartbeats, the lease eventually expires and another agent could take over (this is the crash recovery mechanism).

Step 5: Complete the Task

When the work is done, the agent reports completion with a summary and an idempotency key:

The idempotency key (1-my-agent-complete) ensures that if this exact command runs again (due to a retry or crash recovery), it is silently ignored instead of causing an error.

Step 6: Communicate via Inbox

Agents can send messages to each other through inboxes. For example, after completing a task, an agent might notify the lead:

The lead agent reads its inbox:

What Just Happened?

You just walked through the complete task coordination workflow:

In a real deployment, AI agents do exactly these steps automatically. The orchestrator creates tasks, each AI tool's agent session picks up tasks assigned to it, does the work, and reports back. The hq CLI handles all the tricky parts — concurrency, crash recovery, duplicate detection — so agents can focus on the actual work.

Next Steps