Trace Claude Code applications

This guide shows you how to send conversations automatically from the Claude Code CLI to LangSmith. Once configured, each Claude Code project can opt in to sending traces to LangSmith. Each trace includes user messages, tool calls, compaction, subagent runs, and assistant responses. System prompts are not included, because Claude Code does not return them in conversation transcripts.

Prerequisites

Before setting up tracing, ensure you have:

Getting started

From within Claude Code, run:

/plugin marketplace add langchain-ai/langsmith-claude-code-plugins
/plugin install langsmith-tracing@langsmith-claude-code-plugins
/reload-plugins

To update the plugin, refresh the marketplace from within Claude Code:

/plugin marketplace update langsmith-claude-code-plugins

Then move the install onto the new version from your shell and restart Claude Code:

claude plugin update langsmith-tracing@langsmith-claude-code-plugins

The marketplace update on its own only refreshes the catalog clone. Your install stays pinned to the version directory it was installed from, so the hooks keep running the old bundle until claude plugin update moves it. To skip both steps next time, run /plugin, open Marketplaces → langsmith-claude-code-plugins and choose Enable auto-update: third-party marketplaces have it off by default, and enabling it updates the marketplace and its installed plugins together.

If you are migrating from the previously recommended version of tracing Claude Code with manually created stop hooks, refer to Migrating from the manual stop hook.

Setting environment variables

Option 1: Project-level configuration (recommended) The plugin requires the following environment variables:

TRACE_TO_LANGSMITH: "true": Enables tracing for this project. Remove or set to false to disable tracing.
CC_LANGSMITH_API_KEY: Your LangSmith API key.
CC_LANGSMITH_PROJECT: The LangSmith project name to which your traces will send.
(optional) CC_LANGSMITH_METADATA: JSON object of custom metadata to attach to all runs (e.g., PR URL, author).
(optional) CC_LANGSMITH_DEBUG: "true": Enables detailed debug logging. Remove or set to false to disable debug logging.

To get set up, create or edit Claude Code’s project settings file. Create a .claude/settings.local.json in your project directory and populate it as follows:

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project"
  }
}

Alternatively, to enable tracing to LangSmith for all Claude Code sessions, you can add the previous JSON to your global Claude Code settings.json file.

Option 2: Shell environment variables Run the following commands in your shell or add them to your shell configuration file (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export TRACE_TO_LANGSMITH="true"
export CC_LANGSMITH_API_KEY="<LangSmith API key>"
export CC_LANGSMITH_PROJECT="my-project"

Verify setup

Traces will appear complete in your LangSmith project after Claude Code responds. If you interrupt a run while it is in progress, the plugin will only flush that run when you send the next message or end the session. In LangSmith, you’ll find:

Each message to Claude Code appears as a trace.
All turns from the same Claude Code session are grouped using a shared thread_id, which you can view in the Threads tab of a project.

Custom metadata

Set the CC_LANGSMITH_METADATA environment variable to a JSON object to attach custom metadata to all traced runs. This is useful for tagging traces with contextual information such as PR URLs, authors, or environment names.

Settings file (recommended)
Shell environment variable

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project",
    "CC_LANGSMITH_METADATA": "{\"author\":\"jane\",\"environment\":\"development\"}"
  }
}

export CC_LANGSMITH_METADATA='{"author":"jane","environment":"development"}'

The metadata keys and values will appear on all runs in LangSmith, which you can use to filter and search traces.

Mute a thread

Muting suppresses a thread’s input and output content in traces without disabling tracing. Muting is off by default unless you set a default. With tracing enabled, run these plugin commands inside Claude Code. Neither command takes arguments:

/langsmith-tracing:mute: Omit this thread’s input and output content from later traces.
/langsmith-tracing:unmute: Restore full tracing for later turns in this thread.

