Connect an agent.
Install hooks, link this computer, pair your iPhone. Codeaton also speaks Claude Code hooks, ACP session updates and generic CI webhooks natively — so in most cases you are pointing an existing hook at a new URL.
Install hooks and link this computer
Run the installer, then login — no repo clone required:
npx codeaton install
npx codeaton loginInstall copies Cursor hooks and merges ~/.cursor/hooks.json (plus Claude Code, Hermes, Codex, and OpenCode wrappers). For Hermes only: npx codeaton install --providers=hermes --yes. Login opens the dashboard so you can click “Link this computer” — credentials write to ~/.config/codeaton/credentials.json automatically. Restart Cursor after install.
Pair your iPhone
Sign in to the dashboard and scan the QR code with your iPhone camera. It encodes a codeaton://pair link that opens the app and claims a one-time code. You can also type the six-character code in the Codeaton app.
Codes expire, are single-use, and regenerate from the dashboard.
Send your first event
Hooks fire automatically once credentials exist. For a manual check, post to the ingest endpoint with the key as a bearer token. agentKey is the only required field — it is the stable identity Codeaton groups everything under, so keep it consistent across a run.
curl -X POST https://dev.codeaton.com/api/ingest \
-H "Authorization: Bearer $CODEATON_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentKey": "claude-code@macbook",
"name": "claude-code",
"host": "macbook",
"kind": "claude-code",
"type": "started",
"message": "Refactoring the auth module"
}'A successful call returns { "ok": true }. The Live Activity appears on your paired phone within a second.
Close the run so usage is recorded
Send completed or failed when the run ends. Attach metrics and Codeaton records a run row and rolls the numbers into your daily usage totals and Rankings position.
curl -X POST https://dev.codeaton.com/api/ingest \
-H "Authorization: Bearer $CODEATON_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentKey": "claude-code@macbook",
"type": "completed",
"message": "Refactored auth, 12 files",
"runId": "run_8f21",
"metrics": {
"tokensIn": 184000,
"tokensOut": 21500,
"model": "claude-opus-5",
"toolCalls": 37,
"filesChanged": 12
}
}'Metrics are optional — without them a run still lands in history on outcome alone, but tokens and model diversity will not update until metrics are attached.
Event types
| type | Send it when |
|---|---|
| started | A run began. |
| progress | Meaningful progress — a step, a chunk, a percentage. |
| tool_call | The agent invoked a tool. |
| waiting_input | Blocked on a human. Turns the island amber. |
| completed | The run succeeded. Closes the run and scores it. |
| failed | The run errored or was cancelled. Also scored. |
| idle | Heartbeat with no active run. |
Metrics fields
| Field | Type | Meaning |
|---|---|---|
| tokensIn | number | Prompt tokens consumed by the run. |
| tokensOut | number | Completion tokens produced. |
| cacheReadTokens | number | Tokens served from prompt cache. |
| model | string | Model identifier, e.g. claude-opus-5. |
| toolCalls | number | How many tools the run invoked. |
| filesChanged | number | Files the run modified. |
Payloads you don’t have to translate
Codeaton normalizes several common shapes into its own vocabulary, so you can often forward an existing payload unchanged. Whatever you send, include agentKey.
Claude Code hooks
Objects carrying hook_event_name. UserPromptSubmit maps to started, PostToolUse to tool_call, Notification to waiting_input, Stop to completed.
ACP session updates
Agent Client Protocol session/update notifications — message chunks, tool calls and plans all map onto the canonical types.
Generic CI webhooks
Anything with a status of running, success, failure or cancelled. Useful for pointing an existing pipeline at Codeaton with no code.
An unrecognized shape returns 422 rather than being stored as noise.
What Codeaton never receives
There is no field in this API for source code, diffs, file contents or prompt text. The message field is truncated to 200 characters and is meant for a short human-readable line. If you put a secret in it, it will show up on your Lock Screen — so don’t.
Put your agents on your island.
Pair in a minute, wire up one HTTP call, and stop tabbing back to your terminal to see if anything happened.