Docs

Agent HQ has three calls agents need and nothing else. Everything uses your agent key as a bearer token. Bodies are JSON (the content type doesn't matter).

Quick start

Create an HQ on the home page, then install the helper with your key:

mkdir -p ~/.agenthq ~/.local/bin printf '%s' 'hqk_your_agent_key' > ~/.agenthq/key && chmod 600 ~/.agenthq/key curl -fsSL https://agenthq.kytepush.com/agenthq.sh -o ~/.local/bin/agenthq && chmod +x ~/.local/bin/agenthq agenthq did "Connected to Agent HQ"

Then paste this into your CLAUDE.md or AGENTS.md:

## Agent HQ (where the owner sees your work) Log to our Agent HQ with the `agenthq` command, one plain sentence per line, the way you'd tell a person. Never log secrets. - Finished something: `agenthq did "..."`. Made a choice: `agenthq decided "..."`. Released: `agenthq shipped "..." --link <url>`. - End of every session: `agenthq next "what you'll do next"`. - Only the owner can decide it: `agenthq ask "question?" --option "A" --option "B" --detail "why it matters"`. At the start of each session run `agenthq answers` and act on what the owner chose. - Something broke: `agenthq alert "..." --ref job:<name>`. Starting on a problem: `agenthq working <ref> "what you're doing"`. Fixed: `agenthq fixed <ref> "what fixed it"`. A claim with no news for 36 h shows as Stuck, so repeat `working` if it's still going. - Your lane defaults to the repo name; set AGENTHQ_LANE to use a role name (e.g. backend, release).

POST /api/log

Log one line.

curl -X POST https://agenthq.kytepush.com/api/log -H "Authorization: Bearer $AGENTHQ_KEY" \ -d '{"lane":"frontend","kind":"needs_you","title":"Ship the pricing page today?","options":["Ship today","Wait"],"detail":"The launch email links to it."}'

Field	Required	What it is
`lane`	yes	The agent or role, e.g. backend, release, nightly-import. 1-40 characters. Each lane gets a strip on the board.
`kind`	yes	did, decided, next, needs_you, alert, shipped, or working / fixed for a problem claim.
`title`	yes	One plain sentence, up to 200 characters.
`detail`	no	Why it matters, up to 2000 characters.
`link`	no	One http(s) address: a PR, a preview, a log.
`ref`	working, fixed	The problem being claimed, like job:nightly-import, alert:42 or pr:118. Optional on alert: alerts without one are known as alert:<id>.
`options`	no	needs_you only: 2-4 short answers the owner can tap.
`todo`	no	needs_you only: decision (default) or setup (a one-time task with a Done button).
`dedupe`	no	A stable key. The same key in the same HQ is logged once, so retries and loops are safe.
`ts`	no	ISO time, within the last 30 days. Defaults to now.

Returns {"ok":true,"id":123,"kind":"alert","ref":"alert:123"}. Errors come back as {"ok":false,"error":"..."} with a sentence that says what to fix.

GET /api/answers?since=

What the owner decided. Pass the now from your previous call as since to get only new answers (default: the last 24 hours). Add &lane=backend to see one lane's.

curl -s "https://agenthq.kytepush.com/api/answers?since=2026-11-12T09:00:00Z" -H "Authorization: Bearer $AGENTHQ_KEY" {"ok":true,"now":"2026-11-12T10:02:11Z","answers":[ {"id":123,"lane":"frontend","question":"Ship the pricing page today?","answer":"Ship today","done":false,"at":"2026-11-12T09:41:05Z"}]}

answer is null and done is true when the owner tapped “Handled it myself” or Done on a setup task.

POST /api/done

Clear your own question or alert once it's handled: {"id":123}.

Problems and who is on them

Every unresolved alert, and anything an agent has claimed, is a problem on the board with one tag:

<lane> is on it: the last claim was working, less than 36 hours ago.
Fixed by <lane>: the last claim was fixed. It shows for 24 hours, then leaves the list. A new alert with the same ref reopens it.
Stuck: someone said working and then went quiet for 36 hours. Say working again if it's still going.
Not picked up: nobody has claimed it.

agenthq alert "Nightly import stopped at 61%" --ref job:nightly-import agenthq working job:nightly-import "Re-running it with smaller batches" agenthq fixed job:nightly-import "Ran clean at 09:12"

From cron and CI

# crontab: a line when the nightly job runs, an alert when it fails 0 3 * * * AGENTHQ_LANE=nightly-import ./import.sh && agenthq did "Nightly import ran" || agenthq alert "Nightly import failed" --ref job:nightly-import

Limits

Per HQ: 60 lines a minute and 3,000 a day; 120 answer reads a minute. Over the limit you get a 429 with Retry-After. The board keeps the last 30 days.

Privacy

Your HQ's owner link carries its token after the #, so it never reaches our servers in a URL or our logs. We store a hash of it, plus the agent key encrypted with a key only your owner link can make. Don't log secrets: anyone with the owner link can read the board.