Both commands apply from the next turn, so the current turn is unchanged. A turn’s mode is fixed when the turn starts, and its subagents inherit that mode. Muted runs keep their normal nesting, names, timing, status, model and tool identity, and token usage. Inputs and outputs are replaced with a system notice. Muted mode also omits raw errors, identity and repository attribution, custom metadata, SDK runtime metadata, and replica metadata overrides. Muting is independent of secret redaction.

Set a default mute configuration

To start threads in metadata-only mode without running a command in each one, set CC_LANGSMITH_DEFAULT_MUTED to "true":

Settings file (recommended)
Shell environment variable

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project",
    "CC_LANGSMITH_DEFAULT_MUTED": "true"
  }
}

export CC_LANGSMITH_DEFAULT_MUTED="true"

Set the variable to "false" to return to the unmuted default. The comparison is case-insensitive, and any other value mutes, including an empty string. The plugin also reads a defaultMuted boolean from its own configuration files, in this order: .claude/langsmith.json and langsmith-plugins.json in the project directory, then ~/.claude/langsmith.json and ~/.langsmith-plugins.json. The environment variable takes precedence over all four. Thread preferences are sticky. The plugin saves each explicit mute or unmute to a privacy file, ~/.claude/state/langsmith_state.privacy.json by default, and a saved thread preference wins over the configured default in both directions. Deleting the privacy file removes every thread override and returns each thread to the configured default.

Secret redaction

The plugin redacts detected secrets from run inputs, outputs, errors, and metadata before uploading them to LangSmith. Redaction is on by default. Redaction runs on your machine before upload, so unredacted content never reaches LangSmith. Replica destinations receive the same redacted payload. Detection covers provider API key prefixes, JSON Web Tokens, and PEM private key blocks. It also covers contextual shapes such as API_KEY=<value>, an Authorization header, and a password embedded in a URL. Each match is replaced with [SECRET_DETECTED]. For the rule list, see Redact secrets from traces. Redaction matches known credential shapes, so treat it as a safety net rather than a guarantee. A credential in an unrecognized format still reaches LangSmith, and attachments, run names, and tags do not pass through the anonymizer. A redacted trace also still holds the prompts, file contents, and tool results it was built from, so restrict who can read the tracing project. Redaction targets credential values, not identity. The anthropic_user_id and local_username metadata that the plugin attaches is unaffected. To omit content and attribution instead of scrubbing credentials out of it, mute the thread.

Turn redaction off

Set CC_LANGSMITH_REDACT to false, 0, no, or off. The comparison is case-insensitive, and any other value leaves redaction on.

export CC_LANGSMITH_REDACT="false"

Redact additional patterns

Set CC_LANGSMITH_REDACT_EXTRA to a JSON array of { "pattern": ..., "replace": ... } rules. Each pattern is a regular expression string, applied globally and case-sensitively. replace is optional and falls back to [redacted].

{
  "env": {
    "CC_LANGSMITH_REDACT_EXTRA": "[{\"pattern\":\"ACME-[A-Z0-9]{16}\",\"replace\":\"[REDACTED_ACME_KEY]\"}]"
  }
}

Extra rules run after the built-in ones. The plugin skips a rule with an invalid regular expression, logs an error, and uploads the turn with the remaining rules applied. Both settings also read from the plugin configuration files described in Set a default mute configuration, as the redact and redact_extra_rules keys:

{
  "redact": true,
  "redact_extra_rules": [{ "pattern": "ACME-[A-Z0-9]{16}", "replace": "[REDACTED_ACME_KEY]" }]
}

The environment variables take precedence over all four files. A file behaves more strictly than the environment variable. One rule with an invalid regular expression discards every setting in that file, not only that rule. Because a project-level .claude/langsmith.json can set redact to false, review that file before enabling tracing in a repository you do not control.

Usage with GitHub Actions

You can use this plugin with anthropics/claude-code-action to trace Claude Code runs in CI. Add the following to your workflow:

