Get started with TruthTrail

TruthTrail records the product decisions your coding agent makes and puts them on the ticket, where the person who wrote the ticket confirms or rejects them. Pick the guide for your role.

DeveloperInstall in your repo, log in, keep coding. Team leadConnect Jira or GitHub Issues once. Ticket reporterConfirm or reject decisions in the ticket. QATest against what was agreed.

Developers

1. Set up your repo

Run this once in each repo, then commit the result:

npx truthtrail init

init prints exactly what it changed. It adds:

.decisions/, where decisions live while you are not logged in
a short rules block in AGENTS.md, read by Claude Code, Cursor and Copilot. Your own text is never touched
a pointer in CLAUDE.md, if you have one
.truthtrail.json (config), and .truthtrail/ in .gitignore
a local MCP server entry for each AI tool it finds. Skip it with --no-mcp

Running it again is safe.

2. Claude Code plugin (optional)

The plugin loads the ticket's decisions when a session starts, and reminds Claude to record questions you answered before it stops.

/plugin marketplace add truthtrail/claude-plugin
/plugin install truthtrail@truthtrail

3. Keep coding

Name your branch after the ticket, like KAN-12/date-field or ABC-1234/login. When the ticket doesn't settle something, your agent asks you or makes an assumption, and records it with the record_decision tool. You can also record one yourself:

npx truthtrail decide --question "Empty date field?" --chosen "Use today's date"

Branch without a ticket key? The agent asks once and remembers it for that branch. You can set it yourself with npx truthtrail ticket ABC-1234.

4. Join your team

Once your team lead has connected the tracker, log in once on each laptop. After that, decisions go to the ticket instead of the repo.

npx truthtrail login            # Jira: browser opens, Allow, paste the code
npx truthtrail login --github   # GitHub Issues: enter the code at github.com/login/device
npx truthtrail status           # who you are, connection, queued decisions

A laptop has one TruthTrail login at a time. Logging in with GitHub replaces an Atlassian login, and the other way round.

Offline? Decisions are queued in .truthtrail/outbox.jsonl and sent with your next command, or now with npx truthtrail sync. Already have decisions in .decisions/? Upload them once with npx truthtrail import.

Set up a Jira team

A Jira admin or team lead does this once. You need Jira Cloud.

Connect Jira. Open the connect page, enter your space (project) keys, like KAN, PAY, then Connect Jira and accept on Atlassian. You become an admin for this site in TruthTrail.
Tell developers to run npx truthtrail login in their repo.
Add PR checks (optional). If your code is on GitHub, click Add PR checks on GitHub after connecting, or later from team settings. An owner of the GitHub org installs the TruthTrail App on the code repos. See PR check.

To add more spaces later, connect again with the new keys. Only people who can open a Jira issue can see its decisions.

Set up a GitHub Issues team

An owner of the GitHub organization does this once. Your issues can live in the code repo or in a separate tracker repo.

Install the App. Open the GitHub connect page and install TruthTrail on the tracker repo and on the code repos that should get the PR check.
Pick the tracker repo on the settings page that opens. A branch like ABC-1234/login then means issue #1234 there, whatever the prefix. If some prefixes live in other repos, add one rule per line, like WEB = acme/web-issues.
Choose who confirms. The default is whoever opened the issue. You can also name people or teams, like @acme/product, or allow both.
Tell developers to run npx truthtrail login --github.

Come back to settings any time at team settings.

The PR check

Every pull request whose branch, title or description names a ticket gets a check called TruthTrail. It updates by itself when the reporter answers.

Check	When
Failure	A decision on the ticket was rejected.
Neutral	Decisions are still waiting. Turn on Fail the PR check while decisions are still waiting in team settings to make this a failure.
Success	Every decision is confirmed.

To block merging until it passes: in the GitHub repo, open Settings → Branches, edit the rule for your main branch, turn on Require status checks to pass, and add TruthTrail.

For ticket reporters

You wrote the ticket, so you decide whether the agent's choices are right. You don't need to install anything.

TruthTrail keeps one summary comment on your ticket. It's updated in place as decisions arrive, so it may sit higher up the thread, marked “edited”.
You're @mentioned when a decision is waiting for you.
Reply in a new comment on the same ticket:

