Trace Claude Code sessions

The LangSmith tracing plugin sends your Claude Code conversations to LangSmith so you can see what the agent did. Each message becomes a trace, and a session’s messages are grouped into a thread.

Prerequisites

Claude Code installed.
A LangSmith account.
Node.js 20 or later on Windows and Linux. On macOS the plugin runs its own build and does not need Node.js.

Install the plugin

Run these commands inside Claude Code:

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

Auto-update is off for this marketplace by default. To turn it on, run /plugin and open Marketplaces. To install the plugin for everyone, see Deploy to your organization. For more on installing plugins, see Install plugins in the Claude Code docs. Sign in once with the LangSmith CLI. See Install the LangSmith CLI if you do not have it yet.

langsmith auth login

If you use the CLI sign-in and have more than one profile, set profile in your config file to the one the plugin should use. Your own api_key ignores this setting, but a generic LANGSMITH_API_KEY is not used as a fallback while profile is set. To use an API key instead, add it to ~/.claude/langsmith.json:

{ "enabled": true, "api_key": "lsv2_pt_...", "agent_id": "shared-claude" }

If more than one credential is set, the plugin uses the first one it finds:

The plugin’s own key from api_key or CC_LANGSMITH_API_KEY.
Your langsmith auth login sign-in.
A generic LANGSMITH_API_KEY from your environment.

A CLI sign-in acts as you so your workspace role needs permission to write traces. You may get a 403 if you switched from a tracing API key (lsv2_tr_...) to the CLI sign-in since tracing keys can always write traces whatever your role is. If that happens ask your admin to give you a role that can write traces such as Workspace User and check that no ABAC deny policy on the project blocks it. Tracing stops when your sign-in expires or your key is rejected, and turns from that gap are never uploaded. Claude Code reminds you in the chat until you fix it. Admins can also require a working sign-in for every prompt.

Turn on tracing

Tracing is off until you turn it on in ~/.claude/langsmith.json, unless your admin already turned it on with a managed file. In an agent-based workspace, send traces to an agent with agent_id:

{ "enabled": true, "agent_id": "shared-claude" }

In a project-based workspace, use the legacy project setting instead:

{ "enabled": true, "project": "shared-claude" }

A project can override these settings with <project>/.claude/langsmith.json or <project>/langsmith-plugins.json. A cloned repository can use them to turn tracing on and send your conversations to someone else’s server. Before you trust a repository, review those files along with .claude/settings.json and .claude/settings.local.json.

Send a message and open your agent or project in LangSmith. Run /langsmith-tracing:trace to get a link to the current conversation’s trace.

Deploy to your organization

Admins can install the plugin for everyone and control how it traces from one place.

Install for everyone

Use Claude Code’s managed settings to install the plugin on every machine. For the setup, see Manage Claude Code plugins for your organization.

Lock settings

An admin can lock tracing settings for every user with a managed file at ~/.langsmith-plugins/managed.json in each user’s home folder. The Claude Code, Cursor, and Codex plugins all read this file, and its settings override the user’s own config files and environment variables.

{
  "api_url": "https://api.smith.langchain.com",
  "agent_id": "coding-agent",
  "strict_auth": true,
  "workspace_id": "<your-workspace-id>"
}

Set workspace_id as well when your users sign in with the LangSmith CLI. Each user’s sign-in may default to a different workspace, so setting it here keeps everyone’s traces in one place. API keys ignore this setting so use one scoped to a workspace. The managed file works on macOS and Linux. The plugin only trusts it when:

Root owns the file and its folder.
No other user can write to either.
Neither is a symlink.

If the file exists but fails these checks, tracing stops and the user sees a message to contact their admin. Locking a setting also locks the settings tied to it, so users cannot route traces around the lock. For example, locking agent_id also stops users from sending traces to a project with project. Admins usually install the file on each machine with a mobile device management (MDM) tool such as Jamf or Microsoft Intune. For every setting you can lock, see the plugin settings guide.

Example setup script

Run this as root for each user, with USER_HOME set to that user’s home folder:

