Collector manual

How AgentBoard works

A lightweight CLI collector that hooks into your AI coding tools and sends only token counts — automatically, as you work.

How it works

🔗

Hook Registration

AgentBoard install-hooks writes per-turn and session-end hooks into each AI tool's own config file.

⚡

Auto Collection

When a hook fires, a background worker parses the session transcript and uploads only the tokens that are new.

📊

Plan Snapshot

The collector also reads your local usage status — never a real prompt, never a billable turn — to capture remaining rate-limit %.

📤

Token-only Upload

Only token counts, model name, timestamps, and rate-limit % are sent. Code and prompts never leave your machine.

Data flow

AI session runs→hook fires — after each turn and at session close→background worker reads the session transcript→new tokens + rate-limit % extracted→POST /api/proxy/v1/events/usage/batch→Dashboard & Plan Recommendation

Never blocks, never double-counts. Collection runs in a background process, and each upload carries only the tokens accrued since the last one. Rate-limit snapshots are a local status read — at most one per tool every 10 minutes, never a billable turn.

Plan Recommendation then compares that 5-hour/weekly usage against your current subscription plan and tells you whether to upgrade, downgrade, or stay put — see /plans.

Supported AI tools

Tool	Setup	Token tracking	Plan snapshot
Claude Code	Automatic — Stop + SessionEnd (~/.claude/settings.json)	Full	Yes
Codex CLI	Automatic — notify (~/.codex/config.toml) + SessionEnd/SubagentStop (~/.codex/hooks.json)	Full	Yes

agentboard install-hooks registers both automatically and skips any tool it doesn't detect on your machine. Codex's SubagentStop hook also captures tokens spent by its subagents.

Installation

Prerequisites

Node.js ≥ 20 and Git are required.

Clone and build the collector

$ git clone https://github.com/hse09021/agentboard-agent-collector.git

$ cd agentboard-agent-collector

$ npm install

$ npm run build

$ npm link # register agentboard as a global command

$ agentboard login

# Open the printed URL → GitHub OAuth → paste the token back

$ agentboard install-hooks

That's it. From now on, every turn you run in a supported AI tool — plus a final sweep when the session closes — reports token counts and a rate-limit snapshot automatically. Run agentboard status to confirm auth state and recent usage.

Codex requires you to approve new hooks before they fire: run /hooks inside Codex (or restart it) and trust the agentboard hooks, otherwise its session-end and subagent collection stays inactive.

Updating

Pull the latest source and rebuild

$ cd agentboard-agent-collector

$ git pull

$ npm install

$ npm run build

$ npm uninstall -g @agentboard/collector

$ npm link

$ agentboard --version

$ agentboard install-hooks --force

$ agentboard doctor

Updating normally keeps your login state and device ID because local collector settings are stored in ~/.agentboard, not inside the package. Re-run install-hooks --force after updating so each AI tool points at the newest hook scripts. If npm link reports that agentboard.cmd already exists on Windows, run npm uninstall -g @agentboard/collector and then run npm link again. If the error continues, remove stale agentboard shim files from %APPDATA%\npm.

CLI reference

agentboard loginGitHub OAuth login and device registration.

agentboard logoutRemove the local auth token.

agentboard install-hooksWrite the per-turn and session-end hooks into each supported AI tool's config.

agentboard uninstall-hooksRemove all registered hooks.

agentboard statusShow auth state, hook registration, and collected session count.

agentboard doctorDiagnose config files, auth, and hook registration.

Privacy guarantee

LOCAL-FIRST

No prompts

No code

No repos

No file paths

Only token counts, model names, timestamps, and — for Claude Code/Codex — remaining rate-limit %.

Never collected

✕Prompt text
✕Source code
✕File contents & paths
✕Repository names
✕Commit & PR content
✕Terminal commands

What we collect

✓Token counts (input, output, cached)
✓Session ID (the AI tool's own random ID)
✓Timestamps
✓Model name
✓OS type (once, when the device is registered)
✓Claude Code/Codex: plan name & remaining rate-limit % (for Plan Recommendation)

Every event passes through a Forbidden Data Guard before upload that rejects any field shaped like a prompt, code, path, or command. The raw usage-status output captured for Plan Recommendation is additionally scanned and redacted if it looks like it contains a file path. The collector is open source — you can inspect exactly what gets sent.

Already set up? Head to your dashboard.

Go to Dashboard →