WTF (Why That Failed)

A flight recorder for incident troubleshooting inside Claude Code. WTF captures every tool call and manual observation into a durable SQLite database that survives context compaction, then enriches raw entries through a background classifier into a distilled timeline.

Prerequisites

• Claude Code CLI (claude)
• jq (JSON processor)
• curl or wget
• AWS credentials for Bedrock (optional — enables background classifier)

Installation

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash

This downloads a pre-compiled binary for your platform, installs the PostToolUse hook, and registers the MCP server. No clone or runtime required. Skills (/wtf, /wtf now, /wtf happened, /wtf imout) are delivered by claudecode-workflow.

Verify the installation:

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --check

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --version v1.0.0

Development Installation

If you're working on the WTF server itself, clone the repo and use the local installer (requires Bun):

git clone https://github.com/Wave-Engineering/mcp-server-wtf.git
cd mcp-server-wtf
./scripts/install.sh

Quick Start

# Start troubleshooting
/wtf

# Investigate the issue... Claude records tool calls automatically

# Get the distilled timeline
wtf_happened

# Add your own observations
/wtf now "DNS resolver returning stale records"

Architecture Overview

WTF is a three-layer system:

  /wtf, /wtf now          Skills (user-facing entry points)
        |
        v
  wtf_now, wtf_happened   MCP Server (journal storage, retrieval,
  wtf_freshell             background classification)
        ^
        |
  PostToolUse hook         Auto-capture (every tool call -> JSONL queue)

Layer 1 -- Skills: /wtf starts a troubleshooting session and activates flight recorder mode. /wtf now adds manual journal entries.

Layer 2 -- MCP Server: A Bun + TypeScript server exposing four tools over stdio transport. Manages a SQLite database, ingests the hook queue, and runs a background classifier (Claude Haiku via AWS Bedrock) that categorizes entries as actions, breadcrumbs, theories, or noise.

Layer 3 -- PostToolUse Hook: A shell script that fires on every Claude Code tool call, extracts relevant fields, truncates large values, and appends a JSON line to .wtf/hook-queue.jsonl for ingestion.

Usage

Starting a Session

/wtf

Archives any prior incident and creates a fresh one. Prompts for an optional title, then puts Claude into flight recorder mode where significant observations are journaled automatically.

Recording Observations

/wtf now the health endpoint is returning 503s
/wtf now "theory: connection pool exhaustion under load"
/wtf now checked nginx logs — 502s started at 14:32

Adds a manual entry to the journal. Classification is handled by the background classifier.

Getting the Timeline

Call the wtf_happened MCP tool (Claude can invoke it directly, or you can ask for it):

wtf_happened                  # summary (max 50 lines)
wtf_happened { detail: "full" }  # all entries

Returns a distilled Markdown timeline:

## WTF Summary -- DNS Resolution Failure
**Duration:** 45 min | **Entries:** 127 raw, 34 distilled | **Status:** active

1. [12:03] BREADCRUMB -- Health endpoint returning 503s intermittently
2. [12:05] THEORY -- Connection pool exhaustion, idle timeout set to 0
3. [12:08] ACTION -- Set DB_POOL_IDLE_TIMEOUT=30s in .env

Suspending Recording

/wtf imout

Suspends the flight recorder without losing data. Useful when switching to non-troubleshooting work. The hook still fires but entries are filtered.

Generating a Runbook

wtf_happened also writes a runbook skeleton to .wtf/runbook.md that can be refined into a reusable playbook.

Clearing / Starting Fresh

wtf_freshell

Archives the current incident and starts a new one. Previous entries are preserved in the database.

Configuration

Data Directory

All runtime data lives in .wtf/ relative to the project root (gitignored):

.wtf/
  wtf.db              SQLite database (WAL mode)
  hook-queue.jsonl    Hook queue (consumed by MCP server)
  runbook.md          Generated runbook skeleton

Tunable Values

Parameter	Default	Location
Queue poll interval	2,000 ms	queue.ts
Classifier poll interval	5,000 ms	classifier/worker.ts
Classifier rate limit	2,000 ms	classifier/worker.ts
Hook truncation limit	4,096 bytes	scripts/hooks/wtf-post-tool-use.sh
Summary line cap	50 lines	tools/happened.ts

MCP Server Registration

The remote installer registers the compiled binary:

claude mcp add --scope user --transport stdio wtf-server -- ~/.local/bin/wtf-server

The development installer registers the Bun source directly:

claude mcp add --scope user --transport stdio wtf-server -- bun /path/to/mcp-server-wtf/index.ts

Hook Configuration

The PostToolUse hook is configured in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "/absolute/path/to/scripts/hooks/wtf-post-tool-use.sh"
      }
    ]
  }
}

Uninstall

If installed via the remote installer:

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --uninstall

If installed from a local clone:

./scripts/install.sh --uninstall

Both remove the MCP server registration and hook configuration. The per-project .wtf/ data directories are preserved (they contain incident history). To remove them:

rm -rf .wtf/

License

MIT -- see LICENSE.