IdlePay client

The IdlePay CLI + statusline client (see ../DESIGN.md). Zero dependencies, Node ≥ 18. Talks to the real API server in ../server/ (Node ≥ 22.5).

What's here

| Path | Role | |---|---| | src/statusline.mjs | Hot path. Copied to ~/.idlepay/ at init; prints your existing statusline + one ad line; heartbeats; lazily spawns the refresher. No network, never throws. | | src/refresher.mjs | Background worker. Detects wait states (transcript mtime), accrues 5-second impressions, spools + batch-uploads events, syncs ads every 60 s, self-exits after 10 min idle. | | src/settings.mjs | Patches/restores ~/.claude/settings.json with a verbatim backup. | | bin/idlepay.mjs | CLI: init · off [--1h\|--today\|--here] · on · status · uninstall. | | test/smoke.mjs | Sandboxed e2e test against the real server (fake ~/.claude, fake transcript). npm test. |

Try it for real (your actual Claude Code)

npm run server                         # terminal 1 — real API, dev-mode auth, landing on :4848
node bin/idlepay.mjs init              # terminal 2 — device-flow login, patches ~/.claude/settings.json (backed up)
claude                                 # open any Claude Code session, ask it something
node bin/idlepay.mjs status            # watch impressions/earnings accrue
node bin/idlepay.mjs uninstall         # byte-exact restore, removes ~/.idlepay, deregisters device

Sandboxed instead (no real settings touched): npm test.

Known gaps deferred from code review (fix before real money)

• Spool overflow drops newest events (design says drop oldest).
• Heartbeat file is read-modify-write; concurrent sessions can briefly lose each other's heartbeat (self-heals ≤5 s). Production: per-session heartbeat files.
• Byte-exact restore overwrites settings changes the user made after init.
• Stale ad cache blanks at 10 min instead of the design's 1 h stale-serve window.
• Pid-reuse can suppress refresher respawn until the squatter pid exits.
• An impression's 5 s accrual can span an ad rotation boundary.

Remaining simplifications vs DESIGN.md

• GitHub device flow is implemented end-to-end but needs a registered OAuth app (GITHUB_CLIENT_ID on the server); without it the server runs dev-mode auth.
• Settings patcher handles plain JSON only (production: JSONC-preserving editor).
• Wait-state detection uses transcript mtime only (no done-flag read yet).
• No re-assert after Claude Code updates, no killswitch restore path (freeze only).