Quick Start

Prompt Install is the default setup path. Use one prompt in your coding assistant to detect your stack, install the SDK, and wire tracing automatically.

ZappyBee Beta is free while we collect feedback. Fair-use monthly limits apply on trace/step ingest to prevent abuse. If you exceed limits, ingest endpoints return 429 with a reset time.

1. Create a project

Sign up, create a project, and copy your API key from Settings.

2. Prompt Install (Recommended)

Copy this prompt and run it in your coding assistant

Primary

Supports Claude Code, Codex, Cursor, Lovable, Antigravity, and generic coding agents.

Choose your coding assistant

Best for CLI-driven refactors in existing repos.

install-prompt.txt
You are Claude Code working directly inside my repository.

Goal:
Install ZappyBee tracing as fast as possible with zero product regressions.

Critical constraints:
1) Detect framework(s), language(s), runtime(s), and package manager(s) automatically.
2) Keep existing app behavior intact. No breaking changes.
3) Do NOT hardcode secrets. Use env vars only.
4) Do NOT commit or push anything.
5) At the end, output:
   - changed files
   - exact run command
   - exact smoke test command

Configuration:
- SDK package name: zappybee
- API key env var: ZAPPYBEE_API_KEY
- Base URL env var: ZAPPYBEE_BASE_URL
- Base URL value: https://tokencat-api-riuvb.ondigitalocean.app

Implementation tasks:
1) Detect stack
- Identify whether this repo uses TypeScript/JavaScript, Python, or both.
- Detect package manager preference from lockfiles/config:
  pnpm-lock.yaml > package-lock.json > yarn.lock > bun.lockb
- For Python detect toolchain:
  uv > poetry > pipenv > pip

2) Install dependencies
- If TS/JS exists, install zappybee with the detected package manager.
- If Python exists, install zappybee with the detected Python tool.
- If OpenAI or Anthropic SDKs are already present, keep using them.
- Do not remove existing dependencies.

3) Configure environment
- Add/update env examples so they include:
  ZAPPYBEE_API_KEY=
  ZAPPYBEE_BASE_URL=https://tokencat-api-riuvb.ondigitalocean.app
- If there is an app env loader, wire both vars there.
- Never place a real API key in source files.

4) Add SDK initialization
- Add one shared initialization location per runtime (TS and/or Python).
- Initialize with:
  apiKey from ZAPPYBEE_API_KEY
  baseUrl from ZAPPYBEE_BASE_URL (fallback to https://tokencat-api-riuvb.ondigitalocean.app if needed)

5) Add automatic tracing where possible
- If Anthropic/OpenAI clients are found, apply ZappyBee.wrap(client).
- Keep existing client options and behavior unchanged.

6) Add manual tracing for unsupported/custom flows
- Add one traced execution path with:
  startTrace -> startStep -> step.end -> trace.end
- Include model, prompt/completion tokens, status, output/error.
- Use try/catch/finally (or equivalent) so traces close on failures.

7) Add smoke test path
- Add a minimal script or command that triggers one traced run.
- Script should work locally without exposing secrets in code.
- Add clear comment on how to run it.

8) Validate
- Run existing build/typecheck/lint commands where available.
- Fix only issues introduced by your changes.

9) Final report
- Print:
  a) what was detected (framework/language/package manager)
  b) exact files changed
  c) install command(s) used
  d) run command
  e) smoke test command
  f) where to check traces in UI

Now apply the changes directly.

3. Manual SDK setup (Fallback)

Prefer to do it by hand? Use manual installation + snippets below.

bash
npm install zappybee

Or for Python:

bash
pip install zappybee

Keep secrets in ZAPPYBEE_API_KEY and ZAPPYBEE_BASE_URL.

typescript
import { ZappyBee } from "zappybee";

ZappyBee.init({
  apiKey: process.env.ZAPPYBEE_API_KEY || "tc_live_...",
  // Optional. Defaults to http://localhost:3001
  baseUrl: process.env.ZAPPYBEE_BASE_URL || "https://tokencat-api-riuvb.ondigitalocean.app",
});

4. Instrumentation pattern

Auto-wrap works for Anthropic and OpenAI. For Gemini, Grok, Mistral, Llama, DeepSeek, and anything else, use manual tracing.

typescript
import Anthropic from "@anthropic-ai/sdk";
import { ZappyBee } from "zappybee";

ZappyBee.init({
  apiKey: process.env.ZAPPYBEE_API_KEY || "tc_live_...",
  // Optional. Defaults to http://localhost:3001
  baseUrl: process.env.ZAPPYBEE_BASE_URL || "https://tokencat-api-riuvb.ondigitalocean.app",
});

const client = new Anthropic();
ZappyBee.wrap(client);

const msg = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 512,
  messages: [{ role: "user", content: "Hello!" }],
});
typescript
import { ZappyBee } from "zappybee";

ZappyBee.init({
  apiKey: process.env.ZAPPYBEE_API_KEY || "tc_live_...",
  // Optional. Defaults to http://localhost:3001
  baseUrl: process.env.ZAPPYBEE_BASE_URL || "https://tokencat-api-riuvb.ondigitalocean.app",
});

const trace = await ZappyBee.startTrace("my-agent");
const step = await trace.startStep("llm", "llm_call", { model: "gemini-2.5-pro" });

// ... call your provider here ...
await step.end({
  status: "success",
  model: "gemini-2.5-pro",
  output: result,
  promptTokens: 123,
  completionTokens: 456,
});
await trace.end({ status: "success" });

5. Verify traces in dashboard

  • Run your app or worker once after setup.
  • Trigger one agent request/job in your product.
  • Open Traces and confirm you see a new run with step timeline.
  • If missing, check env vars and ask your coding assistant to run the smoke test it created.

Support

Questions, feedback, or need higher beta limits? Email contact.support@zappybee.dev.