Skip to main content
plugin

trail — Claude Code plugin: what it does, how to install

Binds the trail MCP server to Claude Code for querying local runtime logs and runs a guided four-stage debugging workflow with mandatory cleanup.

MIT ★ 8 updated 2026-06-09

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/claude-plugins-community
/plugin install trail@claude-community
Open on GitHub

What trail does

This plugin registers the trail MCP server directly inside Claude Code, exposing the list_sessions and get_logs tools. The standalone tool records stdout and stderr from terminal commands or Docker containers into session-based JSONL files on your local drive. Filtering by log severity, regex, time intervals, or line offsets occurs on the server side, keeping raw output from cluttering Claude Code's context window.

It bundles the /trail:debug-with-trail skill, which activates on bug reports or crash questions. Claude first confirms that trail tracks the target process, inspects existing logs, inserts marked log statements if necessary, and finally purges every injected line using grep to verify zero leftovers.

The plugin only connects Claude Code to the tool — it does not bundle the executable, so the static trail binary must already be present in your PATH.

What it helps with

  • inspect runtime session logs without wasting Claude Code context tokens
  • diagnose server crashes and unexpected 500 responses locally
  • insert temporary debug logging with verified cleanup via grep
  • filter process or container output by regular expressions and timestamps

Example prompts for the agent

  • /trail:debug-with-trail Help me debug why the server crashes after a few minutes
  • List my trail sessions and show errors from the latest run
  • Trace why the worker is not picking up new queue jobs

How to install trail

Plugin marketplace

/plugin marketplace add anthropics/claude-plugins-community
/plugin install trail@claude-community

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about trail

How to install trail in Claude Code?

Run /plugin marketplace add anthropics/claude-plugins-community inside Claude Code, then execute /plugin install trail@claude-community. Make sure the standalone trail binary is installed on your system PATH beforehand.

What does the trail plugin do?

It connects Claude Code to local session logs captured by trail through MCP tools list_sessions and get_logs. It also gives the agent a structured debugging skill that audits logs first and cleans up temporary instrumented code after testing.

What prerequisites are needed before installing trail?

You need the trail binary on your system PATH. You can fetch the prebuilt executable for macOS or Linux via the official install script or compile it directly with go install github.com/Pratham-Mishra04/trail@latest.

Source text

claude-code · MIT
# trail — Claude Code plugin

Auto-wires the [trail](https://github.com/Pratham-Mishra04/trail) MCP server into Claude Code and bundles a debugging skill that walks the agent through capturing → querying → cleanup of runtime instrumentation.

## What this gives you

- **Auto-registered MCP server** (`list_sessions`, `get_logs`) — no manual `claude mcp add` step
- **`/trail:debug-with-trail` skill** that triggers automatically when you ask about debugging, errors, crashes, or "what's happening at runtime", and follows a 4-phase workflow:
  1. Verify trail is installed and the right process is being captured
  2. Read existing logs first (cheapest answer)
  3. Add targeted log statements with a unique cleanup marker, restart, capture, query — only when needed
  4. **Mandatory cleanup** of every line added in step 3, verified by `grep`

## Prerequisites

The plugin only wires up Claude Code — you still need the `trail` binary on your `PATH`.

```bash
# macOS + Linux — prebuilt binary, no Go required
curl -fsSL https://raw.githubusercontent.com/Pratham-Mishra04/trail/main/install.sh | sh

# or, if you have Go:
go install github.com/Pratham-Mishra04/trail@latest
```

Verify:

```bash
trail version
```

## Install

Add the marketplace, then install the plugin:

```bash
# In Claude Code:
/plugin marketplace add Pratham-Mishra04/trail
/plugin install trail@pratham
/reload-plugins
```

That's it. The MCP server starts on the next session; the debug skill is auto-discoverable.

## Verify it's working

Inside Claude Code, ask:

> *List my trail sessions.*

You should see Claude invoke the `list_sessions` tool. If you have no sessions yet, capture one first:

```bash
trail run -- <your command>
```

Then try again.

## How the debug skill triggers

The skill auto-invokes when you ask things like:

- "Why is my server returning 500s?"
- "Help me debug this — it crashes after a few minutes"
- "What's in the logs from my last run?"
- "Trace why the worker isn't picking up jobs"

The skill body is verbatim instructions to the agent; you can read it at [`skills/debug-with-trail/SKILL.md`](./skills/debug-with-trail/SKILL.md).

## Don't want the plugin?

You don't need it — the binary works on its own. Manual setup for Claude Code:

```bash
claude mcp add trail -s user -- trail mcp
```

For Cursor / Windsurf / Claude Desktop, see the config snippets in the [main trail README](https://github.com/Pratham-Mishra04/trail#editor-setup).

The trade-off: without the plugin, you don't get the debug skill — the agent has to figure out how to use the MCP tools on its own from their descriptions. Usable, just less guided.

## Updating

The plugin uses the `version` field in `plugin.json`. To update after a new release:

```bash
/plugin update trail@pratham
```

## Local development

If you've cloned the trail repo and want to test plugin changes locally:

```bash
# In Claude Code:
/plugin marketplace add /path/to/trail
/plugin install trail@pratham
/reload-plugins
```

Then edit files under `integrations/claude-code/` and `/reload-plugins` to pick up changes.

© Pratham-Mishra04 · MIT · Pratham-Mishra04/trail

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open