This document outlines a methodology for automatically integrating the Claude Code CLI with LangSmith for real-time trace visibility of conversational interactions. The core mechanism leverages a global "Stop" hook within the Claude Code CLI, designed to execute a predefined shell script (stop_hook.sh) after each assistant response.

The process functions as follows:

1. Hook Triggering: A global hook, configured in ~/.claude/settings.json, specifies that a command-type hook, bash ~/.claude/hooks/stop_hook.sh, should be executed upon the "Stop" event, which occurs after Claude Code provides a response.
2. Transcript Processing: The stop_hook.sh script is responsible for accessing and parsing the Claude Code CLI's generated conversation transcripts. These transcripts, typically in JSON format, contain user messages, tool calls, and assistant responses. System prompts are explicitly noted as not being included in these transcripts.
3. Data Transformation: Messages extracted from the conversation transcripts are programmatically converted into the LangSmith data model, specifically as "runs" (analogous to spans in distributed tracing). These runs encapsulate the conversational turns.
4. Data Transmission: The transformed LangSmith runs are then transmitted to a specified LangSmith project via the LangSmith API.
5. Opt-in Tracing: Tracing functionality is opt-in and controlled on a per-Claude Code project basis (or globally). This is managed through environment variables defined within the project's .claude/settings.local.json file (or ~/.claude/settings.json). Key environment variables include:
   • TRACE_TO_LANGSMITH: A boolean flag ("true") to enable tracing for the specific project.
   • CC_LANGSMITH_API_KEY: The authenticated LangSmith API key (e.g., lsv2_pt_...).
   • CC_LANGSMITH_PROJECT: (Optional) The target LangSmith project name for trace ingestion.
   • CC_LANGSMITH_DEBUG: A boolean flag ("true") to enable verbose logging for debugging API interactions.
6. Trace Representation in LangSmith: Upon successful configuration and execution, each message exchanged within a Claude Code session appears as an individual trace in LangSmith. Critically, all conversational turns originating from the same Claude Code session are logically grouped by a shared thread_id within LangSmith, enabling chronological visualization in the Threads tab.

Prerequisites for this setup include the Claude Code CLI, a valid LangSmith API key, and the jq command-line JSON processor. The stop_hook.sh script must be made executable (chmod +x ~/.claude/hooks/stop_hook.sh). Troubleshooting involves inspecting the hook's log file (~/.claude/state/hook.log), verifying environment variable correctness, ensuring API key validity, checking for proper project setup in LangSmith, enabling debug mode for detailed API call inspection, and confirming the presence of required system utilities like jq, curl, and uuidgen. Log file management is also addressed, noting that the hook.log can grow, especially in debug mode.