> ## Documentation Index > Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Integrate with the agent plugin > Install the Kubit agent plugin for Claude Code or Cursor and run /kubit-integrate to detect your tracing setup, mint an API key and wire the Kubit SDK into your repo. 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](https://learn.kubit.ai/agent-observability/integrate/sdk-python.md), the [Kubit SDK for Node](https://learn.kubit.ai/agent-observability/integrate/sdk-node.md) or [Manual OpenTelemetry](https://learn.kubit.ai/agent-observability/integrate/manual-otel.md). The [Quickstart](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#choose-how-to-integrate) 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](https://learn.kubit.ai/start-here/admin.md). * [ ] 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 ```bash theme={null} npx @kubit-ai/agent-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 ```text theme={null} /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. ### 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. | 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`. 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](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#check-the-extraction-mapping). It then mints an ingestion key, or takes one you paste, and writes `KUBIT_API_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`) that calls `configure()`, 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`. 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](https://learn.kubit.ai/agent-observability/integrate/sdk-python.md) and [Kubit SDK for Node](https://learn.kubit.ai/agent-observability/integrate/sdk-node.md) 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](https://learn.kubit.ai/agent-observability/integrate/sdk-python.md#add-user-and-session-ids) or [Kubit SDK for Node](https://learn.kubit.ai/agent-observability/integrate/sdk-node.md#add-user-and-session-ids). ## 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` | Ask Kubit anything. It hands the question to the right skill, or runs `/kubit-report`, `/kubit-inspect` and `/kubit-blame` in turn for an investigation. | | `/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 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: ```text theme={null} Add Kubit tracing to this repo. Follow https://learn.kubit.ai/agent-observability/integrate/sdk-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](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#get-an-api-key). ## 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](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#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 | Symptom | Cause | Fix | | - | - | - | | `/kubit-integrate` and the other Kubit skills aren't listed | Claude Code wasn't restarted after the install | Restart Claude Code, then run `/kubit-help` | | Every Kubit tool call returns an auth error | MCP sign-in not done | Run `/mcp`, pick `kubit-agent` 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?](https://learn.kubit.ai/agent-observability/get-started/data-flowing.md). ## Next steps * [Quickstart](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#check-the-extraction-mapping): check the extraction mapping and validate in Activity. * [Concepts](https://learn.kubit.ai/agent-observability/concepts.md): what Kubit does with your spans. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.