Set up Kubit with your coding agent

The Kubit plugin for Claude Code wires Kubit into your repo for you. Its /kubit-integrate skill finds your existing tracing setup, creates or selects a workspace, writes the API key to your env file and adds the Kubit SDK. It shows a diff before every file it changes. Use this page if you work in Claude Code, if your agent is in Node or TypeScript, or if you already send traces to Langfuse or Braintrust. For a plain Python app, the Quickstart is just as fast by hand.

Before you start

Claude Code installed
A Kubit account
Your agent’s repo checked out, with its dependencies installed
For Node: OpenTelemetry JS SDK v2 or no OpenTelemetry yet. @kubit-ai/otel needs @opentelemetry/sdk-trace-base, @opentelemetry/sdk-trace-node and @opentelemetry/resources at ^2.0.0.

Steps

Install the Kubit plugin

# TODO(eng): exact install command, e.g. claude plugin marketplace add … && claude plugin install kubit

The plugin adds the Kubit MCP server and seven skills to Claude Code.

In Claude Code, run /mcp, pick the Kubit server and complete the browser sign-in. This is a one-time OAuth sign-in. Until it’s done, every Kubit tool call fails with an auth error.

Run /kubit-integrate in your repo

/kubit-integrate

The skill scans the repo and tells you what it found before it changes anything. Then it walks you through the choices in the next section.

Review each diff

The skill shows a diff for every file it writes or edits: the env file, the bootstrap file and your entrypoint. Approve or reject each one.

Run the verification command

The skill ends with three lines: which workspace and env file it used, where the Kubit wiring went, and a command that sends a hello-kubit test span. Run that command.

What /kubit-integrate does

Detection

The skill looks for tracing tools on two axes.

Axis	What it detects	What it does
Sink (where traces go today)	Langfuse, Braintrust	Adds `KubitSpanProcessor` next to the sink’s processor. Your sink keeps receiving every span.
Source (what creates spans)	Vercel AI SDK, OpenTelemetry GenAI instrumentation, LangChain	With no sink, calls `configure()` so Kubit is the only exporter for those spans.

If it finds more than one sink, it asks you to pick one.

Workspace and API key

The skill offers to create a new workspace, switch to another one or use your current one. Creating a workspace takes about 30 seconds. It detects your timezone for the workspace and falls back to UTC. It then mints an ingestion key, or takes one you paste, and writes KUBIT_API_KEY=<key> to .env.local or .env. The key goes only into that file. If no env file can be written, it prints an export KUBIT_API_KEY=… line for you to run.

Wiring

What it finds	What it writes
One file that already creates a `TracerProvider` or `NodeSDK`	Merges Kubit into that file
Several candidate files	Asks which one your agent’s traces go through
No provider yet	A bootstrap file (`kubit_instrumentation.py` or `kubit-instrumentation.ts`) plus an import as the first line of your entrypoint

For a Next.js app with the Vercel AI SDK, the bootstrap file is instrumentation.node.ts.

Constraints

Constraint	Details
OpenTelemetry JS SDK `^1.x`	Not supported. The skill refuses to install until you upgrade to `^2.0.0`.
Langfuse below v3 with LangChain	Not supported. `from langfuse.callback import CallbackHandler` (Python) or `langfuse-langchain` (JS) sends spans outside OpenTelemetry. Upgrade to `langfuse >= 3` (`from langfuse.langchain import CallbackHandler`) or `@langfuse/langchain`.
LangChain with Braintrust’s callback handler	Kubit doesn’t receive LangChain spans on this path. The skill offers the OpenTelemetry-native alternative (`opentelemetry-instrumentation-langchain`), which needs `wrapt<2`. Verified end to end on Python only.
Next.js with Vercel AI SDK	Next.js parents AI spans on an HTTP route span that Kubit’s default filter drops, so no traces arrive. Wrap each top-level `streamText`, `generateText`, `generateObject`, `streamObject` and `embed*` call in `context.with(ROOT_CONTEXT, () => …)` from `@opentelemetry/api`. The skill tells you this but doesn’t edit route handlers.

Other Kubit skills

Skill	Use it to
`/kubit-connect`	Pick or switch the organization and workspace for this conversation
`/kubit-integrate`	Wire Kubit into a repo (this page)
`/kubit-inspect`	Find and drill into users, sessions, traces and spans
`/kubit-report`	Build or open funnels, flows, retention and query reports
`/kubit-blame`	Map a trace regression to the commit that likely caused it
`/kubit-help`	Ask what Kubit can do or reach support
`/kubit-update`	Update the Kubit plugin

Using Cursor, Codex or another agent

Without the plugin, give your agent the page that matches your stack and let it follow the steps:

Add Kubit tracing to this repo. Follow https://learn.kubit.ai/send-traces/python.md exactly.
Read KUBIT_API_KEY from .env. Show me the diff before writing any file.

Get the API key first, as described in the Quickstart.

Verify

After running the skill’s verification command, ask Claude Code:

“Show me traces from the last 15 minutes”

The result lists a trace whose root span is hello-kubit.

If it fails

Symptom	Cause	Fix
Every Kubit tool call returns an auth error	MCP sign-in not done	Run `/mcp`, pick the Kubit server and sign in
Skill stops at the version check	Repo pins OpenTelemetry JS `^1.x`	Upgrade the `@opentelemetry/*` packages to `^2.0.0`, then rerun
Test span arrives, Next.js AI spans don’t	AI spans are parented on a dropped HTTP span	Wrap AI SDK calls in `context.with(ROOT_CONTEXT, …)`

More checks are in Is my data flowing?.

Next steps

Span attributes: add user and session IDs.
Concepts: what Atlas does with your spans.

Start here

Get started

Send traces

Bring your own warehouse

Set up Kubit with your coding agent

Before you start

Steps

What /kubit-integrate does

Detection

Workspace and API key

Wiring

Constraints

Other Kubit skills

Using Cursor, Codex or another agent

Verify

If it fails

Next steps

​Before you start

​Steps

​What /kubit-integrate does

​Detection

​Workspace and API key

​Wiring

​Constraints

​Other Kubit skills

​Using Cursor, Codex or another agent

​Verify

​If it fails

​Next steps

Before you start

Steps

What /kubit-integrate does

Detection

Workspace and API key

Wiring

Constraints

Other Kubit skills

Using Cursor, Codex or another agent

Verify

If it fails

Next steps