- uses: anthropics/claude-code-action@v1
  env:
    TRACE_TO_LANGSMITH: "true"
    CC_LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
    CC_LANGSMITH_PROJECT: "my-project"
    CC_LANGSMITH_METADATA: |
      {
        "pr_url": "${{ github.event.pull_request.html_url || '' }}",
        "pr_number": "${{ github.event.pull_request.number || '' }}",
        "pr_author": "${{ github.event.pull_request.user.login || '' }}",
        "repository": "${{ github.repository }}",
        "commit_sha": "${{ github.sha }}",
        "trigger": "${{ github.event_name }}"
      }
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}
    plugin_marketplaces: |
      https://github.com/langchain-ai/langsmith-claude-code-plugins.git
    plugins: |
      langsmith-tracing@langsmith-claude-code-plugins
    prompt: |
      Your prompt here

Make sure to add LANGSMITH_API_KEY and ANTHROPIC_API_KEY as repository secrets. This lets you correlate traces back to specific PRs, commits, and authors in LangSmith.

Nesting traces under an existing run

You can also set an environment variable named CC_LANGSMITH_PARENT_DOTTED_ORDER to nest all Claude Code traces as children of an existing LangSmith run. This is useful when Claude Code is invoked programmatically as part of a larger traced workflow. Python

import subprocess
from langsmith import traceable, get_current_run_tree


os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "<LangSmith API key>"
os.environ["LANGSMITH_PROJECT"] = "claude-code"

@traceable
def run_claude(prompt: str):
    run_tree = get_current_run_tree()
    subprocess.run(
        ["claude", "-p", prompt],
        env={
            **os.environ,
            "TRACE_TO_LANGSMITH": "true",
            "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
            "CC_LANGSMITH_PROJECT": "claude-code",
            "CC_LANGSMITH_PARENT_DOTTED_ORDER": run_tree.dotted_order,
        },
    )

TypeScript

import { traceable, getCurrentRunTree } from "langsmith/traceable";
import { execSync } from "node:child_process";

process.env.LANGSMITH_TRACING = "true";
process.env.LANGSMITH_API_KEY = "<LangSmith API key>";
process.env.LANGSMITH_PROJECT = "claude-code";

const runClaude = traceable(
  async (prompt: string) => {
    const runTree = getCurrentRunTree();
    const pluginDir = new URL(".", import.meta.url).pathname;
    const res = execSync(`claude -p "${prompt}" --plugin-dir '${pluginDir}'`, {
      env: {
        ...process.env,
        TRACE_TO_LANGSMITH: "true",
        CC_LANGSMITH_API_KEY: "<LangSmith API key>",
        CC_LANGSMITH_PROJECT: "claude-code",
        CC_LANGSMITH_PARENT_DOTTED_ORDER: runTree.dotted_order,
      },
    });
    return res.toString();
  },
  { name: "run_claude" },
);

The resulting trace hierarchy looks like:

Your outer run (chain)
└── Claude Code Turn (chain)
    ├── Claude (llm)
    ├── Read (tool)
    └── Claude (llm)

Trace to multiple destinations (replicas)

You can trace to multiple LangSmith projects or workspaces simultaneously using the CC_LANGSMITH_RUNS_ENDPOINTS environment variable. Set CC_LANGSMITH_RUNS_ENDPOINTS to a JSON array of replica configurations. This overrides other client settings. Tracing to multiple replicas is useful for:

Sending traces to both a production and staging project.
Tracing to multiple workspaces with different API keys.
Adding extra metadata to specific replica destinations.

Each replica object supports the following fields:

Field	Required	Description
`apiUrl`	Yes	LangSmith API URL (typically `https://api.smith.langchain.com`)
`apiKey`	Yes	API key for the destination workspace
`projectName`	Yes	Project name in the destination workspace
`updates`	No	Optional metadata/fields to override on the replicated runs

There are two ways to set the CC_LANGSMITH_RUNS_ENDPOINTS environment variable:

