# TruthTrail

> TruthTrail is an open-source MCP server for developer tools. Posts your coding agent's product decisions on the Jira or GitHub ticket for sign-off. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://truthtrail.pages.dev
- **MCP Registry name:** io.github.truthtrail/truthtrail
- **Categories:** developer tools, productivity
- **Listing updated:** 2026-11-15

## About

A coding agent often has to pick an answer the ticket never gave, and the choice stays in a chat nobody else reads. TruthTrail records each decision as the agent works, files it under the ticket key found in the branch name, and posts one summary comment on the Jira Cloud ticket or GitHub issue. It mentions the person who wrote the ticket, who replies /confirm D-2 or /reject D-2 with a reason. Before implementing, the agent reads the ticket's decisions and reworks anything rejected.

A GitHub App adds a pull request check: rejected decisions fail it, waiting ones stay neutral, and all confirmed passes. A lead can make waiting fail too. The npx truthtrail why command shows the decisions behind a given line.

Without signing in, everything stays in .decisions/ in the repo. Signed in, the server keeps encrypted decision text, never source code, diffs or conversations. It supports Claude Code, Cursor and GitHub Copilot.

## Features

- **Decision log:** Agent questions and assumptions saved under the ticket in .decisions/.
- **Ticket comments:** One summary comment on Jira Cloud or GitHub Issues.
- **Confirm or reject:** Reporters reply with /confirm or /reject and a reason.
- **PR check:** Shows confirmed, waiting and rejected decisions on pull requests.
- **Why lookup:** Shows the decisions behind a line of code.
- **Privacy boundary:** Stores decisions only, not code or conversation.

## Good for

- Let ticket authors vet an agent's assumptions
- Block merging while a decision is rejected
- Explain odd behaviour during QA
- Trace why code was written a certain way

## Install

### Claude Code (Terminal)

```sh
claude mcp add truthtrail -- npx -y truthtrail
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "truthtrail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "truthtrail"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## FAQ

### Which agents and trackers work?

Claude Code, Cursor and GitHub Copilot, with Jira Cloud and GitHub Issues.

### How do I set it up?

Run npx truthtrail init once per repo and commit the result.

### What if the branch has no ticket key?

The agent asks once and remembers it for that branch.

### What does it cost?

Free while in beta; team pricing will be announced before the beta ends.

### What is stored on the server?

Encrypted decisions, never source code, diffs or conversations.

### Is TruthTrail free?

Yes. TruthTrail is open source, so you can use and self-host it for free.

### How do I add TruthTrail to Claude Code?

Run this command in your terminal: claude mcp add truthtrail -- npx -y truthtrail

### What are the best alternatives to TruthTrail?

The closest alternatives to TruthTrail are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/truthtrail
