# setup-tattletale

Adopt this skill: https://proskills.md/skills/other/getsentry-tattletale-skills-setup-tattletale

Page: https://proskills.md/skills/other/getsentry-tattletale-skills-setup-tattletale
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/setup-tattletale/SKILL.md
size: 5074
sha: a2e29f1ba87301369580c099887d1d331445f69e
upstream: https://github.com/getsentry/tattletale/blob/main/skills/setup-tattletale/SKILL.md

````text
---
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`.
````

## File: README.md
upstream: https://github.com/getsentry/tattletale/blob/main/README.md

````text
# tattletale

Paste this to your coding agent:

```text
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`](https://www.npmjs.com/package/@sentry/tattletale).

## Quick start

```bash
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](skills/setup-tattletale/SKILL.md)). Tell
Claude Code or Codex: _"set up tattletale, send to <DSN or Sentry project>, 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/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:

```bash
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

```bash
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](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
````
