> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# OpenCode AI Observability installation

1.  1

    ## Prerequisites

    Required

    [OpenCode](https://opencode.ai) is an open-source AI coding agent that runs in your terminal. The [`@posthog/opencode`](https://github.com/PostHog/posthog-opencode) plugin captures LLM generations, tool executions, and conversation traces as `$ai_generation`, `$ai_span`, and `$ai_trace` events and sends them to PostHog.

    You need:

    -   [OpenCode](https://opencode.ai/docs) installed
    -   A [PostHog account](https://app.posthog.com/signup) with a project token

2.  2

    ## Install the plugin

    Required

    Add `@posthog/opencode` to the `plugin` array in your `opencode.json` file:

    ```json
    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@posthog/opencode"]
    }
    ```

    Use `opencode.json` in your project root for a project-level install, or `~/.config/opencode/opencode.json` for a global install. OpenCode installs the package when it starts and caches it in `~/.cache/opencode/node_modules/`.

3.  3

    ## Configure PostHog

    Required

    Set environment variables with your PostHog project token and host. You can find both in your [PostHog project settings](https://app.posthog.com/settings/project).

    ```bash
    export POSTHOG_API_KEY="<ph_project_token>"
    export POSTHOG_HOST="https://us.i.posthog.com"
    ```

    > **Tip:** Add these variables to your shell profile, such as `~/.zshrc` or `~/.bashrc`, so they persist across sessions.

    If `POSTHOG_API_KEY` is not set, the plugin does not capture or send events.

4.  4

    ## Run a session

    Required

    Start OpenCode as normal and use it for a task:

    ```bash
    opencode
    ```

    The plugin initializes and captures events for each LLM call, tool execution, and completed prompt.

5.  5

    ## Configuration options

    Optional

    Configure the plugin with environment variables:

    | Variable | Default | Description |
    | --- | --- | --- |
    | `POSTHOG_API_KEY` | *(required)* | Your PostHog project token |
    | `POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog ingestion host |
    | `POSTHOG_PRIVACY_MODE` | `false` | When `true`, the plugin does not send LLM content, prompts, or tool inputs and outputs. Token counts, costs, latency, and model metadata are still captured. |
    | `POSTHOG_ENABLED` | `true` | Set to `false` to disable the plugin |
    | `POSTHOG_DISTINCT_ID` | Machine hostname | Distinct ID included in all events |
    | `POSTHOG_PROJECT_NAME` | Current directory name | Project name included in all events |
    | `POSTHOG_TAGS` | *(none)* | Custom tags added to all events in `key1:val1,key2:val2` format |
    | `POSTHOG_MAX_ATTRIBUTE_LENGTH` | `12000` | Maximum length for serialized tool input and output attributes |

    ### Privacy mode

    When `POSTHOG_PRIVACY_MODE=true`, all LLM content, user prompts, tool inputs, and tool outputs are redacted. Token counts, costs, latency, and model metadata are still captured.

    The plugin always redacts sensitive keys matching terms such as `api_key`, `token`, `secret`, `password`, `authorization`, `credential`, and `private_key`, regardless of privacy mode.

    ### What gets captured

    The plugin captures three types of events:

    -   **`$ai_generation`:** Each LLM call, including model, provider, token usage, cost, stop reason, and input and output messages in [OpenAI chat format](/docs/ai-observability/generations.md).
    -   **`$ai_span`:** Each tool execution, including tool name, input parameters, output result, duration, parent generation, and error details. [Learn more about spans](/docs/ai-observability/spans.md).
    -   **`$ai_trace`:** Each completed prompt, including aggregated token totals, latency, input and output state, and error status. [Learn more about traces](/docs/ai-observability/traces.md).

6.  ## Verify traces and generations

    Recommended

    *Confirm LLM events are being sent to PostHog*

    Let's make sure LLM events are being captured and sent to PostHog. Under **AI Observability**, you should see rows of data appear in the **Traces** and **Generations** tabs.

    ![LLM generations in PostHog](https://res.cloudinary.com/dmukukwp6/image/upload/SCR_20250807_syne_ecd0801880.png)

    [Check for LLM events in PostHog](https://app.posthog.com/ai-observability/generations)

7.  6

    ## Next steps

    Recommended

    Now that you're capturing AI conversations, continue with the resources below to learn what else AI Observability enables within the PostHog platform.

    | Resource | Description |
    | --- | --- |
    | [Basics](/docs/ai-observability/basics.md) | Learn the basics of how LLM calls become events in PostHog. |
    | [Generations](/docs/ai-observability/generations.md) | Read about the `$ai_generation` event and its properties. |
    | [Traces](/docs/ai-observability/traces.md) | Explore the trace hierarchy and how to use it to debug LLM calls. |
    | [Spans](/docs/ai-observability/spans.md) | Review spans and their role in representing individual operations. |
    | [Anaylze LLM performance](/docs/ai-observability/dashboard.md) | Learn how to create dashboards to analyze LLM performance. |

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better