⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.5.0

setup-tattletale

getsentry@getsentry⭐ 10 stars· last commit 3d ago· 0 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐ 10 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// 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 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

// 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

// REPO STATS

10 stars
0 open issues
Last commit: 3d ago