Instrument Cursor, Claude Code, and OpenCode¶
TruLens can capture coding-agent lifecycle hooks without wrapping application
code. The shared runtime ships in trulens-core; each coding client is a thin
plugin containing only its native hook and configuration contract.
Install a client¶
For Cursor:
pip install trulens-core trulens-apps-cursor
trulens-client-hooks install cursor --dry-run
trulens-client-hooks install cursor
For Claude Code:
pip install trulens-core trulens-apps-claude
trulens-client-hooks install claude-code --dry-run
trulens-client-hooks install claude-code
For OpenCode:
pip install trulens-core trulens-apps-opencode
trulens-client-hooks install opencode --dry-run
trulens-client-hooks install opencode
OpenCode does not use JSON command hooks. Install writes a managed plugin to
~/.config/opencode/plugins/trulens-client-hooks.js (or
.opencode/plugins/trulens-client-hooks.js with --project). The plugin
forwards native OpenCode lifecycle events to trulens-client-hooks ingest.
Use --project to install into the current repository instead of the user's
global client configuration. The installer preserves unrelated hooks, creates a
backup, and is idempotent.
Choose a destination¶
The default is a local SQLite database at
~/.trulens/client-hooks.sqlite. Set TRULENS_DATABASE_PATH to move that file,
or a database URL for a custom SQLite file or PostgreSQL:
export TRULENS_DESTINATION=database
export TRULENS_DATABASE_URL="postgresql+psycopg://trulens@localhost/traces"
For Snowflake, use a named connections.toml profile:
export TRULENS_DESTINATION=snowflake
export TRULENS_SNOWFLAKE_CONNECTION=my_connection
export TRULENS_SNOWFLAKE_DATABASE=TRULENS_TRACES
export TRULENS_SNOWFLAKE_SCHEMA=CLIENT_HOOKS
By default, the native client determines identity: the app name is cursor,
claude, or opencode, the app version is detected from the native client,
and the run name is the native conversation/session ID. Cursor supplies its
version in hook payloads, Claude Code supplies it in the native transcript, and
the OpenCode plugin detects it from the installed CLI.
TRULENS_APP_NAME, TRULENS_APP_VERSION, and TRULENS_RUN_NAME remain
available as explicit overrides.
For OTLP, either transport:
export TRULENS_DESTINATION=otlp
export TRULENS_OTLP_ENDPOINT="http://localhost:4317"
export TRULENS_OTLP_PROTOCOL=grpc # or http/protobuf
TRULENS_OTLP_ENDPOINT and TRULENS_OTLP_PROTOCOL are what the exporter reads.
Leave either unset and the OpenTelemetry SDK's own variables apply instead, so
OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_PROTOCOL or
OTEL_EXPORTER_OTLP_PROTOCOL also work. The transport defaults to gRPC when
nothing sets it.
Each transport needs its exporter package: pip install "trulens-core[otlp]".
To send spans to a Snowflake Cortex AI Gateway, so they join the gateway's own server spans for the same requests:
export TRULENS_DESTINATION=ai_gateway
export TRULENS_AI_GATEWAY_URL="https://<host>/api/v2/aigateways/<GATEWAY>"
export TRULENS_AI_GATEWAY_PAT_FILE=~/.snowflake/gateway.pat
Use TRULENS_AI_GATEWAY_TOKEN instead of TRULENS_AI_GATEWAY_PAT_FILE to pass
the token directly. The exporter appends /telemetry/v1/traces to the URL,
sends the token as Authorization: Bearer, and always uses OTLP over
HTTP/protobuf, because gateways do not serve gRPC. This needs the HTTP exporter
package, which trulens-core[otlp] installs.
Spans land in the gateway's trace table rather than a database of your own. To get one trace spanning both client and gateway, the agent also has to propagate trace context; see Inherited trace context.
Configure privacy¶
Lifecycle metadata is captured by default. Source-bearing content is opt-in:
export TRULENS_CAPTURE_CONTENT=true
export TRULENS_CAPTURE_TOOL_PAYLOADS=true
export TRULENS_CAPTURE_DIFFS=true
export TRULENS_CAPTURE_PATHS=true
Diffs include Cursor afterFileEdit old/new pairs and explicit patches. They
can contain source code or credentials, so they remain independently opt-in.
Values are redacted and size-bounded before durable journaling.
Each captured field is truncated to TRULENS_MAX_FIELD_BYTES, 16384 by default
with a floor of 256. Note that tool payloads carry whole tool results, so a file
the agent reads is journaled up to that bound, and captured paths include the
native transcript path.
Identity and correlation¶
TruLens preserves the native client identity instead of creating a separate thread identifier. The mapping is:
| TruLens field | Value |
|---|---|
SpanAttributes.CONVERSATION_ID |
Native conversation or session ID |
SpanAttributes.RUN_NAME |
The same native conversation or session ID |
SpanAttributes.INPUT_ID |
Correlated native turn ID |
SpanAttributes.RECORD_ID |
<client>:<conversation-id>:<turn-id> |
| OpenTelemetry trace ID | The agent's trace when it exports one, otherwise derived from RECORD_ID |
The native conversation fields are Cursor conversation_id, Claude Code
session_id, and OpenCode sessionID. A conversation therefore maps to one
TruLens conversation and, for destinations that support runs, one run. Each user
prompt within it maps to a distinct turn and RECORD_ROOT span.
The conversation ID is also emitted as gen_ai.conversation.id, the GenAI
semantic convention spelling. Producers outside TruLens use that name, so it is
what correlates these spans with, for example, an AI gateway recording the server
side of the same requests.
The durable journal correlates prompt, tool, edit, shell, MCP, subagent,
response, and terminal events into that turn. TruLens uses a native turn ID when
the client supplies one. Otherwise it generates a stable turn:<hex> ID when
the prompt arrives. Later events without a turn ID join the active turn, and the
terminal event closes it. OpenCode response events are explicitly correlated to
the active prompt turn because OpenCode gives the response a different message
ID.
Identity is deterministic across retries. Re-exporting the same journalled turn reuses its run name, record ID, input ID, and trace ID instead of creating a new record.
Inherited trace context¶
An agent that propagates W3C trace context sets TRACEPARENT on the processes
it spawns, which is how a hook invocation learns the span it was spawned under.
The payload on stdin carries no trace context, so the environment is the only
channel.
When a turn's events carry a usable TRACEPARENT, TruLens adopts that trace
instead of deriving one from RECORD_ID, and parents the turn's RECORD_ROOT
to the inherited span. Hook spans then land in the trace the agent already
started, beside the agent's own spans and whatever recorded the server side of
the same requests. Without one, the turn keeps its self-derived trace and a
parentless root, which is the previous behavior.
| Client | Inherited trace context |
|---|---|
| Claude Code | Yes, with CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 |
| Cursor | No, it has no native OpenTelemetry to propagate from |
| OpenCode | No, the plugin runs in-process and does not export one |
Notes on the Claude Code case:
UserPromptSubmit,PreToolUse,PostToolUseandStopcarry the context.SessionStartandSessionEnddo not, because they run outside an active span. A turn only needs one event with the context to adopt it.- The earliest usable context in a turn wins, so the turn is parented to the outermost span the agent had open rather than a later, narrower one.
- Adoption requires the agent's own export to be configured, since propagation is what puts the same trace ID on its outbound inference requests.
Extraction uses the globally configured OpenTelemetry propagators, so
OTEL_PROPAGATORS=none turns adoption off and restores self-derived traces. A
malformed or all-zero TRACEPARENT is ignored the same way.
Run lifecycle¶
Run lifecycle β creating a run and driving it to a terminal status β is a
Snowflake AI Observability concept. It is managed only for
TRULENS_DESTINATION=snowflake, which is the one destination configured with a
connector. OSS (local database/Postgres), plain OTLP, and AI Gateway
destinations export spans but skip run lifecycle entirely: no run is
created and no ingestion is started.
For the Snowflake destination, each conversation maps to one run. Each exported turn contributes one invocation containing one input record:
Run (run name = native conversation/session ID)
βββ invocation for turn 1 -> COMPLETED
βββ invocation for turn 2 -> COMPLETED
βββ invocation for turn 3 -> COMPLETED
For every turn the exporter creates the run if it does not exist, exports the turn's spans, then starts ingestion for that turn. Run creation comes first because the spans carry the run name, and ingestion comes last so the ingestion window does not open before the spans it waits for have been sent. When ingestion can start, the run becomes terminal after the first turn and stays terminal as later turns arrive because status resolves against the most recent invocation.
Runs are created in LOG_INGESTION mode: spans are assembled from journalled
native events rather than by invoking a Python app. Run identity is idempotent on
(app_name, app_version, run_name), where the app version is the detected native
client version.
Snowflake run completion starts an ingestion task after span export. This step
requires CREATE TASK on the target schema and EXECUTE TASK on the account. If
those privileges are unavailable, TruLens retains the successfully exported
trace and logs a warning, but the run may remain non-terminal in the UI. A span
export failure still releases the turn for retry with the journal's normal
backoff.
Destinations without a Snowflake run store β OSS databases, plain OTLP, or a session with no connector β still receive spans; there is simply no run to create or complete, and this is treated as a quiet, expected state rather than an error. To additionally disable run management on a Snowflake destination (for example, to debug the span path in isolation):
export TRULENS_MANAGE_RUNS=false
With run management disabled, turns never reach a terminal run status.
Trace semantics¶
Each turn emits the same semantic conventions as other TruLens apps:
Agent span
βββ Request/response RECORD_ROOT span
βββ Tool, edit, shell, MCP, and subagent spans
βββ Response-generation span
Existing input/output and trace-level selectors work without client-specific
logic. When the turn inherits trace context, this tree is parented to the
agent's span rather than starting a trace of its own; the shape is otherwise
unchanged. Coding-agent-only metadata such as client name, native hook event,
editor version, workspace, and diff is defined centrally in
trulens-otel-semconv.
See Evaluate the Traces for how
post-hoc metrics would run on those records.
Official OTEL GenAI conventions are used for model inference, structured
messages, token usage, and tool execution. TruLens record/evaluation fields and
coding-agent/MCP concepts without an OTEL equivalent remain under the
ai.observability.* namespace. Custom data is not emitted into reserved OTEL
namespaces.
Every span carries the instrumentation scope trulens.client_hooks, versioned
with the installed trulens-core. Filter on that scope name to select hook spans
specifically, which matters when they share a trace with other producers.
Validate and inspect¶
trulens-client-hooks clients
trulens-client-hooks validate
trulens-client-hooks status cursor
trulens-client-hooks flush
Each hook invocation returns after writing to a locked local journal. A detached singleton worker exports completed turns and retries transient destination failures without blocking the coding client. Configure worker behavior with:
export TRULENS_EXPORT_LEASE_SECONDS=60
export TRULENS_WORKER_IDLE_SECONDS=2
export TRULENS_WORKER_POLL_SECONDS=0.25
export TRULENS_STALE_AFTER_HOURS=24
TRULENS_STALE_AFTER_HOURS bounds how long a turn that never saw a terminal
event waits before it is finalized as incomplete, with a one-minute floor.
The journal lives in $XDG_STATE_HOME/trulens/client-hooks, falling back to
~/.trulens/client-hooks. Set TRULENS_JOURNAL_DIR to relocate it; the worker
log sits alongside it as worker.log, which is where export failures are
recorded.
status reports worker, pending, claimed, and retry state. flush remains a
synchronous recovery command for troubleshooting after a machine or process
crash.
Remove only the TruLens-managed hook entries while preserving other hooks:
trulens-client-hooks uninstall cursor
Runtime hooks always fail open: telemetry errors are written to stderr and never block the coding client.