Repository navigation
Edge shipper: ship Claude Code / Codex usage from Mac + Linux to the hub - #4
Merged
Merged
Conversation
Machines that aren't the hub had no way in: hooks could only reach a tracker listening on this box, and the hub could only see a remote machine's activity by mounting its ~/.claude / ~/.codex. This adds the missing half of the multi-machine story — a small always-on agent that runs where the work happens. Claude Code hooks POST to a loopback intake, which appends to a JSONL spool before answering, so the hook keeps its "always exit 0, fast" contract and nothing is lost while the tailnet is down. A flusher forwards batches of at most 500 events (the hub's MAX_BATCH_SIZE) to /api/ingest/v1 with the shared bearer token, backing off exponentially when the hub is unreachable. - edge/: zero-dependency Node package (config, intake, queue, shipper, agent, redacting logger) plus an `llm-edge start|status|drain|send|config` CLI. Paths go through os.homedir()/path.join and config lives under ~/.config/llm-usage-tracker-edge on both macOS and Linux — v1 platforms are macOS and this Linux box; Windows is a roadmap note only. - Every event carries a source_id: the caller's, or a SHA-256 of the event's content and millisecond timestamp. Retries and replayed batches are dropped by the hub's idempotency index rather than duplicated. - 401/403 stops the flush and keeps the backlog; 503 and 5xx/network errors retry; only a 400 drops its batch, since it would otherwise wedge every later event behind it. - The token exists only in an Authorization header. Every log line passes through a redactor, and status/config report ***set*** or ***missing***. - hooks/edge-hook.sh bridges the existing hook to the edge by setting MONITOR_URL, and the intake accepts POST /api/monitor/events verbatim — so the local hub+watchers path is untouched for people running both on one box. - Tests: 85 in edge/ (node --test, nothing to install) covering queue idempotency and durability, batch chunking, the auth header and exact body shape, offline retry, backoff bounds and log redaction; plus a vitest contract test that posts an edge-built batch through the real ingest route. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ninedter
force-pushed
the
claude/edge-ship-agent
branch
from
September 10, 2026 14:22
e9561ad to
b550ab7
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on the ingest contract from #2 (
POST /api/ingest/v1, merged into main): this is the client half. Machines that aren't the hub previously had no way in — hooks could only reach a tracker on the same box, and the hub could only see remote activity by mounting that machine's~/.claude/~/.codex. This adds a small always-on agent that runs where the work happens.Hooks stay in Claude Code's critical path, so they can't wait on a tailnet that might be down. The edge answers on loopback in ~1 ms after the event is on disk, and takes over delivery from there.
What's here
edge/— zero-dependency Node package (needs Node ≥ 20, nonpm install): config, loopback intake, JSONL spool, batching flusher, redacting logger, and anllm-edge start|status|drain|send|configCLI. Everything path-portable (os.homedir()/path.join), config and spool under~/.config/llm-usage-tracker-edge/on both platforms. Secrets come from env or a config file — no Keychain-only path.hooks/edge-hook.sh— bridges the existing hook to the edge by settingMONITOR_URL; the intake acceptsPOST /api/monitor/eventsverbatim, so no hook logic is duplicated.hooks_edgeblock added tohooks/claude-hooks-config.json. The local hub+watchers path is untouched for anyone running both on one box.edge/README.mdhas copy-paste install for macOS and Linux, launchd and systemd user units, the full config table, CLI reference and troubleshooting. The root README gains a "Shipping from another machine (the edge)" section.Decisions worth reviewing
source_id— the caller's if it sends one, otherwise a SHA-256 over the event's content and its millisecond timestamp. Retries and replayed batches are counted as duplicates by the hub, never inserted twice.401/403stops the flush and keeps the backlog (the token is wrong; hammering the hub won't help).503(hub started withoutINGEST_TOKEN) and 5xx/network errors retry with exponential backoff + ±20% jitter. Only400drops its batch — an unshippable batch would otherwise wedge every later event behind it.INGEST_TOKENonly ever appears in anAuthorizationheader. Every log line goes through a redactor that strips the literal token plus anything bearer- or token-shaped;status/config/GET /statusreport***set***or***missing***. A test asserts the token cannot reach a log sink even on the auth-failure path.grep. Capped at 100k events, oldest-first eviction, compaction batched so a long offline stretch doesn't go quadratic.127.0.0.1:3799can already run the hook.Scope
macOS + Linux for v1. Windows is a one-line roadmap note in
edge/README.md— the code is path-portable, but no service installer is provided. No mTLS (Tailscale is the transport security, matching #2). No hub schema/API changes.Tests
npm run test:edge— 85 tests inedge/(node --test, nothing to install): queue idempotency and durability across restart, oldest-first eviction, batch chunking at the hub's 500 cap, auth header present, exact hub body shape, offline retry, backoff bounds, config precedence, CLI, and log redaction.npm testat root — 160 tests (was 155), including a newsrc/app/api/__tests__/edge-contract.test.tsthat posts an edge-built batch through the real ingest route: accepted as-is, label lands on the session row, a replay comes back as duplicates, a full 500-event batch is accepted, and a batch without the bearer token is still 401.npm run lint,npx tsc --noEmitandnpm run buildclean.MONITOR_URL=http://127.0.0.1:3799 bash hooks/test-hook.shwith a stub hub — all seven hook types exited 0 in ~55 ms each, arrived as one correctly shaped batch with the right bearer header, queue drained to zero, no token anywhere in the logs.grok-bot-boxdeploy checklist (docs only — nothing deployed here)henrys-mac-mini) is up withINGEST_TOKENset and reachable on the tailnet:curl -sf http://henrys-mac-mini:3789/api/health.grok-bot-box: clone the repo, write~/.config/llm-usage-tracker-edge/.envwithTRACKER_URL=http://henrys-mac-mini:3789,MACHINE_ID=grok-bot-box,MACHINE_LABEL=Grok Bot box, then appendINGEST_TOKENviaread -rsso it never hits shell history;chmod 600.node edge/bin/llm-edge.js send --dry-run— check the batch shape, thenllm-edge start.edge/README.md,systemctl --user enable --now llm-edge,loginctl enable-linger $USER.hooks_edgeblock to~/.claude/settings.json, thenMONITOR_URL=http://127.0.0.1:3799 bash hooks/test-hook.sh.llm-edge status→queued: 0,shipped_totalclimbing; the machine appears inGET /api/machineson the hub.henrymacbook-prowithMACHINE_ID=henrymacbook-pro(launchd plist instead of systemd).🤖 Generated with Claude Code