Documentation

Quickstart (one command)

If you just want Blips in your own Claude Code / Codex / Antigravity sessions — or want to see exactly what your users would see:

npx opencrater on

The installer detects which CLIs you have, registers hooks for each (all events — rendering is gated separately, see placements), installs a local runtime under ~/.config/opencrater/runtime so hooks never race a cold npx cache, and prints the opt-out. Everything it does is undone by npx opencrater off.

Registering a package

1. Sign in at opencrater.to/signup (GitHub, Google, or GitLab).
2. Dashboard → packages → register: name, type (MCP server, CLI, agent, library, API service, SaaS, GitHub repo, and more), language, categories. Type and categories matter — they feed both targeting and Blips relevance.
3. You get a serve key (ock_…) — a public attribution token you can always view again on your dashboard. It attributes impressions to your package so you get paid; it cannot spend anything, so shipping it inside your installer is expected and safe. Rotate it any time.
4. Set a funding fallback URL (e.g. your GitHub Sponsors page) — it renders as the card whenever no campaign fills, so the slot always works for you.
5. Wire your integration (SDK below, or hooks if your users run agent CLIs), pick your placements, and add a README line disclosing Blips and the opt-out.

npx -y -p opencrater opencrater-hook \
  --key ock_YOUR_KEY --package your-package --host claude_code

Hosts & hook events

Cards render through each CLI's native hook system. The SDK registers all of a host's events as triggers; whether a given event renders is your placement selection. Event sets below are source-verified per host:

How rendering actually works: the hook is only a trigger. It spawns a detached painter that draws the card straight onto the terminal device as a top-right overlay — hosts capture hook stdout, so printing was never an option. The painter repaints through output storms, shows a live auto-dismiss countdown, and cleans up after itself. Concurrent hook bursts (an agent firing six tools at once) collapse to exactly one card via a machine-wide render slot.

Choosing placements

In the dashboard, each package selects which hook events may render, per host. Recommendations exist because attention has edges: session start and turn end are natural seams; PreToolUse fires constantly and would wear your users out. Selecting nothing keeps the recommended defaults. The serve response carries your selection to every installed SDK (allowedPlacements), cached per package + host.

Advertisers independently target placements — a card renders only where both your selection and their targeting agree.

Earnings & payouts

• You earn a share of every Blips shown on your surface and every confirmed click — clicks are the headline, impressions add a small per-view earning on top. Clicks confirm after the fraud window (pending → available).
• Dashboard → earnings shows impressions, clicks, CTR, dismissal rate, and revenue per package, with daily charts. High dismissal rates come with concrete advice — they usually mean too many placements or a mismatched audience.
• Withdraw available balance as USDC on Base or Ethereum. Small amounts auto-pay; larger ones process from the payout queue. Chain transactions are public and irreversible — check addresses.
• Your earnings can also fund your own campaigns directly (see below) — promote your package with the money it makes.

Campaign anatomy

