Installation

Prerequisites

Python 3.10 or later — the hook scripts are Python and use only the standard library. Check with python3 --version. 3.10 is a hard floor: the scripts use X | Y type annotations that are evaluated at import time and fail on 3.9.
Claude Code — the plugin attaches to Claude Code's hook lifecycle.
A Trenchcoat account at app.trenchcoat.io.

Step 1: Create an API key

Open app.trenchcoat.io and go to Settings → API Keys.
Click Create API Key and give it a descriptive name (e.g. my-laptop).
Choose a capture level. Every level can send events — they differ in what the server stores. Start with read:sessions and widen later if you want content captured; see Authentication.
Copy the key. It starts with ct_live_ and is shown once.

Step 2: Install the plugin

/plugin marketplace add pando-codes/pando-plugins
/plugin install trenchcoat@pando-plugins

Claude Code downloads the plugin and registers its nine hooks: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, and PreCompact.

Step 3: Add your key

Put the key in the env block of ~/.claude/settings.json:

{
  "env": {
    "TRENCHCOAT_API_KEY": "ct_live_..."
  }
}

Edit the file directly rather than pasting the key into a Claude Code conversation — anything you type in a session becomes part of that session's transcript. /trenchcoat:connect deliberately has no "paste your key" prompt for this reason.

Start a new Claude Code session now. Claude Code loads env at session start, so the key is not visible to the running session.

Step 4: Connect

In the new session:

/trenchcoat:connect

This reads the key from settings.json, validates it against the API, and writes the telemetry configuration — including the OpenTelemetry export settings, whose exact values are easy to get wrong by hand.

It also reads your key's scopes and sets the local content-capture flags to match, so Claude Code doesn't spend effort sending content the server would strip anyway.

If a different telemetry backend is already configured, connect stops and asks rather than overwriting it.

Start another new session afterwards, so the variables connect just wrote take effect.

Step 5: Verify

/trenchcoat:verify

For a full diagnostic — credentials, connectivity, event coverage, OTel configuration, and whether your local flags agree with your key's scopes — run:

/trenchcoat:doctor

doctor reports the running session's environment. If you have not started a new session since connecting, it will report stale OTel values; that is expected, not a failure.

What gets created on disk

Your data lives in its own directory, separate from the plugin's code:

~/.claude/trenchcoat/
  config.json                # non-credential settings
  events-YYYY-MM-DD.jsonl    # one file per day
  sessions.json              # session index
  .push_queue.jsonl          # events awaiting upload
  .pending/                  # in-flight tool calls
  .reconciled/               # recovered tool records

The plugin's own code lives under ~/.claude/plugins/cache/pando-plugins/trenchcoat/<version>/ and is managed by Claude Code — you should not need to touch it.

Credentials are not in config.json. They live in ~/.claude/settings.json, and leave your machine only in the X-API-Key header of outgoing requests.

See the Configuration guide for every setting.

Uninstalling

/trenchcoat:disconnect reverses what connect wrote to settings.json and stops uploads. Your local JSONL files are left alone — delete ~/.claude/trenchcoat/ yourself if you want them gone.

On this page