claude-code-buddy

Claude Code Buddy Skill

Connect to a device on the local network and push Claude Code events to it. After connecting, the Stop and Notification hooks fire automatically — this skill covers the on-demand actions (connect, notify, usage) and the plain-language config tuning.

The plugin only speaks the HTTP contract below. The device decides the actual LED / display / voice feedback; the plugin never draws anything itself.

Config

Path: ~/.config/claude-code-buddy.json (file permission 0600).

{
  "devices": [
    { "label": "My Device", "host": "lamp-a1b2.local", "last_known_ip": "192.168.1.50", "password": "the-web-admin-password" }
  ],
  "default_host": "lamp-a1b2.local",
  "usage_threshold": 80,
  "sounds_enabled": true,
  "task_done_enabled": true,
  "notify_enabled": true
}

• host is the device's mDNS hostname (like lamp-a1b2.local); last_known_ip is the cached address used to avoid re-resolving every time.
• password is the device's admin password — the same one used to log into the device's web UI. The daemon gates its LAN endpoints (notify / usage / approval) with it, sent as an Authorization: Bearer header; without it those calls return HTTP 401. Discovery (/health) stays open, so the device is still findable before a password is set. Stored only in this 0600 file.
• Shared helpers live in scripts/buddy_client.py (config load/save, discovery, send(), usage fetch). Prefer them over re-implementing.

1. Discover / Connect

Find the device on the LAN and save it to config.

When to use: "connect my device", "set up my device", or when a POST fails with a connection error/timeout (the cached IP is stale).

Run discovery

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/discover.py

How it works (automatic): cache check (cached IP → /health) → mDNS browse for _autonomous._tcp → /24 subnet /health sweep. Returns the found device(s) as JSON, e.g.:

[{ "host": "lamp-a1b2.local", "ip": "192.168.1.50" }]

On success: ask the user for the device's admin password (the same one they use to log into the device's web UI) — the daemon requires it to accept activity/approval pushes. Then write the device into devices[] (append new, update existing by host) including the password field, set default_host if it's the first device, and write the file with permission 0600.

If a later push returns HTTP 401, the stored password is missing or wrong (or was changed in the web UI) — ask the user for the current admin password and update the device entry.

On failure: exits non-zero with {"error": "not_found"} on stderr. Suggest: device powered on? Same WiFi as the computer?

2. Notify

POST a notification to the device. Most common on-demand action.

When to use: "notify my device", "send to my device", "ping my device when done". Also reasonable proactively at the end of a long task.

2.1 Pick the target

Use default_host (and its last_known_ip) from config. If no config or no devices → tell the user to connect a device first (section 1).

2.2 Build the payload

{
  "title": "Build passed",
  "subtitle": "3m 12s, 0 failures",
  "level": "done",
  "sound": true
}

• title (string, required) — short headline, plain text.
• subtitle (string) — one line of detail.
• level — "done" | "attention" | "info". Use attention when the user needs to act, done for completions, info otherwise.
• sound (boolean) — whether the event carries a sound cue. The device picks the actual cue; do not send sound indices. Respect sounds_enabled from config.

2.3 Send (urllib, stdlib only)

import json, urllib.request

payload = json.dumps({
    "title": "Build passed",
    "subtitle": "3m 12s",
    "level": "done",
    "sound": True,
}).encode()

req = urllib.request.Request(
    "http://<ip>:5002/claude-code/notify",
    data=payload,
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=3) as resp:
    print(resp.status)          # expect 200, body {"ok": true}

Replace <ip> with the device's last_known_ip (or resolve host).

3. Usage

Fetch the user's OAuth usage and POST it to /claude-code/usage.

When to use: "push my usage to my device", "/claude-code-buddy:usage".

3.1 Fetch usage

Read the OAuth token (~/.claude/.credentials.json, or the macOS keychain item Claude Code-credentials; the token starts with sk-ant-oat), then:

import json, urllib.request

req = urllib.request.Request(
    "https://api.anthropic.com/api/oauth/usage",
    headers={
        "Authorization": f"Bearer {token}",
        "anthropic-beta": "oauth-2025-04-20",
    },
)
with urllib.request.urlopen(req, timeout=15) as resp:
    usage = json.loads(resp.read())

from buddy_client import time_left

five_hour = int(usage["five_hour"]["utilization"])
seven_day = int(usage["seven_day"]["utilization"])
reset_5h  = time_left(usage["five_hour"]["resets_at"])   # -> "1h 56m"
reset_7d  = time_left(usage["seven_day"]["resets_at"])   # -> "1d 11h"

scripts/buddy_client.py already wraps token lookup + fetch — use it.

3.2 POST to /claude-code/usage

{
  "five_hour": 41,
  "seven_day": 48,
  "reset_5h": "1h 56m",
  "reset_7d": "1d 11h",
  "sound": true
}

reset_5h / reset_7d are display-ready strings (humanize the resets_at ISO timestamp with buddy_client.time_left()), not raw ISO — the device shows them as-is.

POST to http://<ip>:5002/claude-code/usage exactly like section 2.3 (expect 200, {"ok": true}). The usage API rate-limits hard — do not poll faster than once per minute.

4. Task Done + "Claude needs you" (automatic)

These run via Claude Code hooks; no skill action needed.

• Stop hook (scripts/on-stop-done.py) — fires after each response. POSTs /claude-code/notify with level: "done". If 5-hour or 7-day usage is >= usage_threshold, it also POSTs /claude-code/usage. Skipped when task_done_enabled is false.
• Notification hook (scripts/on-notify.py) — fires when Claude needs approval or input has gone idle. POSTs /claude-code/notify with level: "attention". Skipped when notify_enabled is false.

Both honor sounds_enabled for the sound field and fail silently if no device is connected.

5. Tuning (plain-language config edits)

Let the user retune behavior in plain language — read config, change only the relevant key(s), preserve everything else, write back with permission 0600, then confirm in plain language. If the config is missing → tell them to connect a device first.

5.1 Threshold

When to use: "warn me earlier", "set warning threshold to 60", "only warn me near the limit", "I want pushes at 90%".

• Explicit number → use it. "earlier"/"sooner" → lower (e.g. 60). "only near the limit" → raise (e.g. 90). If unclear, ask for a number.
• Validate integer 0–100, then set usage_threshold.

5.2 The three toggle flags

All default true and live at the top level of the config.

Mapping requests:

• "mute my device" / "turn off the sounds" → sounds_enabled = false
• "unmute" / "sounds back on" → sounds_enabled = true
• "stop the task done notification" → task_done_enabled = false
• "stop pinging me when Claude needs me" → notify_enabled = false
• "turn all notifications off" → task_done_enabled = false and notify_enabled = false
• "turn everything back on" → all three true

The hooks read these flags on every run, so changes take effect immediately — no restart.

6. HTTP responses

Important

• Python 3 stdlib only — no pip, no extra dependencies.
• Keep sound a boolean; the device decides the actual cue.
• Never print or log the OAuth token.
• Config file permission must be 0600.
• Device-side /claude-code/notify and /claude-code/usage receivers exist and log the payload, but may not yet render device feedback on every device (the HAL bridge is the remaining work); /health and /status exist for liveness/discovery.