claudeers.
// Developer Tools

tattletale

Tattles on your coding agents: Claude Code and Codex sessions in Sentry agent tracing

// Developer Tools[ cli ][ api ][ claude ]#claude#tag-to-be-production-20261106#devtools◷ MIT$open-sourceupdated 8 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up tattletale (claude-plugin project) into my current project.
Found on https://claudeers.com/tattletale
Repo: https://github.com/getsentry/tattletale
Homepage/docs: —
Detected install method: claude-plugin → /plugin install tattletale@getsentry/tattletale
Category: devtools. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)

⚠ Unverified / not recently updated — review before pasting a run-this config.

/plugin marketplace add getsentry/tattletale
/plugin install tattletale@getsentry/tattletale
// or clone
git clone https://github.com/getsentry/tattletale

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

tattletale

Paste this to your coding agent:

Set up https://github.com/getsentry/tattletale to send my coding-agent sessions to a new Sentry project.

Tattles on your coding agents. tattletale sends your Claude Code, Codex, OpenCode and Pi sessions to a Sentry project as agent traces:

  • one conversation per session;
  • a span per model call, with exact input, cache and output tokens;
  • tool calls, with arguments, results and sizes;
  • subagents nested under the tool call that launched them;
  • compactions.

Then you, or an agent, can find where tokens go in Sentry's Explore → Conversations and span queries.

All it needs is the DSN of the Sentry project to send to. It runs on Node 22.18 or later and has no runtime dependencies.

Experimental. Published on npm as @sentry/tattletale.

Quick start

npx @sentry/tattletale setup --dsn '<SENTRY_DSN>'   # optionally scope it, see below
npx @sentry/tattletale install                     # hook into Claude Code, Codex, OpenCode and Pi
npx @sentry/tattletale status

install sets up whichever of the four agents you have (or pick with --claude, --codex, --opencode, --pi). Codex asks you, once, to approve the new hooks under /hooks. OpenCode gets a plugin file in ~/.config/opencode/plugins/ and Pi an extension in ~/.pi/agent/extensions/; both pick it up in sessions started afterwards. New sessions show up in Sentry within minutes.

Or let your agent do it

The plugin ships a setup skill (skills/setup-tattletale/SKILL.md). Tell Claude Code or Codex: "set up tattletale, send to , only for the terra repo". The skill covers getting a DSN (including through the Sentry MCP), choosing the scope, installing and verifying.

Choose which sessions are sent

By default every session is sent. Narrow it with setup; matching uses each session's working directory.

You wantRun
Only the terra repo, in any folder or worktreesetup --dsn … --repo getsentry/terra
Only sessions under a foldersetup --dsn … --include ~/code/terra
A few repos or foldersrepeat --repo / --include
Everything except personal stuffsetup --dsn … --ignore ~/personal
Only counts and timings, no prompts or codeadd --content metadata
Back to everythingsetup --everything

Rules:

  • Folder rules match that folder and everything below it; ~/code/terra does not match ~/code/terraform.
  • Repo rules (--repo or --include repo:owner/name) match on the folder's git origin remote, so worktrees anywhere count. --repo terra matches any owner.
  • Ignore rules always win.

Spans carry vcs.repository.name, so you can also slice by repo in Sentry.

Replay past sessions

New sessions are sent automatically. To send older ones, use replay (alias backfill). Do a dry run first:

npx @sentry/tattletale verify --days 7                        # local token reconciliation, sends nothing
npx @sentry/tattletale replay --days 7 --dry-run              # what would be sent from the last week
npx @sentry/tattletale replay --since 2026-10-01 --until 2026-10-15
npx @sentry/tattletale replay --session 4d64aace              # one session (ID or prefix)
npx @sentry/tattletale replay ~/Downloads/old-transcripts     # files or folders, e.g. from another machine
  • Never doubles. Spans already in Sentry are skipped, so replaying the same range twice sends nothing new.
  • Your scope still applies. Sessions outside your folder and repo rules are skipped.
  • Oldest first. Sessions are replayed in age order, so an original session claims history that a later fork copied.
  • Files and folders count as finished. Explicit files or folders are treated as complete sessions. Folders are searched for *.jsonl and *.jsonl.zst, with Codex archives included, and for OpenCode exports (ses_*.json, as written by opencode export). Without paths, OpenCode sessions are read from its database. Pi sessions are recognized by their file names (<timestamp>_<id>.jsonl).

Limits:

  • Sentry retention. Sentry drops spans older than the project's retention at ingest.
  • Claude Code cleanup. Claude Code deletes transcripts after 30 days by default. Set cleanupPeriodDays higher in ~/.claude/settings.json to keep more history replayable.

npx @sentry/tattletale --help lists every command.

Development

pnpm install
pnpm check   # tsc (strict) + oxlint + oxfmt --check + tests
pnpm build   # dist/ (what npm ships; Node won't strip types under node_modules)

