Trace Claude Code applications

This guide shows you how to automatically send conversations 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, run:

/plugin marketplace update langsmith-claude-code-plugins
/reload-plugins

If you are migrating from the previously recommended version of tracing Claude Code with manually created stop hooks, see 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 where traces are sent
(optional) CC_LANGSMITH_DEBUG: "true" - Enables detailed debug logging. Remove or set to false to disable debug logging.

The easiest way to get set up is to 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 above 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 LangSmith after Claude Code responds. Note that 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 see:

Each message to Claude Code appears as a trace.
All turns from the same Claude Code session are grouped using a shared thread_id and can be viewed in the Threads tab of a project.

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)

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

Currently, 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 following the plugin installation instructions above.

Source code

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

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

Trace Claude Code applications

Prerequisites

Getting started

Setting environment variables

Verify setup

Nesting traces under an existing run

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

​Nesting traces under an existing run

​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

Nesting traces under an existing run

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