<div align="center">

Atom of Thoughts

Structured reasoning for LLMs. Decompose, track confidence, visualize, approve.

</div>

---

Quickstart

1. Add to your MCP config:

{
  "mcpServers": {
    "atom-of-thoughts": {
      "command": "npx",
      "args": ["-y", "@dioptx/mcp-atom-of-thoughts"]
    }
  }
}

2. Restart your client.

3. Ask the model to reason something through:

"Use AoT-fast to think through whether we should use JWT or session-based auth for the API."

The model breaks the problem into five kinds of atoms (premise, reasoning, hypothesis, verification, conclusion), each tagged with a confidence score. You get a structured chain you can audit, not a black-box answer.

[!TIP] Works with Claude Code, Cursor, Windsurf, or any MCP-aware client.

Install

npx (recommended; zero install, always latest)

{ "command": "npx", "args": ["-y", "@dioptx/mcp-atom-of-thoughts"] }

npm global

npm install -g @dioptx/mcp-atom-of-thoughts

{ "command": "mcp-atom-of-thoughts" }

Smithery

npx -y @smithery/cli install @dioptx/mcp-atom-of-thoughts --client claude

Docker

docker build -t aot .

{ "command": "docker", "args": ["run", "-i", "--rm", "aot"] }

How it works

graph LR
    P["P · Premise"]:::premise --> R["R · Reasoning"]:::reasoning
    R --> H["H · Hypothesis"]:::hypothesis
    H --> V["V · Verification"]:::verification
    V --> C["C · Conclusion"]:::conclusion

    classDef premise fill:#6b7280,stroke:#9ca3af,color:#fff,font-weight:bold
    classDef reasoning fill:#3b82f6,stroke:#60a5fa,color:#fff,font-weight:bold
    classDef hypothesis fill:#eab308,stroke:#facc15,color:#000,font-weight:bold
    classDef verification fill:#06b6d4,stroke:#22d3ee,color:#fff,font-weight:bold
    classDef conclusion fill:#22c55e,stroke:#4ade80,color:#fff,font-weight:bold

Atoms chain through dependencies. Each carries a confidence score from 0 to 1. Reasoning terminates when a high-confidence conclusion lands or max depth is hit. Each problem runs in its own session, so two threads of thought never bleed into each other.

Tools

Three tools cover the full surface:

Tool	When to reach for it
AoT-fast	Default. Tradeoffs, debugging, decisions, option evaluation. Depth 3.
AoT-full	Plans, architecture, decomposition into sub-problems. Depth 5.
atomcommands	Sessions, export, approval polling, decomposition lifecycle.

Quick example

AoT-fast({atomId:"P1", content:"API returns 500 on POST /users",     atomType:"premise"})
AoT-fast({atomId:"R1", content:"Unhandled exception in route handler", atomType:"reasoning", dependencies:["P1"]})
AoT-fast({atomId:"C1", content:"Add try-catch in POST handler",       atomType:"conclusion", dependencies:["R1"], confidence:0.9})

Only atomId, content, and atomType are required. Everything else has sensible defaults.

Visualization

Pass viz: true on any call to open an interactive D3 graph in the browser:

AoT-fast({atomId:"C1", ..., viz: true})

Approve and reject decisions POST back to the server over HTTP. No filesystem polling.

Live TUI

Watch the model reason in a second terminal pane while it works, and feed approve/reject decisions back into the next tool call. The event feed is on by default; nothing extra to configure.

In a second pane next to your LLM client:

npx -y @dioptx/mcp-atom-of-thoughts tui

1. Watch reasoning unfold

Atoms appear as the model emits them, walking the chain premise → reasoning → hypothesis → verification → conclusion. Confidence bars fill in real time, dependencies show as inline arrows, and a velocity sparkline tracks event rate. Auto-scroll keeps the newest atom selected.

2. Give granular feedback

j / k move the selection. a accepts an atom; * stars it as critical context; r rejects it and prompts for a one-line reason. s submits the verdict. The submit flash tells you exactly what to do next: ask the model to call atomcommands check_approval. The verdict is written as the same approval JSON the existing file-fallback path already polls for, so feedback flows back through a contract the server already understands. Zero new wire protocol.

3. Customize the view

t opens settings: confidence threshold to hide low-confidence atoms, color theme (vibrant, soft, or mono), compact mode, dependency arrows toggle. ? shows the full keymap.

Keys reference

Key	Action
j / k	Move selection
a	Accept the selected atom
r	Reject (prompts for a one-line reason)
u	Clear feedback on the selected atom
*	Star as critical context
s	Submit verdict (writes aot-approval-*.json)
t	Settings (threshold, theme, compact mode, deps)
?	Keys help
space	Pause / resume event stream
q	Quit

[!TIP] Skip setup and see it in action: npx -y @dioptx/mcp-atom-of-thoughts tui --demo

---

<details> <summary><b>Configuration</b></summary>

{
  "args": ["-y", "@dioptx/mcp-atom-of-thoughts", "--mode", "fast", "--viz", "never"]
}

Flag	Default	Effect
--mode full|fast|both	both	Which tools to register
--viz auto|always|never	auto	auto: render on viz:true. always: render every call. never: skip (CI)
--max-depth <n>	5 / 3	Override depth limit
--output-dir <path>	OS temp	Where to write viz HTML
--downloads-dir <path>	~/Downloads	Approval JSON fallback

</details>

<details> <summary><b>Sessions</b></summary>

Each reasoning chain gets its own session. Default ID: "default".

• atomcommands new_session creates and activates a new one.
• atomcommands switch_session / list_sessions / reset_session for management.
• When reasoning terminates, the session auto-archives. The next zero-dependency atom auto-spawns default-2, default-3, and so on.
• Or pass sessionId on any AoT call to target one explicitly.

Two problems in one MCP process stay isolated without manual session management.

</details>

<details> <summary><b>Browser visualization (alternative to the TUI)</b></summary>

Prefer a browser tab to a terminal pane? Pass viz: true on any AoT call. The server writes a self-contained HTML file (D3 inlined, works offline) and opens it:

• Force-directed graph colored by atom type with confidence rings
• Sidebar to approve or reject phases or individual atoms
• Approve / reject POSTs to a local 127.0.0.1 listener on an ephemeral port; falls back to a ~/Downloads file scan if the listener can't bind

The TUI and the browser viz both feed atomcommands check_approval. Pick whichever fits your workflow.

</details>

<details> <summary><b>Install methods</b></summary>

npx (zero install):

{ "command": "npx", "args": ["-y", "@dioptx/mcp-atom-of-thoughts"] }

npm global:

npm install -g @dioptx/mcp-atom-of-thoughts

Smithery:

npx -y @smithery/cli install @dioptx/mcp-atom-of-thoughts --client claude

Docker:

docker build -t aot . && docker run -i --rm aot

</details>

<details> <summary><b>Development</b></summary>

git clone https://github.com/dioptx/mcp-atom-of-thoughts.git
cd mcp-atom-of-thoughts
npm install
npm test        # 183 tests (unit + e2e)
npm run build

</details>

<details> <summary><b>Migrating from v2</b></summary>

See MIGRATION_v2_to_v3.md for the full lookup table. The short version:

• AoT-light is now AoT-fast
• AoT is now AoT-full
• generate_visualization is now viz: true on any AoT call
• export_graph and check_approval are now atomcommands subcommands
• --no-viz and --no-approval are replaced by --viz auto|always|never

</details>

---

MIT. Based on Atom of Thoughts.