A campaign is: a name (the card's “Sponsored ·” brand line — use your product name), a category (primary + optional secondary), a CPC bid, budgets (total, optional daily pace cap), targeting, and one creative. Create it at dashboard/promote — every input has inline help, a recommendation, and an example, plus a live terminal preview that renders exactly what ships, switchable between Claude Code, Codex, and Antigravity frames.

Lifecycle: draft → submit (funds lock into escrow) → in_review → approved → active → paused / edited (back to review) / cancelled (unspent escrow refunds instantly) / completed.

Blips formats (including audio)

Targeting

Empty axes mean “no constraint”. Relevance also flows the other way: the engine reads your title, body, categories, and keywords, so well-written copy targets itself.

Bidding & the auction

Your CPC is a bid, not a price tag. Each serve ranks eligible campaigns by bid × predicted CTR × relevance — a relevant Blips with a modest bid routinely beats an expensive irrelevant one. Relevance blends the session's sanitized topics, the install's decaying interest profile (7-day half-life), and the surface itself — the package's type and categories. Budget pacing spreads delivery across the day and the campaign's flight; dismissals feed back as a negative signal. Start at $0.15–$0.30 for developer tools and raise for volume.

Escrow billing

1. Submit — the campaign's full budget moves from your balance into escrow locked to that campaign.
2. Serve — clicks accrue against the campaign during the day, alongside a small flat per-impression fee for every Blips shown. The dashboard shows the accrued amount as your pending debit, with the next settlement time.
3. Settle — once every 24 hours, accrued clicks and per-impression fees debit the escrow. Fraud-held clicks never bill.
4. Cancel — any time. Today's accrued clicks settle immediately; the entire unspent remainder returns to your balance in the same transaction.

Review lifecycle & editing

Every creative is human-reviewed before serving (see the network policy for standards). Rejections come with a written reason you see verbatim; fix and resubmit from the campaign page — funding stays locked, no re-charge. Audio creatives are listened to in full before approval.

Editing a running campaign: the edit button on your campaign opens the same editor, but saving takes the campaign off the air immediately and back through review (a confirmation dialog spells this out first). Budget, stats, and clicks-so-far are untouched.

The SDK

Any card on a machine shares the same local files (state, cooldowns, audio caps), so it behaves like one polite machine no matter how many tools enable cards.

import { sponsor } from "opencrater";

await sponsor.show({
  publisherKey: "ock_YOUR_KEY",
  packageName: "your-tool",
  placement: "SessionEnd",
});

Commands

Environment variables

Politeness rules (enforced in code)

Local files

Everything lives under ~/.config/opencrater/: state.json (install ID, caps, caches), blocked-ads.json (dismiss cooldowns), reported-ads.json (⚑-reported campaigns — permanent local blocks), recent-renders.json (repeat cooldowns), audio-plays.json (audio window), last-ad.json (replay), runtime/ (the local SDK copy hooks prefer over npx; self-updates daily). Delete the directory for a complete reset. None of these files are ever uploaded — the privacy policy documents each one.

Compute wallet

The same Blips that pay maintainers also pay you, the developer running the terminal — in AI compute instead of cash. See cards while you code, bank weekly compute, and when you hit your Claude or Codex limit, spend that compute to keep going. Attention in, compute out.

It's a loop: opencrater login links this machine to your wallet, the hook credits you for the cards you see, and opencrater claude runs your coding agent on the balance. Your balance lives on your compute wallet.

Earning compute

1. npm i -g opencrater then opencrater login — opens a browser, you paste a one-time token; this machine is now linked to your wallet (the token never expires).
2. opencrater on wires the hooks (and pins a fast local runtime). Keep coding — the cards that appear at natural pauses now credit you.
3. New accounts get a one-time starter grant the moment you log in, so you can try opencrater claude immediately.
4. Each ISO week your earnings from the impressions + clicks you saw (capped, plus a starter for new devs) are paid into your available balance, which rolls over. Unused compute expires only after 30 days untouched (oldest-first).

Check it any time with opencrater balance or on the dashboard. If you're signed in, Blips attribution always goes to your dev wallet — it takes precedence over any publisher key in the installed hook.

Spending it · opencrater claude / codex / grok

When you hit your weekly Claude, Codex or Grok limit, launch that same agent on OpenCrater compute:

opencrater claude               # launch Claude Code on your earned compute
opencrater claude -c            # resume the exact Claude session your limit cut off
opencrater codex                # launch Codex on your earned compute
opencrater codex -c             # resume your last Codex session
opencrater grok                 # launch xAI's Grok CLI on your earned compute
opencrater grok -c              # continue your last Grok session

The compute cards

Four OpenCrater system cards (not Blips — they carry no advertiser and cost nothing) guide you through the loop. They render on their own cadence, deliberately independent of the Blips frequency:

The limit/reset cards rely on the host writing its capacity state to disk. Claude Code does (so they're precise there); Codex only persists plan dates, so on Codex the backup/usage/depleted cards still work but the exact limit/reset cards don't fire.

Compute FAQ

Compute troubleshooting

Troubleshooting