USER_HOME=/Users/developer
mkdir -p "$USER_HOME/.langsmith-plugins"
cp managed.json "$USER_HOME/.langsmith-plugins/managed.json"
chown root:wheel "$USER_HOME/.langsmith-plugins" "$USER_HOME/.langsmith-plugins/managed.json"
chmod 755 "$USER_HOME/.langsmith-plugins"
chmod 644 "$USER_HOME/.langsmith-plugins/managed.json"

On Linux, use root:root instead of root:wheel. For the full script, see Set it up on macOS.

Strict auth blocks every prompt until the user’s sign-in or key works, so no session goes untraced. It is off by default and has no effect while tracing is off. To turn it on for everyone, set strict_auth to true in the managed file.

Strict auth also blocks non-interactive runs such as claude -p in CI. Leave it off for automated runs unless a failed sign-in should stop the job.

Hide a conversation

Run /langsmith-tracing:mute inside Claude Code to keep a conversation’s content out of LangSmith, and /langsmith-tracing:unmute to turn it back on. The confirmation appears as a prompt blocked by a hook, because that is how Claude Code shows a plugin’s reply. To mute every conversation by default, set defaultMuted to true.

Secret redaction

The plugin strips secrets on your machine before anything is uploaded, so they never reach LangSmith or a replica. Redaction is on by default. It catches provider API keys, JSON Web Tokens, and PEM private keys, along with common patterns such as API_KEY=<value> or a password in a URL. Each match is replaced with [SECRET_DETECTED]. For the full rule list, see Redact secrets from traces. Redaction only matches known credential shapes, so treat it as a safety net rather than a guarantee. Run names, tags, and attachments skip it, and a redacted trace still holds your prompts and file contents. Limit who can read the tracing project. To turn redaction off or add your own patterns, see the plugin settings.

Settings

Each setting has a config file key and an environment variable. The environment variable wins when both are set.

Config key	Environment variable	Default	Description
`enabled`	`TRACE_TO_LANGSMITH`	`false`	Turns tracing on.
`api_key`	`CC_LANGSMITH_API_KEY`	none	LangSmith API key. Not needed if you sign in with the CLI.
`agent_id`	`LANGSMITH_AGENT_ID`	none	Agent the traces go to. Wins over `project` if both are set.
`project` (deprecated)	`CC_LANGSMITH_PROJECT`	`claude-code`	Project the traces go to. Use `agent_id` unless your workspace is project-based.
`api_url`	`LANGSMITH_ENDPOINT`	`https://api.smith.langchain.com`	LangSmith server to send to.
`workspace_id`	`LANGSMITH_WORKSPACE_ID`	none	Workspace the traces go to when you sign in with the CLI. API keys ignore it and your config file wins over the variable.

For every setting, see the plugin settings.

Other examples

The plugin’s Advanced configuration guide has worked examples for:

Troubleshooting

No traces: Check that the plugin is enabled in /plugin and that tracing is on.
Tracing is paused: Run langsmith auth login again or replace the rejected API key.
Tracing is paused after a 403: Your sign-in or API key might not have access to the agent, project or workspace. Look through ~/.claude/state/langsmith_engine/worker.log and ~/.claude/state/hook.log for the details.
Still stuck: Set CC_LANGSMITH_DEBUG=true and check ~/.claude/state/hook.log.

For more fixes, see When nothing shows up.

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

Prerequisites

Install the plugin

Turn on tracing

Deploy to your organization

Install for everyone

Lock settings

Hide a conversation

Secret redaction

Settings

Other examples

Troubleshooting

​Prerequisites

​Install the plugin

​Sign in

​Turn on tracing

​Deploy to your organization

​Install for everyone

​Lock settings

​Require a working sign-in

​Hide a conversation

​Secret redaction

​Settings

​Other examples

​Troubleshooting

Prerequisites

Install the plugin

Sign in

Turn on tracing

Deploy to your organization

Install for everyone

Lock settings

Require a working sign-in

Hide a conversation

Secret redaction

Settings

Other examples

Troubleshooting