Skip to main content
The Kubit agent plugin wires Kubit into a Python or Node repo for you, from Claude Code or Cursor. Its /kubit-integrate skill finds your existing tracing setup, creates or selects an Agent workspace, writes the API key to your env file and adds the Kubit SDK (kubit-otel or @kubit-ai/otel). It shows a diff before every file it changes. Use this page if you work in Claude Code or Cursor, or if you already send traces to Langfuse or Braintrust. To wire Kubit by hand, use the Kubit SDK for Python, the Kubit SDK for Node or Manual OpenTelemetry. The Quickstart compares the three.

​
Before you start

  • Claude Code installed
  • Node.js 18+, for npx
  • A Kubit account. Sign-up needs an early-access link from Kubit or an invite from your organization. See Set up your organization.
  • Your agent’s repo checked out, with its dependencies installed
  • For Python: Python 3.9 or later
  • 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

1

Install the Kubit plugin

The installer asks two questions. For the runtime, pick Claude Code. For the location, pick Global (the default) to install user-wide, or Local to install into the current directory only. To skip both questions, run npx @kubit-ai/agent-plugin --runtime claude --global, or use --local in place of --global.The plugin adds the Kubit MCP server as kubit-agent and installs eight skills. Restart Claude Code, then run /kubit-help to check that the skills loaded.
2

Sign in to the Kubit MCP server

In Claude Code, run /mcp, pick kubit-agent 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. If a skill hits that error and gets a sign-in link, it opens the link in your browser and waits for you to finish.
3

Run /kubit-integrate in your repo

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.
4

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.
5

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. The skill doesn’t run the command itself. Run it in your terminal.

​
What /kubit-integrate does

​
Detection

The skill looks for tracing tools on two axes. 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. A workspace the skill creates starts on the default-otel extraction template. Switch it to default-agent in Data > Extraction, as described in Check the extraction mapping. 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

For a Next.js app with the Vercel AI SDK, the bootstrap file is instrumentation.node.ts. The skill always installs the Kubit SDK. With a sink, it adds KubitSpanProcessor (Node) or calls attach() (Python) next to the sink’s processor. Without one, it calls configure(). The Kubit SDK for Python and Kubit SDK for Node pages describe the code it writes.

​
Add user and session IDs

/kubit-integrate doesn’t add user or session IDs to your spans. Without them, Kubit can’t group traces into sessions or join them to users. Set them on the root span of each request, as shown in Kubit SDK for Python or Kubit SDK for Node.

​
Constraints

​
Other Kubit skills

​
Using Cursor, Codex or another agent

The plugin installs into Cursor too. Run npx @kubit-ai/agent-plugin and pick Cursor, or run npx @kubit-ai/agent-plugin --runtime cursor. Pick Both to install into Claude Code and Cursor at once. Restart Cursor afterwards. Cursor asks you to sign in to the Kubit MCP server the first time a skill calls it. Codex and other agents don’t have the plugin. Give your agent the page that matches your stack and let it follow the steps:
Get the API key first, as described in the Quickstart.

​
Verify

After you run the skill’s verification command, open Agent > Activity in the Kubit app, set Time Range to Last 1 day and click Execute. The list has a trace whose root span is hello-kubit. Validate in Activity shows what to check in the trace. With the plugin installed, you can also ask Claude Code or Cursor:
“Show me traces from the last 15 minutes”

​
If it fails

More checks are in Is my data flowing?.

​
Next steps

  • Quickstart: check the extraction mapping and validate in Activity.
  • Concepts: what Kubit does with your spans.