Monitor your background coding agents at a glance on your Hammerhead Karoo 3 bike computer. No phone required.
Three native Karoo data fields that update in real time over WiFi.
Numeric 0-100% completion estimate based on tool call count and inferred phase. Shows at a glance how far along your agent is.
Count of pending permission prompts. When this goes above zero, you know your agent is blocked and waiting for input.
Graphical field showing agent name, current phase, and status line. Color-coded: amber background when waiting, dimmed when offline.
Track any number of concurrent sessions. Cycle between agents with the "Next Agent" bonus action during your ride.
Everything runs on your local network. No cloud, no accounts. Pairing code + bearer token over LAN.
Adapter architecture supports future agents (Cursor, Aider, Codex). The bridge accepts events from any source.
Three components connected by HTTP. Agents push, the Karoo polls.
Workstation Karoo 3
+-----------------+ HTTP POST +-----------+ HTTP GET +---------------+
| Claude Code |---- hooks -------->| Bridge |<---- poll (3s) ---| Karoo |
| (agent session) | (curl, 5s max) | Server | | Extension |
+-----------------+ | :7420 | | |
| | | Data Fields: |
+-----------------+ HTTP POST | In-memory | | progress % |
| Future agents |---- adapter ------>| agent | | questions # |
| (Cursor, Aider) | | store | | status (gfx) |
+-----------------+ +-----------+ +---------------+| Component | Technology | Role |
|---|---|---|
| Bridge Server | Node.js TypeScript Fastify |
Aggregates agent state, serves REST API on port 7420 |
| Karoo Extension | Kotlin karoo-ext SDK Jetpack Glance |
Renders native data fields on the Karoo 3 display |
| Agent Adapter | Claude Code hooks curl |
Pushes lifecycle events (tool use, notifications, stop) to bridge |
How the bridge tracks your agent's state as it works.
| Event | Status | Phase | What happens |
|---|---|---|---|
| Session starts | working | starting | Agent created, progress set to 5% |
| Read/Glob/Grep | working | thinking | Agent is exploring the codebase |
| Edit/Write | working | implementing | Agent is writing code, progress jumps to 30%+ |
| Bash (test/lint) | working | testing | Agent is running tests, progress jumps to 70%+ |
| Permission prompt | waiting | - | Pending questions incremented, display turns amber |
| Stop | idle | reviewing | Progress set to 100%, task complete |
| Session ends | stopped | - | Agent marked as stopped |
Get running in three steps. Detailed guide in docs/setup.md.
Install dependencies and run the bridge. It prints a pairing code on startup.
cd bridge
pnpm install
pnpm devPair to get a token, set it as an environment variable, and merge the hooks config.
# Get a token
curl -X POST http://localhost:7420/api/v1/pair \
-H 'Content-Type: application/json' \
-d '{"pairingCode": "YOUR_CODE"}'
# Set the token in your shell
export AGENT_HUD_TOKEN="ahud_..."
# Merge hooks/claude-hooks.json into ~/.claude/settings.jsonBuild the APK and sideload it to your Karoo 3. Open Agent HUD, enter the bridge URL and pairing code.
cd karoo-app
./gradlew assembleDebug
# Sideload via ADB or Hammerhead Companion App
adb install -r app/build/outputs/apk/debug/app-debug.apk| Component | Requirements |
|---|---|
| Bridge | Node.js 20+, pnpm |
| Karoo Extension | Android SDK, JDK 17+, GitHub token with read:packages scope |
| Claude Code | Claude Code CLI, curl |
Full reference in docs/api.md. Base URL: http://<host>:7420/api/v1
| Endpoint | Auth | Description |
|---|---|---|
GET /health | No | Server status and uptime |
POST /pair | No | Exchange pairing code for bearer token |
GET /agents | Yes | List all agents with active agent ID |
GET /agents/:id/summary | Yes | Detailed agent state, phase, progress |
POST /agents/:id/action | Yes | Send action (e.g., approve) to agent |
POST /agents/:id/active | Yes | Set active agent |
POST /hooks/* | Yes | 6 hook endpoints for agent lifecycle events |