# FailTrace

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/LBarimi/FailTrace  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/failtrace

## Description
Reproduce, compare, isolate, and minimize software failures with saved evidence.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "failtrace": {
    "command": "npx",
    "args": ["-y","failtrace"]
  }
}
```

## Documentation & README

# FailTrace

**Reproduce the failure. Check the fix.**

A test fails intermittently. Your coding agent changes the code. One passing retry leaves you guessing.

FailTrace repeats the same check, saves a failing baseline, and checks the proposed fix against it. Use the **CLI or MCP tools** to get trial results, a smaller reproducer, and evidence your agent can inspect before accepting a patch.

[![CI](https://github.com/LBarimi/FailTrace/actions/workflows/ci.yml/badge.svg)](https://github.com/LBarimi/FailTrace/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Local execution. No AI API, account, or telemetry required. Keep your existing test runner and assertions.

## Quick start

With **Node.js 22.12+ and npm**, run this in any working directory:

```sh
npx --yes failtrace demo
```

![FailTrace demo: capture a failure, reduce its input, reject an unrelated crash, and check a patch](https://raw.githubusercontent.com/LBarimi/FailTrace/HEAD/docs/assets/demo.gif)

[Static walkthrough](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/assets/demo.svg) · [Static poster](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/assets/demo-poster.png) · [Demo guide](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/DEMO.md)

The demo reduces six input items to `["BUG"]`, rejects a patch that crashes for another reason, and checks a working patch. It saves the evidence in `.failtrace/` and prints a replay command.

## For coding agents

Connect the local stdio MCP server through your client's configuration:

```sh
npx --yes failtrace@1.5.0 mcp --cwd "/absolute/path/to/your/project"
```

**[Copy the MCP configuration and check the connection →](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/AGENT-WORKFLOWS.md#mcp-client-configuration-and-windows-paths)**

Your client launches this command. Running it alone in a terminal waits for MCP requests. The guide includes Windows setup.

Then ask your agent:

> Use FailTrace to capture this test failure before editing. Choose the exact test or failure message, save a bounded baseline, and inspect the matching trial. After the change, verify against that baseline and explain any unrelated errors or incomplete evidence.

The seven MCP tools share the CLI's Core engine. They retain the failure signature and investigation evidence across repetition, comparison, regression search, minimization, verification and replay. Agents can retrieve saved trial and log pages without rerunning the command. Shell-capable agents can also use the CLI with `--json`.

![MCP workflow: capture the target, inspect saved stderr, and verify a declared patch](https://raw.githubusercontent.com/LBarimi/FailTrace/HEAD/docs/assets/agent-session.png)

The agent can inspect the saved failure before checking the patch.

## Recheck an existing unit test

**Follow an exact NUnit or Unity test through a fix.** Each attempt gets a fresh NUnit 3 report. Missing or skipped tests and unrelated failures stay inconclusive, so an agent cannot accept them as evidence that the selected test passed.

[Connect your test or try the original EditMode example →](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/UNIT-TESTS.md)

NUnit support is included in 1.3.0 through CLI and MCP. The documented Unity validation covers the Windows EditMode example.

![NUnit evidence: a failing baseline, a passing candidate, and a skipped test kept inconclusive](https://raw.githubusercontent.com/LBarimi/FailTrace/HEAD/docs/assets/unit-test-evidence.png)

The selected test stays the same; a skipped report is not accepted as a passing test.

## Use it on your own failure

From your project, replace the command and message with your own:

```sh
npx --yes failtrace@1.5.0 run "npm test -- checkout" --repeat 20 --stderr-contains "checkout failed" --capture-context
```

Run this **before editing** in a Git project. `--capture-context` records source identity for Verify; outside Git, select files with `--context-source`. Each trial saves its output, and exit `1` can mean the target was captured successfully. [Then edit and verify the patch →](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/VERIFY.md#capture-a-baseline-then-verify)

| Your next question | Command |
| --- | --- |
| How often does this failure appear? | `run` |
| What differs between a healthy and failing trial? | `compare` |
| Which Git change introduced it? | `bisect` |
| What input is enough to reproduce it? | `minimize` |
| What happened after the proposed fix? | `verify` |
| How can I replay this investigation? | `bundle` |

[Command reference](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/CLI.md) · [Literal executable arguments](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/DIRECT-EXECUTION.md) · [Reusable project scripts](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/PROJECT-WORKFLOW.md)

![A reduced input packaged with a replay entry point reproduces the target failure](https://raw.githubusercontent.com/LBarimi/FailTrace/HEAD/docs/assets/reproduction-bundle.png)

The demo's bundle reproduces its original failure with exit `1`. Keep the source, input and replay together; [supply the target's prerequisites](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/BUNDLES.md) when packaging your own investigation.

## What the results establish

FailTrace reports observations under the chosen settings. Verify separates a target observed, a healthy sample without that target, and inconclusive evidence. Bisect reports a sampled first-parent boundary; minimization rechecks its result without promising the smallest possible input.

The demo shows controlled example outcomes, not performance measurements. A passing sample does not prove a bug is gone.

Commands run with your permissions, and process cleanup is best effort. Retained stdout/stderr is capped by default at **16 MiB per trial and 256 MiB per run or bisect/minimization**. Previous investigations accumulate separately. Review logs, commands and selected files before sharing; bundles still require the target's dependencies and setup.

[Result and exit-code reference](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/CLI.md#artifacts-and-exit-codes) · [Resource limits](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/RESOURCE-LIMITS.md) · [Storage inventory](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/ARTIFACTS.md) · [Bundle guide](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/BUNDLES.md)

## Availability and contributing

The quick start uses npm's latest release; the verified version is **1.5.0**. MCP configuration and repeatable installation examples keep that exact version pinned: [installation options](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/INSTALL.md), [GitHub release](https://github.com/LBarimi/FailTrace/releases/tag/v1.5.0), and [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LBarimi%2Ffailtrace/versions/1.5.0).

**Version 1.5.0 adds:** [short run references](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/CLI.md#run-references), Verify readiness and next-step guidance, and intermittent-minimization guidance. See the [changelog](https://github.com/LBarimi/FailTrace/blob/HEAD/CHANGELOG.md).

**[Documentation: choose your next task →](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/README.md)**

[Development instructions](https://github.com/LBarimi/FailTrace/blob/HEAD/CONTRIBUTING.md#development) · [Compatibility](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/COMPATIBILITY.md) · [Roadmap](https://github.com/LBarimi/FailTrace/blob/HEAD/docs/ROADMAP.md) · [Third-party notices](https://github.com/LBarimi/FailTrace/blob/HEAD/THIRD_PARTY_NOTICES.md)