BuilderPerks

Content-blind sponsored devtool perks for Codex, Claude Code, Cursor, terminal, IDE, and AI coding agent workflows.

Try the proof block first:

npx -y builderperks@latest proof

It prints a shareable terminal proof block showing the current sponsored-perk status, privacy posture, and beta estimate wording without reading prompts, code, paths, command output, or terminal transcripts.

Then install for Codex:

npx -y builderperks@latest install codex --verify
npx -y builderperks@latest codex

BuilderPerks is terminal-first. Sponsored perks are labeled, optional, and can be disabled anytime. Credits are estimated while beta settlement and reconciliation are still in progress.

Exact local lanes work through a Claude Code statusLine command, a conservative terminal wrapper, or the builderperks launch -- ... wait-state launcher. The launcher detects simple thinking/loading lines locally and can show a labeled sponsor line without sending command output upstream. ChatGPT and Claude chat use supported app, connector, or browser-card surfaces; BuilderPerks does not claim to replace host-controlled native thinking spinners.

Quick start

Proof-first:

npx -y builderperks@latest proof

npx-first Codex setup:

npx -y builderperks@latest install codex --verify
npx -y builderperks@latest codex

The first command installs BuilderPerks for Codex and verifies setup in one pass. It also drops a local builderperks wrapper in ~/.builderperks/bin. builderperks codex starts Codex in terminal-first mode with scrollback preserved. Browser overlay is opt-in with builderperks codex --overlay browser.

Optional global npm install:

npm install -g builderperks
builderperks install codex --verify
builderperks verify codex
builderperks codex

Verify or debug any time:

builderperks refresh
builderperks statusline --respect-frequency
builderperks readiness codex
builderperks verify codex
builderperks doctor codex
builderperks test-render
builderperks version doctor
builderperks repair path
builderperks ads status
builderperks recap
builderperks privacy doctor

Windows / PowerShell should use the same npx command above. The .sh files installed under ~/.builderperks are optional Unix shell helpers for macOS, Linux, WSL, or Git Bash.

If builderperks resolves to an old global install or stale npx cache, run builderperks version doctor. It reports npm latest, hosted tarball version, local shim version, resolved command path/version, and the exact PATH fix. Use builderperks repair path to preview the shell profile patch, or builderperks repair path --apply to append it.

For automation, avoid running multiple npx -y builderperks@latest ... commands in parallel with the same npm cache. If npm reports cache rename/chmod errors, retry with an isolated cache:

npm_config_cache="$(mktemp -d)" npx -y builderperks@latest verify codex

Runtime host allowlist:

• https://builderperks.netlify.app for placement, render, tracking, and support APIs.
• http://127.0.0.1:* or http://localhost:* for the local Codex companion overlay.
• Do not allow arbitrary third-party script hosts in terminal, IDE, or Codex surfaces.

Trust notes:

• BuilderPerks sends broad keywords/categories only, not prompts, source code, file paths, command output, terminal transcripts, secrets, or personal data.
• Production statusline mode is cache-first: ~/.builderperks/statusline.sh reads ~/.builderperks/statusline.last or ~/.builderperks/last-perk.txt and paints immediately. It does not log an impression or block on the network.
• builderperks refresh is the network step that updates the local cache. builderperks statusline remains proof mode for a live one-line render check.
• The overlay proof ledger is local at ~/.builderperks/impressions.jsonl.
• Local frequency caps live at ~/.builderperks/frequency.json; they prevent repeated sponsored units from feeling spammy.
• BUILDERPERKS_ADS=0 builderperks codex disables sponsored units without disabling utility commands.
• Commands print a short setup or diagnostic line if the network or API is unavailable.
• ChatGPT and Claude chat use supported cards/connectors; BuilderPerks does not claim native spinner replacement in host-controlled UIs.

Fallback/internal beta only, when npm registry access is blocked or you are testing a pinned beta tarball:

npx -y https://builderperks.netlify.app/builderperks-0.1.51.tgz install codex --verify
npx -y https://builderperks.netlify.app/builderperks-0.1.51.tgz doctor codex

builderperks setup registers a publisher surface, saves ~/.builderperks/config.env, installs optional shell helpers, optionally writes Claude Code statusLine, and prints cross-platform test/debug commands. It sends only broad keywords/categories, not prompts, source code, file paths, command output, or secrets.

One-command aliases:

builderperks install codex --verify
builderperks install claude
builderperks install terminal

Codex companion overlay:

builderperks codex --overlay browser

builderperks codex is the recommended command for Codex. It starts terminal-first and launches Codex with --no-alt-screen. Browser overlay is opt-in with builderperks codex --overlay browser. It is not a native Codex spinner replacement; native spinner replacement is no. Turn-aware integration is only possible if a future Codex app-server/native wait-card path exists. It does not read prompts, source code, command output, file paths, or terminal transcripts.

