Trace Cursor sessions

Trace Cursor agent sessions in LangSmith using Cursor hooks. Each turn becomes one trace, grouped into a thread per Cursor conversation, which captures prompts, model responses, tool calls, token usage, and subagent activity. Use the traces to debug agent behavior, audit tool calls, track token spend per turn, and compare Cursor runs. The plugin source is available at langchain-ai/langsmith-cursor-plugins.

Prerequisites

Before setting up tracing, ensure you have:

Cursor installed.
Node.js 22.13 or later. The hooks use the built-in node:sqlite module to recover attachments from Cursor’s local database.
A LangSmith API key.

Install and enable the plugin

Install the plugin directly from the GitHub repository in Cursor’s settings:

Open Cursor > Settings > Plugins.
Paste https://github.com/langchain-ai/langsmith-cursor-plugins into the plugin link field.
Confirm to add LangSmith Tracing for Cursor.

This is the recommended path: it installs the hooks with no clone or build step, since the repository ships a precompiled bundle.

Fully restart Cursor after installing so it reloads hooks.json.

Alternative: install from a local clone

Install the hooks from a local clone of langsmith-cursor-plugins. This writes ~/.cursor/hooks.json for all Cursor projects:

node scripts/install.mjs

To scope the hooks to a single project instead, run the installer from the project directory:

node scripts/install.mjs --project

To preview the hook configuration without writing it, run:

node scripts/install.mjs --print

The installer merges its entries with any existing hooks.json. The committed bundle/ means these commands run without pnpm install or pnpm build — those are only needed when contributing changes to the TypeScript source. Restart Cursor after installing so it reloads hooks.json.

Configure tracing

Tracing is disabled until both enabled (or TRACE_TO_LANGSMITH=true) and an API key are set. Configure credentials with environment variables, a JSON config file, or both.

Environment variables

Every LANGSMITH_CURSOR_* variable also accepts the shorter LANGSMITH_* form. When both are set, LANGSMITH_CURSOR_* takes precedence.

Variable	Default	Description
`TRACE_TO_LANGSMITH`	`false`	Set to `"true"` to enable tracing.
`LANGSMITH_CURSOR_API_KEY`	-	LangSmith API key. Falls back to `LANGSMITH_API_KEY`.
`LANGSMITH_CURSOR_ENDPOINT`	`https://api.smith.langchain.com`	LangSmith API URL. Falls back to `LANGSMITH_ENDPOINT`.
`LANGSMITH_CURSOR_PROJECT`	`cursor`	LangSmith project name. Falls back to `LANGSMITH_PROJECT`.
`LANGSMITH_CURSOR_METADATA`	-	JSON object merged into root trace metadata.
`LANGSMITH_CURSOR_RUNS_ENDPOINTS`	-	JSON array of replica destinations.
`LANGSMITH_CURSOR_REDACT`	`true`	Set to `"false"` to disable secret redaction.
`LANGSMITH_CURSOR_REDACT_EXTRA`	-	JSON array of extra `{ pattern, replace }` redaction rules.
`LANGSMITH_CURSOR_ATTACHMENTS`	`true`	Set to `"false"` to disable attachment enrichment.
`LANGSMITH_CURSOR_DB_PATH`	platform default	Override the Cursor `state.vscdb` path used for attachments.
`LANGSMITH_CURSOR_STATE_FILE`	`~/.cursor/langsmith-state.json`	Override the on-disk event-buffer state file.
`LANGSMITH_CURSOR_LOG_FILE`	`~/.cursor/langsmith-hook.log`	Override the hook log file.
`LANGSMITH_CURSOR_DEBUG`	`false`	Set to `"true"` to enable verbose hook logging.

Add the variables to your shell configuration file (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_CURSOR_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_CURSOR_PROJECT="cursor"

To verify hook activity, tail the log file:

tail -f ~/.cursor/langsmith-hook.log

Config file

Use ~/.cursor/langsmith.json for global defaults or ./.cursor/langsmith.json for project-level settings. Settings resolve in this order, with later sources overriding earlier ones: defaults, global config, project config, environment variables.

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "cursor"
}

Field	Environment variable	Default	Description
`enabled`	`TRACE_TO_LANGSMITH`	`false`	Set to `true` to enable tracing.
`api_key`	`LANGSMITH_CURSOR_API_KEY`, `LANGSMITH_API_KEY`	-	LangSmith API key.
`api_url`	`LANGSMITH_CURSOR_ENDPOINT`, `LANGSMITH_ENDPOINT`	`https://api.smith.langchain.com`	LangSmith API URL.
`project`	`LANGSMITH_CURSOR_PROJECT`, `LANGSMITH_PROJECT`	`cursor`	LangSmith project name.
`metadata`	`LANGSMITH_CURSOR_METADATA`, `LANGSMITH_METADATA`	-	Object merged into root trace metadata.
`replicas`	`LANGSMITH_CURSOR_RUNS_ENDPOINTS`, `LANGSMITH_RUNS_ENDPOINTS`	-	Additional LangSmith destinations to replicate traces to.
`redact`	`LANGSMITH_CURSOR_REDACT`, `LANGSMITH_REDACT`	`true`	Set to `false` to disable secret redaction.
`redact_extra_rules`	`LANGSMITH_CURSOR_REDACT_EXTRA`, `LANGSMITH_REDACT_EXTRA`	-	Extra `{ pattern, replace }` rules applied after the built-in ones.
`attachments`	`LANGSMITH_CURSOR_ATTACHMENTS`	`true`	Set to `false` to skip enriching turns with image and file attachment bytes from Cursor’s local database.
`cursor_db_path`	`LANGSMITH_CURSOR_DB_PATH`	platform default	Override the Cursor `state.vscdb` path used for attachments.