scripts/ holds one-off token analyses over local transcripts (token-waste.ts, cache-causes.py, …); each prints its usage at the top. Releases go through craft. See RELEASING.md.

How it works

agent hook (Claude Code, Codex: SessionStart / Stop / SubagentStop / SessionEnd, async;
            OpenCode plugin: session.created / session.idle;
            Pi extension: session_start / agent_settled / session_shutdown)
  └─ hooks/run.sh → cli.ts hook    queue a job, spawn a detached worker, exit 0 (never blocks the agent)
       worker: stream the transcript → build spans with deterministic IDs → take the send lock
               → drop IDs already in ~/.tattletale/sent.log → send new ones (OTLP/HTTP JSON) → append to ledger

The queue is only a wake-up signal: the transcripts and the ledger are the state, so a lost job loses nothing. On a hook, at most every 5 minutes, the worker also sweeps:

  • recently modified transcripts that aren't settled yet, which catches sessions whose hooks never fired;
  • any transcript with spans still unsent, however old, which retries sends that failed.

A transcript that crashes tattletale is reported as an error and left alone until it changes or tattletale is upgraded.

OpenCode has no transcript file: it keeps every session in one SQLite database (~/.local/share/opencode/opencode.db). Its plugin only tells the hook which session changed. tattletale opens the database read-only, writes the session and its subagents (child sessions) to ~/.tattletale/opencode/<id>.json, shaped like opencode export output and stamped with the session's last activity, and from there treats it like any other transcript.

Pi appends each session to a JSONL file under ~/.pi/agent/sessions/. Its extension hands the hook that file. Pi writes only finished requests, so every assistant entry is one complete model call. Pi also records usage for its side requests (cache warming, compaction and branch summaries, and model calls a codemode script makes); those are sent as calls too, marked agent.call.hidden where nothing was written but the usage. A session branched with /tree keeps every branch in the file, and each branch is sent.

Only one process sends at a time on a machine (hook workers, replay, sync). Each re-reads the ledger under that lock, so two of them never send the same span.

The tool's own failures (a parser crashing on a new transcript format, a hook failing) are sent to the same DSN as Sentry error events. Format drift shows up as an issue instead of a silent gap in the data. tattletale test-error sends one through the same path.

  • A model call is sent once it's known to be complete, tool calls once they have a result, and the turn root once the turn ends. Long sessions grow over many traces in a single conversation.
  • Each chat span carries only that call's new input messages, never the full history.
  • Turn totals use agent.turn.*, not gen_ai.usage.*, so summing gen_ai.usage.* never double counts.

Claude Code via native OpenTelemetry (optional)

install --otel switches Claude Code from transcripts to its own OpenTelemetry export. Codex always uses transcripts, because its OTel is mostly internal tracing. The command:

  1. Writes Claude Code's telemetry variables into ~/.claude/settings.json under env: enhanced traces on, logs on, OTLP/HTTP JSON, endpoint http://127.0.0.1:43181, and content flags when content is full. It refuses if you already set OTel differently, unless you pass --force, and keeps a settings.json.tattletale.bak backup.
  2. Starts the relay. After that, the SessionStart hook starts it whenever it isn't running.

The relay (src/relay.ts):

  • Holds each trace until it has gone quiet.
  • Rewrites it to Sentry's gen_ai conventions together with Claude Code's log events (src/otel-claude.ts):
    • usage is renamed, and input includes cache;
    • messages are rebuilt from the user_prompt, assistant_response and tool_result events;
    • tool output comes from tool.output span events;
    • subagents move into the session's conversation;
    • personal fields are dropped.
  • Applies include and ignore using the session's working directory, read from its local transcript.
  • Forwards to the DSN.

Compared with transcripts, it adds model calls that never reach the transcript (for example, the agent_classifier side calls), time to first token and real request timing.

One source per session. Sentry's conversation view doesn't deduplicate, so a session must never be sent twice:

  • Once the relay has seen a session, transcript sync sends only turns that started more than 2 minutes before the relay's first span.
  • A session touched since the switch that the relay never saw waits, then falls back to its transcript after 30 idle minutes.

uninstall --otel removes only the variables it wrote and switches back to transcripts.

Guarantees and how they're checked

