> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Skill

> Let AI integrate Moda into your codebase automatically

## What It Does

The Moda Claude Code skill teaches AI assistants how to correctly integrate Moda's LLM observability SDK into any TypeScript or Python project. Instead of guessing at configuration, the AI detects your project stack and applies the right integration pattern automatically.

The skill handles:

* Detecting your framework and LLM provider
* Installing the correct SDK (`moda-ai` for both npm and PyPI)
* Placing `init()` at the right entry point for your framework
* Choosing the correct conversation ID strategy
* Adding `flush()` in cleanup hooks
* Configuring Vercel AI SDK telemetry

## Prerequisites

* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) must be installed and available in your terminal
* A Moda API key (get one from the [Moda dashboard](https://app.moda.dev))

## Installation

The skill files are available in the [Moda GitHub repository](https://github.com/modaflows/moda). You can install them per-project or globally.

<CodeGroup>
  ```bash Per-Project (Recommended) theme={"dark"}
  # From your project root
  mkdir -p .claude/skills
  cp -r path/to/moda-setup/ .claude/skills/moda-setup/
  ```

  ```bash Global (All Projects) theme={"dark"}
  # Available in every Claude Code session
  mkdir -p ~/.claude/skills
  cp -r path/to/moda-setup/ ~/.claude/skills/moda-setup/
  ```

  ```bash From GitHub theme={"dark"}
  # Clone directly from the Moda repository
  git clone https://github.com/modaflows/moda.git /tmp/moda
  cp -r /tmp/moda/moda-setup/ .claude/skills/moda-setup/
  rm -rf /tmp/moda
  ```
</CodeGroup>

## Usage

Once installed, the skill activates automatically when you ask Claude Code to:

* "Add Moda observability to this project"
* "Integrate LLM analytics"
* "Set up conversation tracking for my AI calls"
* "Add tracing for OpenAI/Anthropic calls"

You can also invoke it directly:

```
/moda-setup
```

## What It Handles

### Framework Detection

The skill inspects your project files to detect:

| File                                  | Detects                                 |
| ------------------------------------- | --------------------------------------- |
| `package.json`                        | Node.js framework, AI SDK, LLM provider |
| `requirements.txt` / `pyproject.toml` | Python framework, LLM provider          |
| `next.config.*`                       | Next.js                                 |
| `app/layout.tsx`                      | Next.js App Router                      |
| `instrumentation.ts`                  | Existing instrumentation setup          |

### Conversation Threading

The skill automatically chooses the right conversation ID strategy:

| Pattern            | Strategy                                    |
| ------------------ | ------------------------------------------- |
| Simple chatbot     | Auto-detection (hash-based)                 |
| Web server         | Scoped context per request                  |
| Agent framework    | Explicit ID (auto doesn't work with agents) |
| Multi-agent system | Shared parent task ID                       |

<Warning>
  Agent frameworks like LangChain, CrewAI, and AutoGPT require explicit conversation IDs. The automatic fallback does NOT work because each agent iteration constructs different messages.
</Warning>

### Correct Placement

The skill knows where to place initialization for each framework:

| Framework      | `init()` Location          | `flush()` Location        |
| -------------- | -------------------------- | ------------------------- |
| Next.js        | `instrumentation.ts`       | Route handler `waitUntil` |
| Express        | Server startup             | `SIGTERM` handler         |
| FastAPI        | Lifespan event             | Lifespan cleanup          |
| Flask          | App factory / module level | `teardown_appcontext`     |
| Generic script | Top of file                | Before exit               |

## Supported Frameworks

<CardGroup cols={2}>
  <Card title="TypeScript / Node.js">
    * Next.js (App Router + Vercel AI SDK)
    * Express
    * Generic Node.js scripts
    * Vercel AI SDK
    * OpenAI SDK
    * Anthropic SDK
  </Card>

  <Card title="Python">
    * FastAPI
    * Flask
    * LangChain
    * CrewAI
    * Generic Python scripts
    * OpenAI SDK
    * Anthropic SDK
  </Card>
</CardGroup>

## Example Session

Here's what happens when you ask Claude Code to integrate Moda into a Next.js project:

```
You: Add Moda analytics to this project

Claude: I'll integrate Moda into your Next.js + Vercel AI SDK project.

1. Installing the SDK:
   npm install moda-ai

2. Creating instrumentation.ts for initialization:
   [creates instrumentation.ts with Moda.init()]

3. Updating your route handler:
   [adds Moda.conversationId and experimental_telemetry
    to your existing chat route]

4. Adding MODA_API_KEY to .env.local:
   [adds the environment variable]

Done! Your LLM calls will now be tracked in Moda with automatic
conversation threading. Get your API key from the Moda dashboard
and add it to .env.local.
```

## Related

<CardGroup cols={2}>
  <Card title="Python SDK Reference" icon="python" href="/ingestion/moda-sdk">
    Full Python SDK documentation
  </Card>

  <Card title="Node.js SDK Reference" icon="node-js" href="/ingestion/moda-sdk-node">
    Full TypeScript/Node.js SDK documentation
  </Card>

  <Card title="Vercel AI SDK" icon="bolt" href="/ingestion/vercel-ai-sdk">
    Vercel AI SDK integration guide
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started with Moda in 5 minutes
  </Card>
</CardGroup>