Advanced path:

npx -y builderperks@latest overlay -- codex

Render proof:

builderperks test-render
builderperks doctor codex

test-render starts a short local overlay session, fetches the overlay page, posts the browser render beacon, and confirms a Level 3 local ledger row. It is the quickest way to prove the overlay is reachable and impressions are render-confirmed.

Local controls:

npx -y builderperks@latest ads off
npx -y builderperks@latest ads on
npx -y builderperks@latest ads status
npx -y builderperks@latest pause --duration 1h
npx -y builderperks@latest pause today
npx -y builderperks@latest resume
npx -y builderperks@latest mute sponsor Sentry
npx -y builderperks@latest block-category crypto
npx -y builderperks@latest privacy
npx -y builderperks@latest privacy doctor
npx -y builderperks@latest privacy sample-request
npx -y builderperks@latest privacy firewall
npx -y builderperks@latest recap

BuilderPerks writes a local render ledger to ~/.builderperks/impressions.jsonl only after a card or line is actually rendered locally. This is proof/debug data, not advertiser billing, publisher payout proof, or fraud reconciliation.

Agent prompt:

Install BuilderPerks with npx -y builderperks@latest install codex --verify, run builderperks verify codex, run builderperks codex, run builderperks readiness codex or builderperks doctor codex if setup is unclear, and run builderperks test-render for local render proof. Allow only https://builderperks.netlify.app plus http://127.0.0.1:* or http://localhost:* for the local overlay. Use broad keywords only; do not send prompts, source code, paths, command output, terminal transcripts, secrets, or personal data.

Existing-token path after you already have a publisher id and token:

npx -y builderperks@latest init --publisher-id pub_x --publisher-token bp_pub_token --install-claude
builderperks refresh
~/.builderperks/statusline.sh
builderperks doctor
builderperks launch -- npm test

builderperks init writes ~/.builderperks/config.env, installs optional ~/.builderperks/statusline.sh and ~/.builderperks/run.sh Unix shell helpers, and can write Claude Code statusLine with --install-claude. Restart Claude Code or open a new Claude Code session after installing. The status-line command sends only broad workflow keywords and category preferences to the BuilderPerks API. It does not send raw prompts, source code, secrets, paths, command output, or personal data.

Replace simple wait-state lines in a terminal command:

npx -y builderperks@latest launch -- npm test
npx -y builderperks@latest launch -- codex

For interactive CLIs, launch auto-enables PTY mode in a real macOS/Linux terminal when script(1) is available. Use --no-pty to disable that fallback or --pty to request it explicitly:

npx -y builderperks@latest launch --pty -- codex
npx -y builderperks@latest launch --no-pty -- npm test

builderperks launch -- ... runs your command and locally watches output for simple thinking/loading lines. When it sees one, it prints a labeled sponsored line or, for visible interactive terminal wait words, skins the wait word into a compact label such as Perk available: estimated credit pending settlement. It does not send command output to BuilderPerks.

Conservative wrapper, when you do not want local output inspection:

npx -y builderperks@latest run -- npm test

builderperks run -- ... runs your command normally and prints a labeled sponsor line to stderr at safe intervals. It does not inspect command output. The public npm setup registers an install profile, stores the one-time token in ~/.builderperks/config.env, and installs optional shell helpers, so terminal and Codex-style CLI workflows can be wrapped from a clean machine. The hosted tarball path remains available as a fallback for registry cache issues.

Advanced stream checks:

npx -y builderperks@latest creative --format json
npx -y builderperks@latest creative --format terminal-card
npx -y builderperks@latest creative --format codex-wait-card
npx -y builderperks@latest test-rotation --count 20

creative --format json returns the structured wait-card payload: sponsor, title, body, CTA, tracked click URL, impression id, demand source, fallback flag, and estimated unpaid credit. terminal-card, overlay-card, and codex-wait-card expose render-ready variants for terminal, companion overlay, and future native wait-slot work. test-rotation samples up to 20 creatives and reports unique placements, unique sponsors, unique copy, source breakdown, malformed compact-copy count, backfill count, repeated sponsors, fallback use, and a pass/warning verdict. If only a single SmartLink is eligible, BuilderPerks will say so instead of pretending it has fresh written third-party copy.

Where the sponsored line appears

