⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
setup-tattletale
Set up, scope, verify or remove tattletale, which sends Claude Code, Codex and OpenCode sessions to Sentry agent tracing. Use when the user asks to set up, install, configure, scope, check or uninstall tattletale, or to send their coding-agent sessions to Sentry.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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 want | Run |
|---|---|
| Only the terra repo, in any folder or worktree | setup --dsn … --repo getsentry/terra |
| Only sessions under a folder | setup --dsn … --include ~/code/terra |
| A few repos or folders | repeat --repo / --include |
| Everything except personal stuff | setup --dsn … --ignore ~/personal |
| Only counts and timings, no prompts or code | add --content metadata |
| Back to everything | setup --everything |
Rules:
- Folder rules match that folder and everything below it;
~/code/terradoes not match~/code/terraform. - Repo rules (
--repoor--include repo:owner/name) match on the folder's gitoriginremote, so worktrees anywhere count.--repo terramatches 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
*.jsonland*.jsonl.zst, with Codex archives included, and for OpenCode exports (ses_*.json, as written byopencode 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
cleanupPeriodDayshigher in~/.claude/settings.jsonto 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
chatspan carries only that call's new input messages, never the full history. - Turn totals use
agent.turn.*, notgen_ai.usage.*, so summing `gen
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/setup-tattletale/SKILL.md5.0 KBa2e29f1ba873upstream ↗
--- name: setup-tattletale description: Set up, scope, verify or remove tattletale, which sends Claude Code, Codex and OpenCode sessions to Sentry agent tracing. Use when the user asks to set up, install, configure, scope, check or uninstall tattletale, or to send their coding-agent sessions to Sentry. --- # Set up tattletale tattletale sends the user's Claude Code, Codex and OpenCode sessions to a Sentry project as agent traces: one conversation per session, model calls with exact token usage, tool calls, and subagents. Everything below runs on the user's machine. **The only thing it needs is the DSN of the Sentry project the data goes to.** Everything else has a default. ## 1. Get the DSN Use, in order: 1. A DSN the user gave you (`https://<key>@o<org>.ingest.<region>.sentry.io/<project>`). 2. The Sentry MCP, if it is connected and the user named an org or project. `find_dsns` returns an existing project's DSN; `create_project` creates one (suggest `coding-agents`) and returns its DSN. 3. Ask for it. It's under Sentry → Project Settings → Client Keys (DSN). ## 2. Decide the scope By default every session is sent. Ask once which sessions should go, unless the user already said. The choice decides what leaves their machine (prompts, code and tool output, scrubbed of common secret patterns). | The user wants | Flags | | ----------------------------------- | ---------------------------------------------------------- | | Everything | (none) | | One repo, in any folder or worktree | `--repo getsentry/terra` (or `--repo terra` for any owner) | | One folder and everything below it | `--include ~/code/terra` | | Several | repeat `--include` / `--repo` | | Everything except something | `--ignore ~/personal` or `--ignore repo:<owner/name>` | | Counts and timings only, no text | `--content metadata` | ## 3. Install ```bash npx @sentry/tattletale setup --dsn '<DSN>' [scope flags from step 2] npx @sentry/tattletale install ``` `install` adds lightweight hooks to whichever of Claude Code, Codex and OpenCode is installed (`--claude`, `--codex`, `--opencode` to pick). For Claude Code and Codex it shells out to `claude plugin …` and `codex plugin …`; for OpenCode it writes a plugin file to `~/.config/opencode/plugins/tattletale.js`, which OpenCode loads in sessions started afterwards. Hooks never block the agent. Tell the user that Codex asks them, once, to approve the new hooks under `/hooks`. You can't approve them for them. Until then, Codex sessions are still sent, in batches whenever another agent's session starts. Optional, for Claude Code only: `npx @sentry/tattletale install --otel`. This switches Claude Code to its own OpenTelemetry through a local relay. It adds request timing and model calls that never reach the transcript. It writes telemetry variables into `~/.claude/settings.json`, and refuses if the user already configured OpenTelemetry differently. Mention that it applies to sessions started afterwards. ## 4. Verify ```bash npx @sentry/tattletale status # DSN, scope, what was sent, relay, recent log npx @sentry/tattletale verify --days 1 # local token reconciliation; sends nothing npx @sentry/tattletale test-error # optional: proves the DSN accepts events ``` Data appears in Sentry under Explore → Conversations, usually within a few minutes. To send past sessions (`replay`, alias `backfill`), always dry-run first and show the user the counts: ```bash npx @sentry/tattletale replay --days 7 --dry-run # or --since 2026-10-01 [--until …] npx @sentry/tattletale replay --days 7 npx @sentry/tattletale replay --session <id> # one session npx @sentry/tattletale replay <file-or-folder> # transcripts copied from elsewhere ``` Replays respect the scope. Spans already in Sentry are never sent twice. Sentry drops spans older than the project's retention, and Claude Code deletes transcripts after 30 days unless `cleanupPeriodDays` is raised. ## Change or remove - Change the scope or DSN: run `setup` again with new flags. `--everything` clears the scope. - Pause: `TATTLETALE_DISABLED=1` in the environment, or `"disabled": true` in `~/.tattletale/config.json`. - Remove: `npx @sentry/tattletale uninstall --otel` (if OTel was installed), then `npx @sentry/tattletale uninstall`. ## Troubleshooting - The log is `~/.tattletale/tattletale.log`. Lines show `sync <agent> <session>: built=… sent=…` and why a session was skipped: `ignored path` (outside the scope) or `waiting for OTel relay` (it resolves by itself within about 10 minutes). - tattletale's own errors go to the same Sentry project as issues. - "no DSN configured": `setup --dsn` was not run, or ran with a different `TATTLETALE_HOME`.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/getsentry-tattletale-skills-setup-tattletale.md