A plain-text language for reasoning you can check.
📖 Book · ▶ Playground · 📁 Examples
Prose is good at stating a conclusion and terrible at showing its shape. You can write three confident paragraphs that quietly contradict themselves, and no tool will say a word.
ThoughtML is a small language that fixes that. You write down what you believe and why — claims, evidence, who holds what, how confident, as of when — and it reads back a typed, dated, defeasible graph. Then it reads that graph a second time, mechanically, and tells you where your own structure disagrees with what you said.
It's a mirror, not an oracle. It shows you the conflict. It does not make the call.
A hiring decision, written as ThoughtML:
focus strong-hire
kind claim
Alex is a strong hire.
focus aced-interview
kind observation
Aced the system-design round.
focus take-home-failed
kind observation
The take-home didn't run — tests were failing.
link aced-interview supports strong-hire
link take-home-failed opposes strong-hire
panel holds strong-hire
confidence 0.9 assumed
This document is clean — zero errors, zero warnings. The syntax is perfect. And
yet it's wrong, in a way no spell-checker or linter would ever catch. Run the mirror
over it (thoughtml --audit):
"audit": {
"conflicts": [
{
"kind": "confidence-vs-status",
"severity": "error",
"message": "`panel` asserts confidence 0.90 in `strong-hire`, but your own structure defeats it (argument status: out)"
}
]
}The panel is 90% sure of a claim its own recorded evidence defeats — it wrote
down that the take-home failed, then made the offer anyway. Nothing about the text is
malformed; the reasoning is. ThoughtML surfaces that gap and hands it back to you.
(And that 0.9 labels itself assumed, not measured — provenance you can see.)
That's the whole idea in one screen.
▶ Try it live in your browser →
the real parser, compiled to WebAssembly — type on the left, watch the reasoning graph build on the right. No install.
For as long as reasoning has been expensive to produce, it made sense to trust it by default. That's changing. An AI agent can now emit pages of structured argument at no cost — which means the scarce, valuable thing is no longer producing reasoning but auditing it.
ThoughtML is built for that world. The agent (or you) writes the reasoning down in a form that's explicit enough to check; a human, another agent, or CI reads it back and catches where the confidence betrays the structure. The point was never to compute the answer. It's to make reasoning legible enough that its flaws can't hide.
Writing ThoughtML with an AI? The whole language travels inside the tool. Run
thoughtml guide --fullfor the complete, source-derived spec (or readllms.txt) and paste it into a system prompt.thoughtml guidealone prints a one-screen tour;thoughtml guide <topic>looks up one section.
- Typed reasoning. A focus is an
observation,claim,hypothesis,option,decision,goal,assumption, … — not just a box. Foci nest into thought-trees: a claim and the reasoning that hangs off it, as one unit. - Defeasible evidence.
supports/opposes/undercutsform an argument graph; an opt-in grounded status reads every node asin/out/undecided. Purely structural relations (part-of,candidate-for) let you enumerate without silently inflating confidence. - Time is the spine. Beliefs are dated and ordered by valid-time. They can be
revised, and a dead end can be
abandoned— kept with its reason, not deleted. Redefining a focus never clobbers the first version; both are retained. Replay the whole thing as of any instant (--as-of, or the viewer's play button). Nothing is forgotten. - Honest numbers. One strength encoding — a numeric
weight— and every authored number can declare its basis:measured/estimated/assumed. - The mirror. An opt-in conflict report flags where your structure disagrees with
what you said: high confidence in a claim your own evidence defeats
(
confidence-vs-status), or the same focus defined two incompatible ways (definition-divergence). It reports; it does not decide.
ThoughtML is a language; this repo is its reference implementation. One parser is the single source of truth — everything else is that same parser wearing a different hat, so the browser, the CLI, and the exported file can never disagree.
| Piece | What it is | |
|---|---|---|
| Reference parser | Rust: source → surface AST → canonical objects → JSON, with diagnostics. The source of truth for the language. | crates/thoughtml |
| CLI toolchain | The parser as git-style subcommands — check, fmt, explain, diff — plus the mirror (--audit), the compute layer (--compute), as-of replay (--as-of), and standalone HTML export (--html). |
same crate |
| wasm build | The same parser compiled for the web, so the playground and the CLI can't drift. | crates/thoughtml-wasm |
| Playground | Live editor + reasoning graph (mermaid.live in spirit): a time-driven Viewer with replay and Follow-mode storytelling, a node-link Structural view, and one-click standalone-HTML export. | web · live ↗ |
| The book | Tutorial, complete language reference, the mirror, and practical guides. | docs · live ↗ |
llms.txt |
The whole language in one file — embedded in the binary, so thoughtml guide --full prints it too. |
llms.txt |
| Example gallery | 20 worked, strict-clean documents — an incident triage, a clinical differential, an AI moderation call, a security threat model, a self-auditing hotfix, and more. | examples |
You don't need any Rust to use the language — only to run the reference implementation.
Install the CLI — pick your ecosystem; all three ship the same binary, no Rust required:
pip install thoughtml # Python
npm install -g thoughtml # Node
cargo install thoughtml # RustPrebuilt binaries for macOS, Linux, and Windows are attached to every release.
Run the toolchain — the bare thoughtml <file> still emits the canonical JSON model:
thoughtml guide # the language itself, one screen (--full for all of it)
thoughtml examples/ship-the-hotfix.thml # canonical JSON + diagnostics
thoughtml --audit examples/ship-the-hotfix.thml # the mirror: where structure disagrees
thoughtml check --json doc.thml # diagnostics with stable codes + suggested fixes
thoughtml fmt -w doc.thml # format in the one canonical style
thoughtml explain doc.thml some-claim # why a node has its confidence / status
thoughtml diff before.thml after.thml # a semantic, belief-level diff
thoughtml --html -o record.html examples/choose-datastore.thml # bake to one interactive HTML fileFull reference: The CLI ↗.
Prefer not to install? Run any of it via cargo run -p thoughtml -- …, or just open the
playground.
Hack on the playground locally:
cd web && npm install
npm run wasm # build the parser to wasm (uses the rustup toolchain)
npm run dev- Decision records (ADRs) you can lint — the options, the evidence, and the open question that blocks sign-off, all checkable.
- AI-agent reasoning a human or CI can audit — the agent emits its reasoning; the mirror catches where its confidence betrays its own structure. (guide ↗)
- Design & code review of an argument — surface "you hold this at 0.9, but your own listed risk defeats it."
- Incident postmortems as checkable causal graphs, and research / claim maps with provenance on every number.
More in Use cases ↗.
v0.3.0 — the self-describing release. thoughtml guide now embeds the whole language
inside the binary — a one-screen tour, a section lookup, or --full for the complete,
source-derived spec to hand an AI — so an agent that runs cargo install can learn ThoughtML
with no website and no network. It builds on the 0.2.0 toolchain (check / fmt / explain
/ diff, the valid-time memory overhaul, and the standalone --html viewer). The full trail
is in CHANGELOG.md; the language as it stands today is in the
book. The surface may still move — hence 0.x, not 1.0.
Issues and ideas are welcome — open one here. The reference parser is the source of truth for the language and the docs are derived from it, so if the two ever disagree, that's a bug worth reporting.
MIT © 2026 Fatin Ishraq.