| Workflow | What works now | | --- | --- | | Terminal | builderperks statusline is live proof mode. ~/.builderperks/statusline.sh is production statusline mode and reads the cache hot path. | | Claude Code | Set statusLine.command to ~/.builderperks/statusline.sh after install. | | Codex | npx -y builderperks@latest install codex --verify, then builderperks verify codex, then builderperks codex. Use builderperks readiness codex, builderperks doctor codex, and builderperks test-render for diagnostics and render proof. Advanced: builderperks launch -- codex can skin visible wait words when Codex emits them through the terminal stream. | | Claude CLI / tests | npx -y builderperks@latest launch -- claude or any long-running command. Launch mode can replace simple spinner/loading lines when a command exposes them. | | VS Code / Cursor | Add a shell task that runs ~/.builderperks/statusline.sh or launches a task with npx -y builderperks@latest launch -- .... | | ChatGPT app | Use the hosted MCP endpoint https://builderperks.netlify.app/mcp for first proof, or chatgpt-app/ for a self-hosted Node deployment. It cannot replace ChatGPT's native thinking spinner. | | Claude Desktop | Use claude-desktop-extension/ to build public/builderperks-claude-desktop.mcpb. It shows a supported conversation card; Claude Code statusLine remains the exact local lane. | | Claude web | Use the browser companion card until Claude exposes a supported web app/statusline API. | | Browser companion | Use the beta Chrome companion for a dismissible card in ChatGPT or Claude browser sessions. |

Truth table

| Capability | Supported | | --- | --- | | Statusline sponsored line | yes | | Stream-skin visible wait text through builderperks launch -- <command> | yes | | Codex terminal-first launch through builderperks codex | yes | | Browser overlay through builderperks codex --overlay browser | opt-in | | Native private Codex thinking spinner replacement | no |

Chrome Web Store beta

The Chrome extension is a browser companion, not an ad-only spinner replacement. It must remain opt-in and user-controlled for Chrome review.

Manual ZIP install is a beta tester path, not the normal user path. Label it clearly:

1. Download public/builderperks-extension-beta.zip.
2. Unzip it.
3. Open chrome://extensions.
4. Turn on Developer Mode.
5. Click Load unpacked.
6. Select the unzipped BuilderPerks folder.
7. Pin the extension, open ChatGPT or Claude, enable BuilderPerks, and click Show first card now.

Local QA:

npm run smoke:extension
npm run build
unzip -l public/builderperks-extension-beta.zip

The package must include manifest.json, content.js, content.css, popup.html, popup.js, popup.css, and icon16.png, icon32.png, icon48.png, icon128.png.

Submission defaults:

• Release as an unlisted beta first.
• Store single purpose: "Shows opt-in, locally matched devtool perks during active AI build sessions."
• Permission justification: storage stores local settings/consent/API URL/daily caps; activeTab lets the popup send the manual first-card command to the current ChatGPT or Claude tab; host permission is limited to https://builderperks.netlify.app/* for fetching placements and reporting opt-in relevance events.
• Privacy URL: https://builderperks.netlify.app/privacy.
• Do not upload browser ad tags, push prompts, popunders, auto-redirects, or remote executable code.
• Screenshots should show the first-run enable gate, the popup settings, and one clearly labeled BuilderPerks card on a test ChatGPT/Claude build session.

Claude Code status line

{
  "statusLine": {
    "type": "command",
    "command": "~/.builderperks/statusline.sh"
  }
}

Claude Desktop one-click bundle

Build and test the local MCPB bundle:

npm run claude:check
npm run claude:pack

The bundle is written to:

public/builderperks-claude-desktop.mcpb

Open it in Claude Desktop Extensions, keep the default API URL, optionally enter a BuilderPerks publisher ID/token, then ask Claude to show a BuilderPerks waitline. This is a conversation-card lane, not native thinking-indicator replacement.

Hosted ChatGPT App endpoint

The live site exposes a first-party MCP endpoint for ChatGPT Developer Mode:

https://builderperks.netlify.app/mcp

Check the advertised metadata:

curl -fsS https://builderperks.netlify.app/api/chatgpt-app

Validate the live MCP tools and widget resource after each deploy:

npm run chatgpt:netlify-check

This hosted lane logs impressions as the BuilderPerks first-party ChatGPT app. User revenue-share still belongs to the terminal, Claude Code, Codex, IDE, and agent workflow profiles created by the installer or CLI.

Provider activation

The deployed stream can serve BuilderPerks seed/direct approved placements and a reviewed approved-partner offer feed now. builderperks doctor and /api/provider-status are the source of truth for which third-party or partner lanes can serve.

The fastest compliant activation path for a brand-new product is a reviewed direct, affiliate, or partner offer list. This is real fill, but it must be labeled as an approved partner/direct feed rather than as an external ad network.

Create offers.json. This template is intentionally not production-valid; replace every placeholder with a reviewed, approved sponsor and real destination URL before validating:

{
  "offers": [
    {
      "company": "Example Devtool",
      "headline": "Credits for builders shipping with agents",
      "body": "A relevant offer for AI app builders using terminal and IDE workflows.",
      "cta": "Claim offer",
      "url": "https://example.com/?ref=builderperks",
      "audience": "AI builders",
      "targetTools": ["Claude", "Codex", "Cursor", "Terminal"]
    }
  ]
}

Validate and normalize after replacing the placeholders:

npm run validate:offer-feed -- ./offers.json > /tmp/builderperks-approved-offers.json

Set inline production env when no hosted feed exists yet:

BUILDERPERKS_APPROVED_PARTNER_FEED_NAME="Approved direct/affiliate offer feed"
BUILDERPERKS_APPROVED_PARTNER_FEED_JSON="$(cat /tmp/builderperks-approved-offers.json)"

Or point to a hosted approved JSON feed:

BUILDERPERKS_APPROVED_PARTNER_FEED_URLS=https://example.com/builderperks-approved-offers.json

After deploy, /api/provider-status should report an approved partner feed and /api/ad-stream should be able to return demand.source=approved_partner.

Netlify operator command after the feed has been reviewed and normalized:

netlify env:set BUILDERPERKS_APPROVED_PARTNER_FEED_NAME "Approved direct devtool offer feed" --context production
netlify env:set BUILDERPERKS_APPROVED_PARTNER_FEED_JSON "$(cat /tmp/builderperks-approved-offers.json)" --context production
netlify deploy --prod
curl -fsS 'https://builderperks.netlify.app/api/provider-status?includeMapped=1' | jq '.summary.approvedPartnerFeeds'
curl -fsS 'https://builderperks.netlify.app/api/ad-stream?publisherId=PUB&publisherToken=TOKEN&surface=terminal&context=deploying%20an%20AI%20app&keywords=typescript,postgres&blockedCategories=adult,gambling&format=statusline' | jq '.demand.source,.render.statusLine'

Fast CPA/affiliate smartlink providers can also be configured with provider-specific URLs such as BUILDERPERKS_CPALEAD_SMARTLINK_URL, BUILDERPERKS_CPAGRIP_SMARTLINK_URL, BUILDERPERKS_MYLEAD_SMARTLINK_URL, BUILDERPERKS_ADSTERRA_SMARTLINK_URL, BUILDERPERKS_MONETAG_SMARTLINK_URL, BUILDERPERKS_PROPELLERADS_SMARTLINK_URL, BUILDERPERKS_BIDVERTISER_SMARTLINK_URL, BUILDERPERKS_ADMAVEN_SMARTLINK_URL, or restricted BUILDERPERKS_EXOCLICK_DIRECT_URL.

Every provider-specific URL still requires the matching approval flag, for example:

BUILDERPERKS_CPALEAD_SMARTLINK_URL=https://...
BUILDERPERKS_PROVIDER_APPROVED_CPALEAD=1

Push/pop SmartLink networks such as Adsterra and Monetag are beta backfill. New CLI installs default to push_pop so users see live ads immediately, while adult and gambling remain blocked. Direct sold developer ads should replace this default once BuilderPerks has enough user volume.

That flag means the operator verified account acceptance, terms, disclosure, and category fit. Restricted categories stay blocked by default.

Do not paste browser ad tags, popunder scripts, push prompts, content lockers, or auto-redirect code into terminal surfaces. BuilderPerks only streams a disclosed sponsored line with a user-clicked URL.

P1 readiness check

Run the strict launch-readiness check after committing the P1 artifacts, deploying the ChatGPT MCP app, publishing npm, reviewing proof sessions, and configuring a clean approved offer feed. By default it validates the live hosted ChatGPT MCP endpoint at https://builderperks.netlify.app:

npm run p1:readiness

Override the host only when testing a separate ChatGPT MCP deployment:

BUILDERPERKS_CHATGPT_APP_URL=https://YOUR-CHATGPT-MCP-HOST npm run p1:readiness

The check intentionally fails while any P1 blocker remains: untracked deploy files, missing npm auth, unpublished current builderperks package, a broken public npx builderperks entrypoint, missing clean approved partner/direct feed, or zero verified workflow sessions.

Review proof sessions only with operator access and evidence:

BUILDERPERKS_ADMIN_KEY=... npm run proof:sessions -- list
BUILDERPERKS_ADMIN_KEY=... npm run proof:sessions -- approve proof-id
BUILDERPERKS_ADMIN_KEY=... npm run proof:sessions -- reject proof-id

Approve only sessions where the evidence shows one labeled sponsored line in a real terminal, Claude Code, Codex, IDE, agent, app, connector, or card workflow.

Subscription credits

Credits are estimated until revenue is real. Treat balances as pending BuilderPerks credits until advertiser/provider revenue, reversals, invalid-activity checks, and credit rules settle. Do not promise direct ChatGPT or Claude bill payment without a vendor-supported billing or reseller path.