CLI & clients

While an AI assistant thinks, one tasteful ad line shows on the developer's screen. Advertisers pay per verified view, and the developer whose screen showed the line keeps up to 50% of the spend.

Three roles, one balance each. Developers install a client wherever they code and earn per view. Advertisers fund a wallet and run campaigns. Admins review every creative before it serves.

Every client speaks the same two-endpoint contract with a device token:GET /api/serveasks what to show andPOST /api/eventsreports the view or click. Server-side pacing makes any client safe - nothing a client does can overcount.

Sign up as a developer, open your dashboard, and generate a device token under Connect your tools. The token starts with idl_ and is shown exactly once - it works on every surface below, and every surface earns into the same balance.

$ npm i -g idleai
$ idleai login idl_xxxx
$ idleai run
✶ earning while you wait - [o]pen pays 50× · [q]uit

That is the whole loop. Pick your surfaces below - you can run as many at once as you like; only the one actually on screen serves.

The reference client. idleai run shows a live earning line in any terminal; the wrappers run a coding agent with the ad line in a tmux status bar - timed to the thinking window for Codex, Gemini and Grok, and shown while the session is live for aider, opencode, Amazon Q and goose.

$ idleai run # live line - a view every 5s, [o] opens = click
$ idleai codex # Codex CLI with the ad in the status bar
$ idleai gemini # same wrapper for the Gemini CLI
$ idleai grok # and the Grok CLI
$ idleai aider # aider, opencode, Amazon Q (q) and goose too

Coding with the Claude Code CLI? It has no tmux wrapper on purpose - it earns through a deeper integration instead. Run idleai setup-claudeonce (or install the plugin) and the ad rides Claude's own thinking window - see the Claude Code section below.

idleai pause and idleai resume write a shared flag in ~/.idleai.json honored by the CLI, the Claude Code plugin, the VS Code extension and the macOS companion.

The plugin puts the ad line in the statusline only while Claude thinks and a quiet earnings line otherwise. On Claude Code 2.1+ the ad rides the thinking spinner itself. Desktop and IDE surfaces read the same settings tree, so one install covers all of them.

/plugin marketplace add idleai-app/idleai-clients
/plugin install idleai@idleai
/idleai:setup # wires the statusline - needs idleai login once

Quick path without the marketplace: idleai setup-claude wires an always-on statusline; the plugin adds thinking-window timing on top.

OpenAI's Codex has no statusline or spinner hook of its own, so idleai covers it three ways - pick whichever surface you use.

$ idleai codex # run the Codex CLI, ad in a tmux status bar
# timed to Codex's thinking window (~/.codex/sessions)

$ idleai patch-codex # or render the ✶ line INSIDE the Codex VS Code panel
# reload the window · undo with idleai unpatch-codex

The CLI wrapper (idleai codex) is gated to Codex's thinking window, the same way the Claude plugin is. The panel injection (patch-codex) patches the installed openai.chatgpt extension - opt-in and reversible, wiped by Codex updates (just run it again). The standalone Codex desktop app has its own reversible node patch.mjs in clients/codex-desktop-inject.

A status-bar item: ✶ <ad text> ↗ · $0.42 today. Views pay after 5 seconds on a focused window; clicking opens the ad. Cursor and Windsurf install VS Code extensions unchanged.

$ cd clients/vscode && npx @vscode/vsce package
$ code --install-extension idleai-0.1.0.vsix
# or: cursor --install-extension … / windsurf --install-extension …

Sign in from the command palette (Idleai: Sign in with device token) - or do nothing if you already ran idleai login; the extension reuses ~/.idleai.json.

Works on claude.ai, chatgpt.com (including the Codex task view), grok.com, gemini.google.com, chat.mistral.ai, perplexity.ai and chat.deepseek.com. A content script detects the assistant's thinking indicator and renders the ✶ pill beside it - only while the assistant works, only on a visible tab.

1. chrome://extensions → Developer mode → Load unpacked → clients/browser/ (Firefox: about:debugging → Load Temporary Add-on)
2. Extension popup → settings → paste your token and server URL.

The token lives in the service worker and never enters page contexts. Pause lives in the popup.

Native apps don't expose an injection surface, so the companion is a menu-bar ticker that serves only while an assistant app is frontmost - no Accessibility permission, no app tampering. A frontmost terminal also counts while an agent CLI is actively working in it, covering codex, gemini and grok runs in Terminal, iTerm2, Warp, Ghostty and friends.

$ cd clients/companion-mac && ./build.sh
$open "Idleai Companion.app"

The tray twin of the mac companion - serves only while an assistant app owns the foreground window, with the ad line in the tray tooltip and a balloon on rotation. One PowerShell file, no build step.

> powershell -ExecutionPolicy Bypass -File idleai-companion.ps1