Settings file (recommended)
Shell environment variable

In your local .claude/settings.local.json or global ~/.claude/settings.json:

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_RUNS_ENDPOINTS": "[{\"apiUrl\":\"https://api.smith.langchain.com\",\"apiKey\":\"ls__key_workspace_a\",\"projectName\":\"project-prod\"},{\"apiUrl\":\"https://api.smith.langchain.com\",\"apiKey\":\"ls__key_workspace_b\",\"projectName\":\"project-staging\",\"updates\":{\"metadata\":{\"environment\":\"staging\"}}}]"
  }
}

To generate the escaped JSON string, use:

echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -cR .

Option 2: Shell environment variableAdd to your ~/.zshrc, ~/.bashrc, or ~/.bash_profile:

export CC_LANGSMITH_RUNS_ENDPOINTS='[{"apiUrl":"https://api.smith.langchain.com","apiKey":"ls__key_workspace_a","projectName":"project-prod"},{"apiUrl":"https://api.smith.langchain.com","apiKey":"ls__key_workspace_b","projectName":"project-staging","updates":{"metadata":{"environment":"staging"}}}]'

Troubleshooting

No traces appearing in LangSmith

Check the hook is running:
tail -f ~/.claude/state/hook.log
You should see log entries after each Claude response.
Verify environment variables:
- Check that TRACE_TO_LANGSMITH="true" in your project’s .claude/settings.local.json.
- Verify your Personal Access Token (PAT) is correct (starts with lsv2_pt_).
- Ensure the project name exists in LangSmith.
Enable debug mode to see detailed API activity:
{ "env": { "CC_LANGSMITH_DEBUG": "true" } }
Then check logs for API calls and HTTP status codes.

Subagent runs do not appear after user interruption

Subagents are only traced upon completion. This means if you interrupt a conversation turn in the middle of a subagent run, the subagent’s child runs will not be traced.

Managing log file size

The hook logs all activity to ~/.claude/state/hook.log. With debug mode enabled, this file can grow large:

# View log file size
ls -lh ~/.claude/state/hook.log

# Clear logs if needed
> ~/.claude/state/hook.log

Migrating from the manual stop hook

If you were using the previous version of tracing Claude Code with LangSmith, you will need to remove ~/.claude/hooks/stop_hook.sh and remove the reference to the hook from any previous settings.local.json or settings.json files you added it to previously, then follow the plugin installation instructions.

Source code

The plugin is open-source under the MIT license and is available in this GitHub repo.

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

Trace Claude Code applications

Prerequisites

Getting started

Setting environment variables

Verify setup

Custom metadata

Mute a thread

Set a default mute configuration

Secret redaction

Turn redaction off

Redact additional patterns

Usage with GitHub Actions

Nesting traces under an existing run

Trace to multiple destinations (replicas)

Troubleshooting

No traces appearing in LangSmith

Subagent runs do not appear after user interruption

Managing log file size

Migrating from the manual stop hook

Source code

​Prerequisites

​Getting started

​Setting environment variables

​Verify setup

​Custom metadata

​Mute a thread

​Set a default mute configuration

​Secret redaction

​Turn redaction off

​Redact additional patterns

​Usage with GitHub Actions

​Nesting traces under an existing run

​Trace to multiple destinations (replicas)

​Troubleshooting

​No traces appearing in LangSmith

​Subagent runs do not appear after user interruption

​Managing log file size

​Migrating from the manual stop hook

​Source code

Prerequisites

Getting started

Setting environment variables

Verify setup

Custom metadata

Mute a thread

Set a default mute configuration

Secret redaction

Turn redaction off

Redact additional patterns

Usage with GitHub Actions

Nesting traces under an existing run

Trace to multiple destinations (replicas)

Troubleshooting

No traces appearing in LangSmith

Subagent runs do not appear after user interruption

Managing log file size

Migrating from the manual stop hook

Source code