
tracetoon
io.github.Tracetoon/tracetoon
Writes GitHub PR descriptions from your coding agents' session logs, checked against them.
Documentation
PRs with receipts. And comics.
Your coding agent already kept the receipts: what you asked for, what it changed, what actually ran. Tracetoon turns them into a pull request reviewers can trust. Every claim is checked against the evidence, it costs less to write, and there's a comic on top.
| 83–34 | 69–17 | −46% / −31% |
|---|---|---|
| judges preferred the evidence-graph PR on Codex | judges preferred it on Claude Code | cost per PR on Codex / Claude Code |
prbench: 61 real PRs from 12 repositories, each written 3 times by each workflow, 2 AI judges per provider in both orders (732 judgments per provider), factual errors checked by two expert models. Compared with Tracetoon's earlier multi-agent workflow. See the full results, methods and caveats.
[!NOTE] For AI agents: start with AGENTS.md (how to run Tracetoon, exit codes, which commands publish) and docs/agents/install.md (install routes an agent can run, per host). docs/agents/use-cases.md lists the problems it solves, in the words users ask them. llms.txt indexes all three.
Contents: Quick start · Better PRs · Evidence graph · Embedded DB · Cost · Comics · Workflow · Under the hood · Install & update · Reference · Talk · Contributing
⚡ Quick start
1. Install it for every agent on your machine. It's one command, ships a prebuilt binary, and needs nothing else:
# macOS, Linux, Git Bash
curl -fsSL https://raw.githubusercontent.com/Tracetoon/tracetoon/main/install.sh | sh
# Windows PowerShell
irm https://raw.githubusercontent.com/Tracetoon/tracetoon/main/install.ps1 | iex
Or let your agent install it. Agent sandboxes often block piping a download into a shell, so these routes work better from inside an agent:
# Claude Code plugin
claude plugin marketplace add Tracetoon/tracetoon
claude plugin install tracetoon@tracetoon
Any other host: ask your agent to follow docs/agents/install.md.
2. Restart your agent. Then, on any branch with your work, ask:
"Open a PR for this branch with Tracetoon."
Or just let your agent run gh pr create as usual: a hook sends it through
Tracetoon. When the PR is up, you get a short report:
Tracetoon created PR #34: https://github.com/o/r/pull/34
Comic: included.
Left out: 1 session that may not belong to this PR.
Comics: tracetoon config set comic off|allowed|always (now: allowed)
Tracetoon works across a broad range of coding agents and IDEs. Recommended integrations are actively maintained and continuously compatibility-tested. Community Supported integrations are available on a best-effort basis.
Recommended: retested on every new release of the agent.
| Agent | Status |
|---|---|
| Claude Code (CLI, IDE extensions and desktop app) | ✅ supported |
| Codex (CLI, app and IDE extensions) | ✅ supported |
| Copilot (CLI, VS Code agent mode and JetBrains) | ✅ supported |
| Cursor (IDE and CLI) | ✅ supported (see notes) |
| OpenCode (CLI) | ✅ supported |
IDE workflows: VS Code and Zed with specific recommended agents; each says "verified" only once its own test passes (IDE workflows).
Community Supported: available and tested with every Tracetoon change, fixed on a best-effort basis.
| Agent | Status |
|---|---|
| Antigravity (CLI and IDE) | ✅ supported |
| Factory Droid (Droid CLI) | ✅ supported |
| Kilo CLI (CLI, and Kilo Code for VS Code and JetBrains, which run it) | ✅ supported |
| Kiro (IDE and CLI) | ✅ supported |
| Cline (CLI, VS Code and JetBrains extensions) | ✅ supported (see notes) |
| Junie (CLI and JetBrains IDE plugin) | ✅ supported |
| Devin (CLI and Devin Desktop, formerly Windsurf) | ✅ supported (uses Claude Code's hook; see notes) |
| Goose (CLI and desktop app) | ✅ supported |
| Qwen Code (CLI) | ✅ supported |
| Crush (CLI) | ✅ supported |
| Amp (CLI) | 🟡 partial (no session logs; see notes) |
| Zed (Zed Agent) | 🟡 partial (see notes) |
| Warp (Warp agent) | 🟡 partial (see notes) |
Hook files, skill folders, verification results and the notes: supported agents.
[!TIP] Already installed? Ask your agent: "Update Tracetoon." It works for the installer, the plugin and a hand-installed skill. See Install, update, uninstall for the details.
🧾 Better PRs: judged blind, picked almost every time
AI-written PRs are usually vague and padded, and they sound sure about tests nobody saw pass. Claude Code, Codex, Copilot, Cursor, Antigravity and 10 other agents already keep session logs on your machine. Tracetoon finds the sessions that produced this branch and turns them into a redacted evidence brief your agent writes from.
- Written from evidence. The PR covers what you asked for, the plan you approved, the decisions you made, and every test, build and lint run with its result. It never invents a motivation, and it never says "all tests pass" unless a run showed it.
- Honest about what's known. A run that passed before the last edits is described that way. Something that wasn't captured is "not captured", not "not done".
- Short and reviewable. The problem and the result come first, then the reason for the approach, what was checked, and where to start reviewing. There are no file-by-file lists and no test-count inventories.
- Checked before it's posted. Deterministic checks run first: a leak scan, freshness, and a claim check that marks sentences the evidence contradicts or doesn't establish. Then two cheap independent reviewers check the draft against the diff.
- Optional notes, never a form. Tracetoon lists what a reviewer may want that the logs don't show, such as a manual check or the reason for a choice. Add them or skip them.
- Your words stay yours. Text you write in the PR, or edit on GitHub later, is kept on the next update. Tracetoon only owns a marked region of the body.
Here is one real PR from the earlier 5-PR study, written three ways and scored 0–100 by the same judges:
| Who wrote it | Score |
|---|---|
| The agent alone | 47 |
| Tracetoon, old workflow | 65 |
| Tracetoon + evidence graph | 80 |
Across 61 real PRs from 12 repositories, judges preferred Tracetoon with the graph over its own no-graph workflow 83–34 on Codex and 69–17 on Claude Code. A pick only counts when two judges each read both orders and agree. On the 36 PRs the brief was never tuned on, the picks were 51–14 and 43–11.
🕵️ Evidence graph: every sentence has a receipt
Before any model writes a word, Tracetoon builds a small graph of your branch
(evidence-graph.json in the run folder). It links every change in the diff
back to the conversation that produced it:
flowchart LR
P[Your request] --> E[Agent edit] --> H[Hunk in the diff]
H --> C[Commit sentence]
E --> R[Test / build run]
R -. "edited after?" .-> H
- Credit goes to the right code. The brief names the function that owns each behavior and marks what's new and what only changed. It also flags code where a word like "always" would be wrong.
- Validation comes from receipts. Tracetoon writes the Validation section from the test and build runs on the final code. The model never gets to type "all tests pass".
- The why, not just the what. Plans, decisions and the original request come along with the code. On 61 real PRs, Codex drafts with the graph conveyed 82% of the expert fact sheet's claims, against 72% without it (on Claude Code it was about even: 75% and 76%).
- Relevance, not recency. The graph decides what the digest keeps when it has to trim, and names the files a cited test run didn't see.
Your agent asks the graph questions instead of rereading every fact and the whole patch:
tracetoon query brief # the compact evidence brief the drafter writes from
tracetoon query outline # changed units, their requests and checks
tracetoon query why src/foo.ts # which request and which runs are behind this file (or a hunk: H3)
tracetoon query unverified # changes no run saw after their last edit
tracetoon query stale R2 # what changed after run R2
tracetoon query --cypher 'MATCH (h:Hunk) RETURN h.file LIMIT 5' # read-only Cypher
Named queries also include verified, unexplained, turn <S#>, dead-ends,
pushback and schema. Results are capped per section; --all lifts the cap.
📦 Embedded database: a graph database that fits in your pocket
The graph runs on Relate, an open-source
embedded graph database written in Rust. Tracetoon ships it compiled to
WebAssembly (assets/relate.wasm.gz) inside the CLI.
- No server, no setup. It runs in-process on Linux, macOS and Windows, with no native modules and no database file. It works offline and builds a fresh graph for every PR. If it can't start, the digest is still written.
- Real queries, not guesswork. A few lines of Cypher answer questions like "which request led to this code?" and "did a test pass after the last edit?"
- Search links. A BM25 FULLTEXT index over each hunk's path, symbols and
lines ties commit sentences, requests and plans to the hunks they describe. A
link is kept only when an exact name or path agrees, or when one file clearly
leads. Turn it off with
prepare --graph-search none. - Same evidence in, same brief out. Every fact traces back to a hunk and a session line, so you, or another agent, can audit any sentence.
[!NOTE] 0 tokens to build the graph and the evidence brief. It's a deterministic step, not a model call. Relate is the open-source successor of cypherlite, which earlier releases embedded.
TRACETOON_RELATE_WASMpoints at a different build;TRACETOON_CYPHERLITE_WASMstill works as a deprecated alias.
💸 Cost: a sharp brief lets cheap workers check the work
Without a map, an expensive model rereads your source to check its own claims, two or three times per PR. With the graph, that work is done once, before any model runs. Then:
- One strong writer drafts from a 2–3K-token brief instead of the whole session history, and writes about 7K tokens instead of 22K.
- Two cheap reviewers check a short packet in parallel: one with the
completeness lens, one general. They run on the host's cheap model at
xhigheffort (haikusubagents on Claude Code,lunapasses started bytracetoon review runon Codex). That's about 4¢ per PR on Claude and under 1¢ on Codex. - One edit pass. The reviewers' findings merge into a single list. There
are no repeat review rounds, and
publishrefuses until both passes are imported.
| Setup (61 real PRs) | Cost per PR |
|---|---|
| Claude Code, no graph | $0.654 |
| Claude Code + graph | $0.415 |
| Codex, no graph | $0.447 |
| Codex + graph | $0.225 |
Averages per PR; the typical paired saving is 31% on Claude Code and 46% on Codex (how cost is measured).
Tuning the review plan
The defaults are the variant lines at the end of the Workflow section in the
skill's SKILL.md. tracetoon prepare
takes a matching flag for each:
SKILL.md line | prepare flag | Values |
|---|---|---|
Reviewer model: cheap. | --reviewer-model | cheap, a model name, or same |
Reviewer effort: xhigh. | --reviewer-effort | low, medium, high, xhigh, max, default |
Review passes: 2. | --review-passes | number of fresh reviewer passes publish requires |
Review lenses: d. | --review-lenses | lenses a–d or none; one pass per lens |
Reviewer runner: auto. | --reviewer-runner | agent (drafter starts it) or tracetoon (review run) |
Review recheck: none. | --review-recheck | once, contested or none |
Brief layout: toon. | --layout | toon, neighborhood, neighborhood-wide |
Graph search: fulltext. | --graph-search | fulltext (bm25) or none |
On an unknown host, reviewers use the main agent's model and the agent starts them. The graph doesn't turn a small model into a mid-size one: Haiku as the writer still lost. The win comes from a strong writer plus cheap checkers.
🎨 Comics: a comic nobody asked for. Everyone reads it.

The comic Tracetoon made for PR #17, which removed the old recurring cast.
Each PR can get a one-off comic: a joke about how the work really went, with characters, a format and an art style made up for that PR. There are no mascots and no recurring cast.
- Formats. A gag strip, a before and after, a movie poster, an instruction manual and more. The drafter compares three short story, layout and cast concepts before one is drawn. Composition follows the joke: a single visual metaphor, a two-panel comparison, a vertical pause, unequal frames, insets or a diagonal split.
- Fresh every time. Tracetoon reads compact metadata from the repo's recent
comics (style family, layout, panel count, cast categories) and picks
something different. Pin a style with
tracetoon config set style "<idea>". - Proofread. An image model you choose draws the whole page, lettering
included.
comic renderprints every word for the agent to proofread, and adds a small "made with Tracetoon" footer bar. - It respects the repo. With the default
comic allowed, Tracetoon reads the repo's rules (contributing guide, code of conduct, agent and AI policy files, the README's contributing section, and the policy docs they link to) and skips the comic where they forbid images in PRs, naming the file and line, once per repo. Where a repo asks for comics, it says so. Yourcomic alwaysoverrides the repo; yourcomic offturns comics off everywhere, with nothing more said about them. - Decided up front. Tracetoon works out whether a PR should get a comic
before your agent writes it, and the agent draws it. A skip needs a reason
(
tracetoon comic skip --reason "…"), shown after the PR is created. - Never a blocker. Without an approved image route, or if drawing fails,
the PR is created without a comic, and the message after the PR says why.
A missing image route is mentioned once per machine, not on every PR
(
tracetoon images --dismissstops the setup offer too).
Set up an image route
Run tracetoon images to see which routes are on your machine, whether each can
draw, and what to do next. Approve one and check it really draws, using one
small test picture with no repo content:
tracetoon images # what's available and approved
tracetoon images --approve codex --test # approve a route and draw a test image
Your agent offers the same at the start of your first PR. comic art uses the
first approved route that can draw, in this order:
| Route | Needs | Prompts go to |
|---|---|---|
codex (recommended) | the Codex CLI, signed in with ChatGPT (codex login) | OpenAI, counted against your Codex usage |
antigravity (experimental) | the Antigravity CLI, signed in | Google, counted against your Antigravity quota |
openai | OPENAI_API_KEY (model gpt-image-2.5-flare, change with TRACETOON_OPENAI_MODEL) | OpenAI, billed to your key |
gemini | GEMINI_API_KEY or GOOGLE_API_KEY (model gemini-nano-banana-2.1, change with TRACETOON_GEMINI_MODEL) | Google, billed to your key |
A Codex set up for another model provider in ~/.codex/config.toml (a LiteLLM
proxy, say) has no image tool. After setting an API key, restart your agent so
it sees the key: on Windows, setx OPENAI_API_KEY "<key>"; on macOS or Linux,
add export OPENAI_API_KEY="<key>" to your shell profile.
[!IMPORTANT] Prompts contain only the comic's scenes and character descriptions, never code or log text. Nothing is sent until you approve a route, and only you can approve one: a repo's
.github/tracetoon.jsoncan't. To stop using a route, remove it withtracetoon config set imageConsent <list>, or turn a CLI route off withTRACETOON_CODEX_BIN=noneorTRACETOON_AGY_BIN=none.
🤝 Fits your workflow: it knows the house rules
- Nothing new to learn. Ask for a PR, or let your agent run
gh pr create. There is no preview or approval step: the agent prepares the PR, has it reviewed, creates it, and tells you what it did. Finishing a task never opens a PR on its own, andpublishnever merges. - Follows the house rules. Tracetoon reads each repo's AI policies,
AGENTS.md, PR templates and contribution guides. It adds any disclosure the repo asks for, and it reports any policy against AI contributions (your request for the PR is the override). - Private by default. Logs are read on your machine. Secrets, personal data, your home path and your username are redacted from the evidence. Only the rendered PR text and the comic are published.
The PR hook
The installer adds a small hook to each agent. When an agent tries to open a PR, the hook points it to Tracetoon instead.
| Redirected to Tracetoon | Left alone |
|---|---|
gh pr create and gh aliases for it | git push (branches for CI, tags, release commits), gh pr edit |
hub pull-request, git-extras git pull-request, Git Town git town propose | Stacking tools: Graphite, git-spice |
Writes to GitHub's pulls API through gh api, hub api, curl, wget, HTTPie or PowerShell | API reads, state-only changes (closing a PR), other forges |
GraphQL createPullRequest, and the GitHub connector tools agents use | Calls made inside a script, or a GraphQL mutation read from a file (can't be seen) |
The hook only touches its own entries in each agent's config, backs up each file
before the first change, and lists every file it changed. Codex asks you to
trust a new hook once (/hooks), and again whenever the hook entry changes;
tracetoon doctor says when Codex would skip it. The Antigravity IDE picks it
up after a restart. Goose runs hooks with sh, so on Windows it needs Git for
Windows' usr\bin on PATH. Where each agent keeps its hook is listed in
supported agents. Skip
installing it with TRACETOON_NO_HOOK=1, or manage it with
tracetoon hook install and tracetoon hook uninstall.
Turn it off at whichever level you need
Any "off" wins, with one exception: your own comic always beats a repo's comic "off".
| Scope | Off | On again |
|---|---|---|
| One command | TRACETOON=0 gh pr create ... | (just once) |
| You, everywhere | tracetoon off | tracetoon on |
| This repo, for everyone | tracetoon off --repo (writes .github/tracetoon.json; commit it) | tracetoon on --repo |
| This repo, just you | tracetoon off --local (git config) | tracetoon on --local |
| CI | off automatically when CI=true | TRACETOON=1 |
| Comics, one PR | ask your agent to skip the comic | (just once) |
| Comics, you everywhere | tracetoon config set comic off | tracetoon config set comic allowed (or always) |
| Comics, this repo for everyone | "comic": "off" in .github/tracetoon.json; commit it | remove it |
tracetoon status shows whether it's on here and which setting decided.
For comics, allowed (the default) follows each repo's rules: no comic where
its "comic" setting, contributing guide, code of conduct, README or a policy
doc they link to forbids images in PRs. always means every PR regardless.
🔧 Under the hood: from session logs to a reviewed PR
flowchart LR
D[doctor] --> PR[prepare<br/>digest + graph + context]
PR --> W[draft<br/>body.md + comic.json]
W --> RV[review<br/>2 cheap passes]
RV --> CA[comic art<br/>+ render]
CA --> RE[render<br/>leak scan + claim check]
RE --> PU[publish]
Your agent drives these steps from the skill; you normally never type them. Each
run lives in .git/tracetoon/runs/<id>/, which git never tracks. The newest 20
scratch runs are kept. Every command takes --json.
1. tracetoon doctor: can this machine make a PR?
Checks git and gh, whether you can push to the repo, which agent logs are on the
machine, and whether a comic can be drawn. --json also reports the actual
runtime and hook identities, installed skill mismatches and observed hook
events. doctor --probe lists log record types the readers don't recognize, so
format drift shows up early (--strict exits 5 if any are found).
2. tracetoon prepare: digest, evidence graph and context from one snapshot
prepare runs digest and context against one repository snapshot.
Digest. It reads the branch from git (base, commits, the exact lines added) and finds the agent sessions behind it. The evidence is:
- edits whose lines are still in the diff
- commits made during a session, including from worktrees since deleted
- PR links, the branch, timing and the working folder
It keeps your prompts, plans, decisions and each verification run, with how that
run relates to later edits. Everything is redacted. Sessions that may not belong
to the PR are left out and counted in the final message; use --include or
--exclude to override, and tracetoon scan to see every candidate session with
its score. --base <remote>/<branch> targets a base only another remote has.
--budget sets the digest size.
Graph. It builds evidence-graph.json and loads it into Relate, as described
above.
Context. It reads the PR template, AI policies and agent instructions, any
existing PR (and edits made to it on GitHub), your settings, and the art styles
of the repo's recent comics. It also prepares a contributor-research packet and
the submitted diff. --offline disables GitHub lookups and leaves external
references as collection gaps.
If the repo already records provenance with Entire checkpoints or git-ai notes, the digest says so.
3. Draft and review: one strong writer, two cheap checkers
Your agent writes body.md itself from tracetoon query brief and the patch,
and writes the comic brief comic.json. Two fresh reviewers then check it, as
described in Cost.
tracetoon review run starts pinned-model passes where the host supports it;
review import and review merge record and combine their findings.
When you ask for the most thorough PR, or there is no brief, your agent instead
coordinates a researcher and a separate drafter. The researcher collects
applicable local and linked guidelines, scoped instructions, conditions and
exceptions, and tracetoon guidance check validates that handoff. The drafter
receives the guidance, redacted traces and submitted code. Role prompts and the
versioned guidance.json and review.json contracts are in the
contribution workflow.
These roles use the host's native subagents, with no other model API or credentials. Hosts without delegation use a clearly labeled inline draft and self-review. Role identity is reported by the host, not certified by the CLI.
4. tracetoon comic art / comic render: draw and letter the page
comic check validates comic.json before any art is made. comic art draws
the page with your approved route (--provider picks one). comic render lays
out the page and prints the words to proofread. comic reroll redraws with a
new format that respects the story's panel count, and comic prompts prints
prompts for the host agent's own image tool. Changing the script or its
composition invalidates cached art and rendered output. The
art-direction guide
links the manga and joke-comic research behind these choices.
5. tracetoon render: freeze, scan and check
Builds the final body inside Tracetoon's marked region, so your own text is kept. Then it runs the leak scan and the claim check, lists optional notes, and prepares the exact rendered PR for the reviewers. Re-rendering shows current findings, source citations, collection gaps and missing evidence. Changed inputs invalidate old reviews.
A possible secret found by the leak scan stops posting until the text is
rewritten, or until you say the finding is fine (--allow-findings).
--no-comic leaves the comic out; --retitle replaces a title a person chose,
and only after you agree.
6. tracetoon publish: post exactly what was rendered
Posts the rendered PR right away. The comic goes on the repo's
tracetoon-assets branch, or as a GitHub attachment for private repos
(--hosting auto|branch|attach). Then gh creates or updates the PR in one
resolved target repo, which also works from forks.
- The branch is pushed if necessary.
--no-pushrequires it to already be on the remote at the rendered commit. --draftopens a draft PR.- Network retries reconcile an existing PR before creating a new one.
- The GitHub URL comes back without waiting for CI.
Nothing is posted from an old render. New commits or working-tree changes
need a fresh prepare and render; commit working-tree changes first.
Optional bookkeeping: task and check
Hooks observe session and repository metadata locally. They don't inject startup rules or require registration, branch changes or wrapped tests.
For explicit evidence receipts, tracetoon check --run <id> --name <name> -- <command>
runs a validation command and records the exact content it tested. Output
streams to stderr while it runs; stdout gets the final receipt. An interrupted
check doesn't count as a pass. --skip "<reason>" records a check deliberately
left to CI. task begin, task complete, task defer and task block track a
cohesive local change. All of this is optional.
tracetoon export --agent-trace writes the PR's line attribution as an
Agent Trace record.
📥 Install, update, uninstall

The installer puts a tracetoon command on your PATH and installs the skill and
PR hook for every supported agent it finds. It ends with a line about comics:
which image route it found and what to do next. Downloads are checked against
the release's SHA-256 checksums.
Update. Ask your agent "Update Tracetoon.", or run it yourself:
tracetoon update # install the latest release in place
tracetoon update --check # only report; add --exit-code to exit 10 when newer exists
tracetoon update --channel stable # ignore release candidates
tracetoon update --to 1.0.0-rc.24 # a specific release (also how to roll back)
update downloads the release and checks it against the checksums. It confirms
the skill and runtime are one build, then replaces the binary, comic assets,
every installed skill copy and the hooks together. If any step fails, it
restores the old files. Afterwards, reload your agent; Codex may ask you to
trust the new hook entries in /hooks.
tracetoon config set autoUpdate off|notify|installcontrols the session notice and background installs (defaultnotify).tracetoon config set updateChannel stable|latestpicks the channel (defaultlatest, which includes release candidates).TRACETOON_DISABLE_UPDATES=1blocksupdateentirely.- Re-running the installer also updates.
- On Windows,
updatein 1.0.0-rc.26 and earlier stops with "the downloaded binary does not run" and leaves the old version in place. Run the installer once (irm https://raw.githubusercontent.com/Tracetoon/tracetoon/main/install.ps1 | iex) to reach a version whoseupdateworks. updatecan't replace a Claude Code plugin or a source checkout in place: the plugin updates with/plugin marketplace update tracetoon, a checkout withgit pull. Asking your agent to update tells you which applies.
Uninstall. Set TRACETOON_UNINSTALL=1 and run the installer again.
Other ways to install
-
Claude Code plugin:
/plugin marketplace add Tracetoon/tracetoon, then/plugin install tracetoon@tracetoon. The plugin comes from thereleasebranch, which carries each published release with its built bundle;mainhas only source. Update it with/plugin marketplace update tracetoon, or turn on auto-update under/plugin> Marketplaces (third-party marketplaces start with it off), then run/reload-plugins. The plugin runs its bundled copy under Bun or Node 22+. For the prebuilt binary and the PR hook, run the installer once; after that,tracetoon updatekeeps everything in step andtracetoon doctorflags any copy that falls out of step. -
By hand: unzip
tracetoon-skill.zip, or a per-platformtracetoon-skill-<os>-<arch>.zipthat includes the binary, from a release into your agent's skills folder:Agent Folder Claude Code ~/.claude/skills/tracetoonCodex, Factory Droid, Copilot, Cursor, OpenCode, Kilo CLI, Cline, Devin, Goose, Crush, Amp, Zed, Warp ~/.agents/skills/tracetoonAntigravity ~/.gemini/config/skills/tracetoonKiro ~/.kiro/skills/tracetoonJunie ~/.junie/skills/tracetoonQwen Code ~/.qwen/skills/tracetoonCodex and Antigravity also read
.agents/skills/inside a repo. -
From source: see Contributing. A source checkout updates with
git pull.
The launcher. The skill ships bin/tracetoon (plus .cmd and .ps1). It
uses, in order: a binary next to it, the installed binary, Bun, or Node 22+ with
the bundled dist/tracetoon.mjs. With your permission it can instead download
the release binary and verify its checksum.
⚙️ Reference
Settings
tracetoon config get [key] and tracetoon config set <key> <value> manage your
user config in ~/.config/tracetoon/config.json (%APPDATA%\tracetoon on
Windows; override with TRACETOON_CONFIG). A repo can set shared defaults in
.github/tracetoon.json. Settings marked user only are ignored there.
| Key | Default | Meaning |
|---|---|---|
enabled | true | Use Tracetoon for PRs (also tracetoon on/off) |
comic | allowed | off, allowed (follow the repo's rules) or always. Your off/always beats the repo's. true/false mean allowed/off |
style | auto | Pin one art style for every comic (an idea from references/styles.md or any description) |
promptQuoting | paraphrase | verbatim quotes your prompts in the PR |
disclosure | assisted-by | Disclosure style (a repo's AI policy can ask for another) |
hosting | auto | Where the comic goes: branch, attach or auto |
budgetTokens | 12000 | Digest size |
imageConsent | [] | Image routes you approved (set by tracetoon images --approve). User only |
autoUpdate | notify | off, notify or install (background installs). User only |
updateChannel | latest | latest (includes release candidates) or stable. User only |
Commands
| Stage | Command | What it does |
|---|---|---|
| Setup | doctor | git, gh, push access, agent logs, image routes, runtime/hook identity |
images | image routes: available, approved, --approve, --test | |
update | check for and install a newer release in place | |
status, on, off | whether Tracetoon handles PRs here, and switches | |
hook install / uninstall | the agent PR hook | |
config get / set | settings | |
| Evidence | scan | sessions that match this branch, with scores |
prepare | digest + graph + context from one snapshot | |
digest, context | the two halves of prepare | |
query | ask the evidence graph (named queries or --cypher) | |
expand <refs> | full redacted evidence for a session, fact or commit:<sha> | |
source <paths> | snapshot base/head files as immutable review references | |
guidance check | validate the researcher's guidance.json | |
| Review | review run / import / merge, review-packet | reviewer passes and their findings |
| Comic | comic check / art / render / reroll / prompts | make this PR's comic |
| Ship | render | freeze body.md, leak scan, claim check |
publish | create or update the PR with exactly what was rendered | |
| Extras | check, task | optional validation receipts and change bookkeeping |
export --agent-trace | Agent Trace line attribution | |
build-info | runtime identity and capabilities |
Run tracetoon <command> --help for every flag.
Environment variables
| Variable | Effect |
|---|---|
TRACETOON=0 / TRACETOON=1 | Off for one command / on in CI |
TRACETOON_NO_HOOK=1 | Installer skips the PR hook |
TRACETOON_UNINSTALL=1 | Installer removes Tracetoon |
TRACETOON_DISABLE_UPDATES=1 | Blocks tracetoon update |
TRACETOON_CONFIG | Path of the user config file |
TRACETOON_OPENAI_MODEL, TRACETOON_GEMINI_MODEL | Image model for the API routes |
TRACETOON_CODEX_BIN, TRACETOON_AGY_BIN | Path to the Codex or Antigravity CLI, or none to disable it |
TRACETOON_RELATE_WASM | A different Relate WebAssembly build |
OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY | Keys for the API image routes |
🎤 Watch the talk
"Your PR says the tests passed. Prove it." At AI Engineer, Stephen Chin and Cassandra Chin explain why agent-written PRs need receipts, and how Tracetoon gets them from the session logs.
🙌 Contributing: AI welcome. Comics wanted.

[!IMPORTANT] AI-assisted and agent-written contributions are allowed here. Use whatever agent you like.
We strongly encourage opening your PR with Tracetoon, so it ships with receipts and a comic. It's the best way to show us what you asked for, what ran and what changed, and we love reading the comics.
You stay responsible for what you submit: read the diff, and let the evidence speak for the tests.
git clone https://github.com/Tracetoon/tracetoon && cd tracetoon
bun run dependencies:prepare # locked Showtail source from build-dependencies.json
bun install --frozen-lockfile
bun run typecheck && bun run test
bun src/cli.ts doctor # run straight from source; nothing to build first
Then ask your agent: "Open a PR for this branch with Tracetoon."
- Use Bun 1.3.14, as pinned in
build.config.jsonand CI. - Never commit real session logs. Fixtures are synthetic or scrubbed.
- The packaged suites (
test:bundled,test:compiled) run on every PR in CI. Locally they're optional; record them as left to CI rather than as passed. - The bundle is not committed:
bun run bundlebuilds it for packaged runs, and the release workflow publishes it on thereleasebranch.
CONTRIBUTING.md has the code layout, how to add an agent, evaluation scripts, the Relate WebAssembly pin and the release process.
Writing about Tracetoon, or adding "made with Tracetoon" to your project? The logo kit has the icon, wordmark and logos for light and dark backgrounds, as SVG and PNG.
tracetoon.ai ·
Evidence graph results ·
Built on Relate ·
@showtail/agent-traces
Apache-2.0. The bundled Comic Neue font is under the SIL
Open Font License (plugin/skills/tracetoon/assets/fonts/OFL.txt).
Tracetoon builds on @showtail/agent-traces, the log readers and
redaction shared with Showtail.
tracetoonnpm install tracetoon





