TruthTrail README.md privacy.md How it works Pricing npm

Your agent made a product call. The ticket should know.

When Claude Code, Cursor or Copilot decides something your ticket didn't cover, TruthTrail posts it on the Jira ticket or GitHub issue. The person who wrote the ticket confirms or rejects it, and your PR check shows what's still open.

How it works
  1. 1Your agent decides
  2. 2Comment appears on Jira
  3. 3Reporter confirms or rejects
  4. 4PR check updates
terminal
JiraSHOP-231

SHOP-231

Discount codes at checkout

Users can enter a discount code at checkout and see the new total.

Comments

PR #48 on SHOP-231/discount-codesTruthTrail check: 1 decision waiting

An example. Names and ticket are made up.

## the gap

The answer lives in a chat that nobody else reads.

A coding agent can't leave a question open. It asks you or picks something sensible, and the code ships. The person who wrote the ticket was never in that conversation.

agent sessionlocal
agentShould an expired code show an error, or be ignored quietly?
youIgnore it, keep checkout moving.
agentDone. Expired codes are skipped without a message.

session closed

SHOP-231last edited 9 days ago

SHOP-231

Discount codes at checkout

Acceptance criteriaUsers can enter a discount code at checkout and see the new total.

QA, a week later: “Bug: expired code is silently ignored.”

## how it works

A trail between your repo and the ticket.

your repo

the ticket

once per repo

Run npx truthtrail init

Adds rules your agent follows and a local MCP server. Commit the result.

your agent

Records what it decided

Questions it asks you and assumptions it makes, filed under the ticket in your branch name.

truthtrail[bot]

Posts it on the ticket

One summary comment on the Jira ticket or GitHub issue, and a mention for the person who wrote it.

the reporter

Replies /confirm D-2

Or /reject D-2 with a reason. On GitHub Issues they can hand it to someone else.

your agent

Reads the answer

Before it implements, it checks the ticket's decisions and reworks anything rejected.

pull request

The TruthTrail check

Rejected fails, waiting stays neutral, all confirmed passes. Your lead can make waiting fail too.

## works with

Keep your agent, your tracker and your code host.

layersupportedhow
Coding agentsClaude CodeCursorGitHub Copilot

A local MCP server and a rules block in AGENTS.md. The CLI works where MCP is blocked.

TicketsJira CloudGitHub Issues

Ticket keys come from branch names. GitHub issues can live in a separate tracker repo.

PR checksGitHub

A GitHub App posts the check, for Jira and GitHub Issues teams.

## by role

Everyone reads the same answer.

Answer the agent once. It goes where the team can see it.

  • The agent records decisions as it works. You don't write a status update.
  • No ticket key in the branch name? The agent asks once and remembers it for that branch.
  • Recorded on the wrong ticket? truthtrail move D-3 SHOP-240.
  • Offline, decisions queue up and are sent with your next command.

See what the code assumed about your ticket, before it ships.

  • One comment on your ticket lists every decision and its status.
  • Reply /confirm D-1, or /reject D-1 with a reason the agent will read.
  • On GitHub Issues, hand a decision to someone else with /confirmer @name.
  • You are mentioned when a decision is waiting for you.

Connect once. Choose how strict the PR check is.

  • Connect Jira Cloud with your Atlassian account, or install the GitHub App.
  • On GitHub Issues, choose who confirms: the issue author, a named list, or both.
  • Make waiting decisions fail the check, and require it in branch protection.
  • People only see decisions on tickets they can open.

Test against what was agreed, not a stale ticket.

  • The ticket's summary comment shows confirmed and rejected decisions next to the acceptance criteria.
  • A confirmed decision explains behaviour that would otherwise look like a defect.
  • npx truthtrail why src/checkout/discount.ts:9 shows the decisions behind a line.

## your data

We store decisions. Never your code.

Without signing in, everything stays in .decisions/ in your repo. Signed in, this is what the server keeps for one decision.

D-2 on the serverexample
{
  "ticket": "SHOP-231",
  "type": "assumption",
  "question": encrypted,  // AES-GCM at rest
  "chosen": encrypted,
  "reason": encrypted,
  "status": "waiting",
  "files": ["src/checkout/discount.ts"],
  "decidedBy": "you (Claude Code)",  // account id + name
  "prs": ["acme/shop#48"]
}
never stored
  • Source code, diffs or file contents
  • Your conversation with the agent
  • Ticket descriptions. TruthTrail never edits them
  • Passwords. Sign-in goes through Atlassian or GitHub
  • Analytics or tracking of any kind

    • Tokens for Atlassian and GitHub are encrypted too. Retention and deletion are in the privacy policy.

## pricing

Free while it's in beta.

Team pricing will be announced before the beta ends. Beta teams hear first and won't lose access without notice.

local

Free

One developer. Decisions stay in your repo.

  • MIT-licensed CLI and MCP server
  • Decisions in .decisions/, committed with your code
  • why, list and check

team

Freeduring beta

The reporter confirms, the PR shows it.

  • Decisions posted on Jira tickets or GitHub issues
  • Confirm and reject in ticket comments
  • TruthTrail check on GitHub pull requests
  • Decision history the whole team can read
Set up your team

## faq

Questions teams ask.

Does my agent need special setup?
npx truthtrail init adds a short rules block to AGENTS.md, which Claude Code, Cursor and Copilot read, and a local MCP server entry. It prints exactly what it changed. If your company blocks MCP servers, the agent uses the npx truthtrail commands instead.
What counts as a decision?
Anything the ticket doesn't settle that changes how the product behaves: a question the agent asks you, or an assumption it makes on its own. Code style and refactors aren't recorded.
What if the ticket key isn't in my branch name?
The agent asks you which ticket it is and remembers the answer for that branch. If a decision lands on the wrong ticket, move it with truthtrail move.
The reporter rejects a decision. What happens?
The summary on the ticket updates, the PR check fails, and the next time your agent reads the ticket's decisions it treats the rejected one as rework.
Our issues live in a separate GitHub repo. Does that work?
Yes. Your lead picks the tracker repo, and a branch like ABC-1234/discount points to issue 1234 there. Different prefixes can point to different repos.
Do I need the server?
No. Without signing in, TruthTrail works locally and keeps decisions in your repo. The server adds posting to tickets, confirmation by the reporter and the PR check.
Can we self-host?
Not yet. If your team needs it, tell us during the beta.

Start in your repo. Bring the team when you're ready.

$ npx truthtrail initadds
  • .decisions/ where decisions live, commit it
  • AGENTS.md a short rules block, your text untouched
  • CLAUDE.md a pointer, if you have one
  • .truthtrail.json config
  • MCP server entry for each AI tool it finds
Connect Jira Install on GitHub