Getting started

1. Register your package

Sign in with GitHub, Google, or GitLab and register your package from the dashboard: name, repo URL, package type (CLI, MCP server, agent framework…), language, and categories. You'll receive a publisher key — shown exactly once, stored hashed on our side. 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.

2. Install the SDK

npm install @opencrater/sdk

Node ≥ 18, zero hard dependencies. The SDK is fail-silent by design: a hard ≤500ms network budget, no retries, and every public call is wrapped — an OpenCrater outage can never break your tool.

3. Show a sponsor card

import { sponsor } from "@opencrater/sdk";

// at a natural pause — end of a run, after output
await sponsor.show({
  publisherKey: process.env.OPENCRATER_KEY ?? "ock_live_…",
  packageName: "your-tool",
  placement: "generic",
});

The SDK respects the frequency cap (default: one card per machine per 10 minutes), skips non-TTY and CI environments, honors NO_COLOR, and renders something like this:

╭─ sponsor · opencrater.to ────────────────────────────────╮
│                                                          │
│ Tailscale — SSH that just works                          │
│ Zero-config WireGuard mesh for your dev machines. Free   │
│ for personal use.                                        │
│ → tailscale.com/ssh                                      │
│                                                          │
╰──────────────────────────────────────────────────────────╯

4. Claude Code hooks

If your package is an MCP server or runs alongside Claude Code, you don't need to touch your code at all. The CLI installs hook entries that render cards at the events you enabled in the dashboard (SessionStart, SessionEnd, Stop, PostToolUse, Notification):

npx opencrater hooks install
# → writes hook entries to .claude/settings.json
# → renders from a preloaded ad pool — zero latency at hook time

npx opencrater hooks uninstall   # removes them cleanly

Hooks read from a small preloaded pool fetched at session start, so nothing blocks the hot path. Codex and other harnesses use the same mechanism under the codex and generic placements.

5. End-user opt-out

Your users always stay in control — please link this section from your README. The first card on any machine is preceded by a one-time notice explaining where it comes from and how to turn it off:

# disable everywhere, permanently (env var)
export OPENCRATER_DISABLE=1

# or persist a per-machine opt-out
npx opencrater off

# re-enable later
npx opencrater on

• Cards never render in CI, scripts, or non-TTY pipes.
• No prompts, code, or credentials are ever collected — only an anonymous random install ID (resettable, in ~/.config/opencrater/state.json).
• A remote kill switch lets us stop all rendering instantly.

FAQ