Written to the verified contract but not yet tested on real Windows - treat it as a preview.

A native Replit Extension: the ✶ earning pane inside the workspace (a static webview, no build - see clients/replit). Quick alternative in any workspace: split a shell pane and run the CLI.

$npm i -g idleai && idleai run

Connectors are model-invoked, so they can't host the idle slot - this is the honest utility build for catalog presence: check_earnings, current_ad and set_paused over stdio MCP, zero dependencies. It ships with a Gemini CLI extension manifest; Claude Code and Codex config snippets live in clients/mcp.

Cursor and Devin render their chat as native workbench UI with no hook idleai can use - no statusline, no spinner, no webview an extension can reach. So for the closest thing to Claude Code's native integration, these clients render the ✶ line insidethe assistant's own panel by patching the app's installed files. Every patch is opt-in, backs up the originals, and is fully reversible. (Codex works the same way - see the Codex section above.)

$ idleai patch-cursor # ✶ line inside Cursor's Composer panel
$ idleai patch-devin # inside Devin's (Windsurf) Cascade panel
# fully quit + reopen the app · undo: idleai unpatch-cursor | unpatch-devin

Two honest caveats. An app update overwrites the patch - just run it again. And patch-cursor ad-hoc re-signs Cursor.app to launch it (the files restore byte-identical, the original signature does not - reinstall Cursor to fully restore it). The Claude desktop app has its own reversible node patch.mjs in clients/claude-desktop-inject.

Every impression and click credits your balance instantly at the platform revenue share - up to 50% of what the advertiser paid, to the micro-dollar. The dashboard shows today's earnings, lifetime totals, your streak and level (Bronze → Silver → Gold → Diamond), and a ledger entry for every movement.

Device tokens are managed under Connect your tools - one per device, revocable individually, masked after creation. A token can only earn for its owner; it cannot read payout details or move money.

A view pays after 5 continuous seconds on screen. A click pays 50× a view, once per minute per campaign. Daily view caps and human-reviewed creatives keep the rates honest for both sides.

Earning needs only an email. Money leaving needs a verified human: confirm your identity with Google or GitHub and add your address in the verify wizard. No SMS, no documents.

Cash out from $5.00, from the dashboard. Pick a payout method in account setup first - the rails available depend on the deployment:

• →Stripe - bank transfer via Stripe Connect; finish the Express onboarding once, then payouts land in your bank.
• →PayPal - paid to your PayPal email.
• →UPI / bank (Razorpay) - for Indian accounts.

A cash-out escrows the amount into a pending request you can track from pending to paid; the ledger records every step. Serving and payouts pause when the IP country doesn't match your declared country or a VPN is detected - clients show the reason, never a silent ban.

Sign up as an advertiser and complete your company profile first - work email on your company domain, website, LinkedIn and a short about. Creatives are blocked from serving until the profile is complete and an admin has approved the ad.

Campaigns pay per verified 5-second view at your rate ($ per 1k views); clicks are the only premium event, at 50× a view. Target one of 59 countries or go global. There is no winner-take-all auction - every approved campaign gets airtime, and your rate sets your share.

Takeovers buy exclusivity: for a booked window (1 to 6 hours, $25.00/hour per country) your ad is the only one shown in that country, until the window ends or your credits run out.

Creatives are one line. They may end with ↗ - clients strip it and render their own accent arrow, so the line looks native on every surface. Every link is UTM-tagged automatically (utm_source=idleai), so conversions attribute cleanly in your analytics.

Campaigns spend from a prepaid wallet. Deposit by card via Stripe, by PayPal, or by UPI via Razorpay - whichever rails the deployment has enabled show up on the deposit form. Local dev runs use simulated deposits.

Budgets are escrowed per campaign: you are only charged when a developer actually watched your line for the full five seconds. Cancel a campaign anytime and the undelivered budget returns straight to your wallet. Every charge, escrow and refund is an auditable ledger entry.

Every client follows the same non-negotiable rules:

• →A view pays only after 5 continuous seconds actually on screen; the server refuses anything faster than 4 seconds apart.
• →Hidden tabs, unfocused editor windows and backgrounded assistant apps never serve.
• →After the response ends the ad may linger briefly (admin-set, default 30s) or until you start typing - whichever comes first.
• →Geo guard: serving stops when the IP country doesn't match the declared country or a VPN is flagged, with the reason shown on the line.
• →Every client has a visible pause and a one-step uninstall.

Device tokens are revocable per device and masked after creation. Storage keeps only sha256 hashes - the full token exists exactly once, in the creation response. In the browser extension the token lives in the service worker and never enters page contexts.

Per-user rate limits back the business pacing: 240 serves and 120 events per minute, then 429. CORS is enabled only on the four Bearer-auth client endpoints - token auth, no cookies.