Reply	What it does
`/confirm D-2`	The decision is right.
`/reject D-2 Show an error instead`	The decision is wrong. The agent reads your reason and reworks it.
`/confirmer @rahul`	GitHub Issues only: let someone else confirm this issue.

In the summary, self-confirmed means the person who made the decision also confirmed it. Replaced means a newer decision took its place.

See every decision for your tickets on the decision history page.

For QA

The ticket's summary comment lists confirmed and rejected decisions. Test against those, not only the acceptance criteria.
A confirmed decision explains behaviour that would otherwise look like a defect.
From a checkout of the code: npx truthtrail why src/checkout/total.ts:42 shows the decisions behind a line, and npx truthtrail list --ticket KAN-12 lists a ticket's decisions.

Commands

Command	What it does
`init`	Set up the repo (rules, config, MCP entries)
`decide`	Record a decision: `--question`, `--chosen`, optional `--options`, `--reason`, `--ticket`, `--type assumption`
`list --ticket KEY`	List a ticket's decisions
`why file:line`	Show the decisions behind a line of code
`check --base main`	Check the branch's decisions locally
`ticket [KEY]`	Show or set the ticket for this branch
`move D-3 KEY`	Move a decision to another ticket
`withdraw D-3`	Withdraw a decision you recorded
`login`, `login --github`	Log in with Atlassian or GitHub
`status`	Who you are, connections, queued decisions
`sync`	Send queued decisions now
`outbox`, `outbox drop ID`	See queued decisions, or drop one
`import`	Upload existing `.decisions/` files once
`connect`	Open the page where a team lead connects Jira
`logout`	Forget this laptop's session

Run any of them with npx truthtrail <command>. Add --help for options.

MCP tools

Your agent uses these through the local MCP server that init sets up. Where MCP is blocked, it falls back to the commands above.

Tool	What it does
`record_decision`	Record a decision or assumption for the current ticket
`list_decisions`	Read the ticket's decisions before implementing
`why`	Decisions behind a file or line
`check_branch`	Check the branch's decisions
`list_pending`, `resolve_pending`	Questions you answered that aren't recorded yet
`set_ticket`	Remember the ticket for this branch
`move_decision`, `withdraw_decision`	Fix a decision on the wrong ticket, or withdraw one

Config

.truthtrail.json in the repo root:

Key	Meaning
`ticketPattern`	How ticket keys look. Default `[A-Z][A-Z0-9]+-\d+`, matched case-insensitively
`decisionsDir`	Where local records live. Default `.decisions`
`storage`	`repo`, `server` or `both`. Unset: `server` when logged in, else `repo`
`jiraSite`	Your Jira site, so logged-out teammates get a reminder
`server`	TruthTrail server URL. The `TRUTHTRAIL_SERVER` environment variable wins

Troubleshooting

“Not logged in. Run npx truthtrail login.”: Run npx truthtrail login, or npx truthtrail login --github for GitHub Issues teams.
“Space (project) KAN isn't connected to TruthTrail.”: Your team lead adds the space on the connect page.
“ABC-12 isn't connected to TruthTrail. Ask your team lead to pick the tracker repo…”: On GitHub Issues, the lead hasn't picked a tracker repo for that prefix yet. They do it in team settings.
“…could be in more than one connected GitHub org.”: Run the command inside a clone of the right org's repo, so TruthTrail can tell from the git remote.
The decision isn't on the ticket: Run npx truthtrail status. If decisions are waiting in the outbox, run npx truthtrail sync. A held one shows why; fix it and sync again, or drop it with npx truthtrail outbox drop <id>. Also look for the summary comment higher up the thread.
Recorded on the wrong ticket: npx truthtrail move D-3 KAN-14. The old ticket shows it as moved.
status shows a broken connection: The team lead reconnects: Jira at /connect, GitHub at /connect/github.
No TruthTrail check on a pull request: The branch, title or description must contain the ticket key, and the TruthTrail App must be installed on that repo. For Jira teams, the GitHub org must be linked in team settings.

Still stuck? Email modhdhairya@gmail.com.