GuaranteeMechanismCheck
Each API response counted onceClaude: dedup by message.id (one response spans several lines). Codex: token_usage_record per response, else deltas of the cumulative token_count (repeats ignored). OpenCode: one call per step-finish, keyed on OpenCode's own message/part IDs; a request still streaming isn't sent. Pi: one call per assistant entry and per usage recordverify: parser vs a naive count over the raw files, on every local session
Resumed/forked history not re-sentClaude copies keep the parent's sessionId and are skipped. Fork subagents' copies are claimed by the first file. Codex: everything before the first own task_started is inherited. Pi: entries older than a fork's header are the parent'stests; verify session-wide union check
Copies with rewritten IDs not re-sentSpan IDs come only from globally unique call/tool/prompt IDs, so the ledger dedups across sessionstest rewritten copy
Tokens match Sentry's conventioninput includes cache reads and writes (Anthropic's doesn't). Claude cache writes split 5m/1h. Claude thinking tokens and Codex reasoning tokens reported separately. OpenCode's input excludes cache and its output excludes reasoning; both are added back. Pi's input excludes cacheverify: chat-span sums = parser; E2E: Sentry aggregates = transcript = Claude's own cost-state, to the token; Codex, OpenCode and Pi calls = OpenRouter's billing per call
Never double sent after a crashThe batch in flight is written to pending/; on recovery its IDs are marked unverified and never re-sent (at-most-once)test crash between send and ledger write
Never double sent after a lost answerA request that may have reached Sentry (timeout, connection dropped after the upload) is treated like a crash: its spans are marked unverified and never re-sent, because Sentry only folds a repeated span into the first for seconds. One that can't have left (offline, DNS, refused) is retriedtest real sockets
Never double sent by two processesOne send lock per machine; the ledger is re-read under it, so a replay next to the hook worker can't re-send what the other senttest two processes
Failures don't lose data or loop foreverA failed send (network, outage, rate limit, refused DSN) leaves the ledger untouched and the session unsettled; the sweep retries it on a later hook, however old it is by then. Only a payload Sentry rejects (400, 413, 422) is bisected, and the one bad span skippedtests

Results on the author's machine (2026-11-11): verify passes on all 2,113 local sessions (1,081 Claude Code and Codex, Apr–Nov 2026; 1,032 OpenCode). A session still running can fail it for the moment: its file grows between the two reads, and a subagent still at work has no root span yet. The E2E runs against Sentry (Claude Code on this machine, Codex, OpenCode and Pi in containers against OpenRouter) matched to the token.

Token-analysis attributes

  • chat spans:
    • agent.call.context_growth_tokens: tokens added since the previous call
    • agent.call.uncached_input_tokens
    • agent.call.cache_break, agent.call.cache_read_drop_tokens
    • agent.call.idle_seconds: gaps longer than the cache TTL show up here
    • agent.call.hidden: usage with no persisted output, e.g. Codex background checks, Pi cache warming
    • agent.usage.cache_write_5m / agent.usage.cache_write_1h
  • execute_tool spans:
    • agent.tool.result_bytes, agent.tool.result_tokens_est
    • agent.tool.file_path, agent.tool.command, agent.tool.mcp_server
    • agent.tool.calls: the tools a Codex code-mode exec script calls (exec_command,apply_patch), since Codex now routes most tool use through that one tool
  • Turn and subagent roots: agent.turn.* / agent.subagent.* totals. Compactions get compact spans with pre- and post-compaction token counts.

Known gaps

  • Agents: Claude Code, Codex, OpenCode (its SQLite-era releases, 1.x) and Pi (1.x). Cursor transcripts have no tokens or timestamps, so it would need hook payloads. Copilot isn't done.
  • Model calls an agent makes without writing them to the transcript are invisible: Claude's safety checks, OpenCode's session-title requests (about 550 tokens each, on its small model). verify reports the gap against Claude's cost-state record when one exists.
  • An OpenCode request cut off mid-stream has no recorded usage and is not sent.
  • Pi records no model name for the model calls of a codemode script, only their usage: they're sent with model unknown.
  • Sentry's own Pi extension (@sentry/pi) traces Pi live. Use one or the other for a Sentry org, not both, or each session shows up twice.
  • A batch whose send got no answer, or was in flight during a crash, is never re-sent. If it had not arrived, those spans (up to 200) are missing. status counts them as unverified.
  • Sentry's computed cost has a single cache-write price. Claude's 1h cache writes cost more, so Sentry undercounts. The 5m/1h split is sent for your own math.
  • Sentry's timeline shows tool-role messages as user messages.
  • Sentry's conversation view looks up a conversation across the whole org. If the same session is sent to two projects in one org, the view merges both copies and doubles every count. Send a session to one project only.
  • Claude Code stores thinking without its text, and Codex keeps reasoning encrypted, so reasoning shows up only as token counts.
  • Every sync re-parses the whole transcript. That's fine locally (a 2,000-call session takes about a second); a byte-offset checkpoint would remove it.
  • Secret scrubbing is a regex pass. --content metadata drops all message content.

// faq

What is tattletale?

Tattles on your coding agents: Claude Code and Codex sessions in Sentry agent tracing. It is open-source on GitHub.

Is tattletale free to use?

tattletale is open-source under the MIT license, so it is free to use.

What category does tattletale belong to?

tattletale is listed under devtools in the Claudeers registry of Claude-compatible tools.

10 views
★ 10 stars
unclaimed
updated 8 days ago

// embed badge

tattletale on Claudeers
[![Claudeers](https://claudeers.com/api/badge/tattletale.svg)](https://claudeers.com/tattletale)

// retro hit counter

tattletale hit counter
[![Hits](https://claudeers.com/api/counter/tattletale.svg)](https://claudeers.com/tattletale)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how tattletale connects across the ecosystem