Plugin SDK Overview

The Trenchcoat plugin runs inside Claude Code and captures telemetry as you work. It attaches to Claude Code's hook system, intercepts lifecycle events, and sends structured event batches to your Trenchcoat workspace — giving you full visibility into how your agents use tools, spawn subagents, and consume tokens.

How it works

The plugin operates entirely on your local machine. No data is captured or transmitted until you connect it to your Trenchcoat API key.

Claude Code session
      │
      ▼
 Hook fires (one of nine lifecycle hooks)
      │
      ▼
 Hook script runs, out of process
      │
      ├──► appended to ~/.claude/trenchcoat/events-YYYY-MM-DD.jsonl
      │      (always — this is your local record)
      │
      └──► appended to .push_queue.jsonl
             (only when an API key is configured)
      │
      ▼
 Session ends → queue drains in batches
      │
      ▼
 POST /api/v1/events  →  Trenchcoat API  →  Supabase

Two things follow from this shape. Local capture works with no account — the JSONL file is written whether or not you have ever connected, so /trenchcoat:report and /trenchcoat:dashboard work offline. And uploads happen at session end, not on a timer, so the dashboard reflects a session once it finishes rather than while it runs.

If an upload fails, the events stay queued and go out with the next session's flush. Nothing is dropped.

Hook scripts run out of process and never block Claude Code.

What data is collected

Each event carries a session_id stable for the session, a UTC timestamp, a sequence number, and an event-specific data payload.

Four of these have a different name in your local JSONL than on the wire — tool_use is written as tool_start, and so on. See Event Schema for the mapping and the full field reference.

By default no prompt text, tool result, or branch name leaves your machine. What is stored is additionally gated server-side by your API key's scopes, independent of any local setting.

What you can do with this data

Once events are flowing into Trenchcoat, your dashboard shows:

• Sessions — a timeline of every Claude Code session, with duration and cost
• Tool usage — which tools fire most often, and which ones error
• Token attribution — tokens broken down by component type (tools, subagents, assistant turns)
• Cost — per-session and aggregate spend derived from model pricing

Supported platforms

Multi-platform support is on the roadmap. If you are building a custom agent and want to send events directly, the API Reference documents the ingestion endpoint — the plugin is just a convenience wrapper around it.

Next steps

Follow the Installation guide to get the plugin running in under five minutes.