Keep config files that include API keys out of version control.

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. Attachments bypass redaction entirely. The plugin recovers image and file attachments from Cursor’s local database and sends their bytes, which the anonymizer never inspects. Set LANGSMITH_CURSOR_ATTACHMENTS to "false" to stop sending them. To turn redaction off, set LANGSMITH_CURSOR_REDACT to false, 0, no, or off, or set "redact": false in a config file. To redact additional patterns, set LANGSMITH_CURSOR_REDACT_EXTRA to a JSON array of { "pattern": ..., "replace": ... } rules, or set redact_extra_rules in a config file. Each pattern is a regular expression string, applied globally and case-sensitively. replace is optional and falls back to [redacted]. Extra rules run after the built-in ones.

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

Setting redact_extra_rules to [] clears rules inherited from a lower-priority source. One rule with an invalid regular expression discards every setting in that file, so keep the patterns simple and verify them before committing. Because a project-level .cursor/langsmith.json can set redact to false, review that file before enabling tracing in a repository you do not control.

What gets traced

The plugin listens to Cursor hooks and assembles one trace per agent turn:

Turns: each turn becomes its own trace, grouped into a thread using thread_id = Cursor’s conversation_id. The trace nests the model run and any tool or subagent runs underneath the turn.
Token usage: per-turn usage_metadata on the model run.
Model and provider: ls_model_name and ls_provider, normalized from Cursor’s model label to a canonical provider id (for example, claude-4.6-sonnet becomes claude-sonnet-4-6). Auto mode reports default with provider cursor.
Tool calls: tool runs for both successful calls and failures, with inputs and outputs.
Attachments: image and file attachments recovered from Cursor’s local database and rendered inline on the user message. Set attachments to false to skip this step.
Subagents: each subagent appears as a nested chain run with its own tool calls underneath, linked to the parent turn.

The plugin does not compute cost locally. Because ls_model_name is normalized to a canonical id and usage_metadata carries the token breakdown, LangSmith’s server-side model price table renders cost in the UI. Auto mode reports default, which LangSmith cannot price.

The plugin uploads Cursor conversation data, including prompts, model responses, tool inputs and outputs, and recovered attachments. Do not enable tracing for sessions that contain data you do not want stored in LangSmith.

Trace metadata

Every run carries the shared coding-agent-v1 metadata contract on run.extra.metadata, which lets traces from any coding agent (Claude Code, Codex, Cursor) be identified and grouped with the same stable keys.

Scope	Keys
Always present	`ls_agent_type` (`"root"`, `"subagent"`, `"middleware"`, or `"compaction"`), `ls_agent_purpose` (`"coding"`), `ls_integration` (`"cursor"`), `ls_agent_runtime` (`"Cursor"`), `ls_trace_schema_version` (`"coding-agent-v1"`), `thread_id` (= Cursor’s `conversation_id`).
Present where known	`ls_integration_version`, `ls_agent_runtime_version` (Cursor’s `cursor_version`), `turn_id` (= Cursor’s `generation_id`), `turn_number`, `repository_url`, `repository_provider`, `repository_name`, `git_branch`, `git_commit_sha`, `cwd`.
Contextual	`local_username`, `user_email` (provisional).
Subagent runs only	`ls_subagent_id`, `ls_subagent_type`.
Tool runs only	`ls_tool_name` (only emitted when the run name differs from the native tool name).
Model and tool runs only	`ls_provider`, `ls_model_name`, `ls_invocation_params`, `usage_metadata`.

Cursor’s hooks do not expose stable sources for user_id, sandbox_type, or approval_policy, so those keys are omitted.

View traces in LangSmith

Open the configured LangSmith project (default cursor) and complete a Cursor turn. The plugin uploads one trace per turn with this structure:

Cursor Turn N (chain)
├── <provider> (llm)   model and provider, token usage, assistant text
├── Read / Shell / ... (tool)
└── Task (tool)        subagent (type and task)

To group related turns, filter on thread_id in the Threads tab of the project.

Known limitations

Subagent token usage: Cursor does not expose a per-subagent usage breakdown via hooks or its local database, so a subagent’s Task run carries its tool calls but no token counts.

Troubleshooting

If traces do not appear in LangSmith:

Confirm TRACE_TO_LANGSMITH=true or "enabled": true is set in a config file the Cursor process can see.
Confirm LANGSMITH_CURSOR_API_KEY or LANGSMITH_API_KEY is set and valid.
Confirm Cursor was fully restarted after the hooks were installed.
Tail the hook log for errors: tail -f ~/.cursor/langsmith-hook.log.
Enable verbose logging with LANGSMITH_CURSOR_DEBUG=true and re-check the log.
If runs land in the wrong project, set LANGSMITH_CURSOR_PROJECT or the project config key.

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 and enable the plugin

Alternative: install from a local clone

Configure tracing

Environment variables

Config file

Secret redaction

What gets traced

Trace metadata

View traces in LangSmith

Known limitations

Troubleshooting

​Prerequisites

​Install and enable the plugin

​Alternative: install from a local clone

​Configure tracing

​Environment variables

​Config file

​Secret redaction

​What gets traced

​Trace metadata

​View traces in LangSmith

​Known limitations

​Troubleshooting

Prerequisites

Install and enable the plugin

Alternative: install from a local clone

Configure tracing

Environment variables

Config file

Secret redaction

What gets traced

Trace metadata

View traces in LangSmith

Known limitations

Troubleshooting