Kicksats CLI

The open-source client for Kicksats — get paid in Bitcoin (sats) while your AI coding agent works.

While Claude Code is thinking, a one-line ad sits under your prompt. An advertiser funded that slot over Lightning, and half of what they pay accrues to you, the dev running it. When your balance crosses a tiny floor it auto-pays to your Lightning address. No account, no signup, no KYC.

This repo is the client — the scripts that run on your machine. It's open so you don't have to take anyone's word for what it does before you run it.

What it actually does (the trust model)

This is the part worth reading before you install anything near your machine:

• It never sees a key. The only thing it needs from you is a Lightning address — that's receive-only, like an email for money. There is no seed, no private key, no API key anywhere in this code. Nothing it's given can move money out of any wallet; it can only receive sats to you.
• The one network call it makes is to the Kicksats API: it fetches the current ad and reports that a thinking-window happened, so the impression can be billed. You can see exactly that in kicksats-bill.mjs and kicksats-statusline.mjs. Nothing else phones anywhere.
• The status-line script reads a locally-cached ad and prints one line. It strips control characters out of the ad text, so a malicious ad can't inject escape sequences into your terminal (sanitize() in kicksats-statusline.mjs).
• The client only proposes; the server decides. It can't mint sats. Every impression is gated server-side by a single-use signed token, a per-session credit-gate, and the advertiser's budget. See cli/IMPRESSIONS.md.
• It never signs anything. The billing token comes from the server already signed; the client just presents it. The signing secret is not in this code and never will be.

If the VS Code extension is the part that bugs you: skip it. The CLI scripts here are the whole earning path on their own.

Files

File	What it does
cli/kicksats-statusline.mjs	Renders the ad line + your earnings counter under the Claude Code prompt. Read-only, never bills.
cli/kicksats-bill.mjs	On each agent turn (Stop hook), reports one impression for the displayed ad.
cli/kicksats-refresh.mjs	On session start, refreshes the cached ad + your balance.
cli/kicksats-settings.mjs	Manages the status-line / spinner config in ~/.claude/settings.json.
cli/install.sh / cli/uninstall.sh	Wire the scripts into Claude Code's hooks. Reversible.
cli/IMPRESSIONS.md	Exactly what counts as one billable impression, and why it can't be inflated.

Install

KICKSATS_LN=you@your-lightning-address.com ./cli/install.sh

Or follow the guided install at kicksats.com. To remove it completely: ./cli/uninstall.sh.

Plumbing

Plain JavaScript, no build step, no minification, no dependencies to audit beyond Node itself. Read every line.

The server (billing, payouts, anti-abuse) is a separate, closed component — what's open here is everything that runs on your machine, which is the only part whose trust matters to you.

Giving back

10% of every sat goes to OpenSats and the HRF Bitcoin Development Fund. The dev's half is never touched.

License

MIT — see LICENSE.