think-out-loud

Thinking should be a conversation you can join.

A skill for active thinking out loud: visible assumptions, evidence, uncertainty, alternatives, decisions, and revisions while the work happens. Read it, question it, interrupt it, and steer it.

Inspired by the Sequential Thinking MCP, and by the frustration of losing useful visibility when a coding assistant hides its thinking display.

What it feels like

Assistant: The failures so far happen after token refresh. An expired token is a plausible cause; I still need to compare successful requests.

You: It also happens immediately after a fresh login.

Assistant: That changes the hypothesis. Token refresh alone cannot explain it. I’ll compare fresh sessions too and check whether the requests reach the server.

Assistant: Fresh-session failures stop before the network request; the captured trace points to client validation. I’ll check that validation path and test the reported inputs.

The useful part is the opportunity to change the investigation before the answer is finished. See the worked example.

Install

npx skills add https://github.com/claude-mem/think-out-loud --skill think-out-loud

Or install manually for Claude Code:

git clone https://github.com/claude-mem/think-out-loud.git
mkdir -p ~/.claude/skills
cp -R think-out-loud/think-out-loud ~/.claude/skills/

For Codex, copy the same skill folder into ~/.codex/skills/.

Ask: “Use think-out-loud while investigating this. Show me the assumptions and decision points so I can steer.” In Claude Code you can invoke /think-out-loud; in Codex, use $think-out-loud.

The skill instructions work without an MCP server or a runtime. The optional notebook script requires Bun.

What the skill does

• Publishes short working notes directly in the conversation.
• Connects observations to the decisions they affect.
• Makes uncertain assumptions and useful alternatives reviewable.
• Incorporates user corrections while the task is in progress.
• Records revisions and branches when a persistent notebook is useful.
• Finishes with the result, validation, and material open questions.

These notes are written for collaboration. They do not expose private internal reasoning or guarantee that a transcript faithfully represents the model's internal process. Showing a note does not establish its truth; the work still needs sources, observations, or tests.

Why this name, now?

This project began as sequential-thinking-skill. Its first focus was reproducing the MCP's numbered entries, revisions, branches, and adjustable estimates with a local script.

The rebrand puts the human interaction first. Native reasoning can do more inside the model, while product interfaces can show less of the process. A useful collaboration skill makes consequential choices visible in the conversation, where a person can respond.

The history supports a more precise story than “Sequential Thinking was forgotten.” The official MCP remains maintained. In December 2025, Anthropic updated its separate think-tool article to recommend native extended thinking for most cases. That helps explain why a separate scratchpad may feel less necessary; it does not establish that this particular MCP was built into models or that its adoption declined. Anthropic's update, official MCP repository.

Read HISTORY.md for the sourced timeline, changes to thinking displays, and the limits of the “forgotten” explanation.

Live view and replies

Run the live view from this repository with Bun and a signed-in Claude Code CLI:

bun live/server.ts

Open http://127.0.0.1:4317. Each public working note arrives live and is rewritten using the pinned I Have ADHD prompt: the key action or finding first, small numbered steps, visible progress, and meaningful uncertainty. The original note remains available. Rewriting uses your existing Claude Code login; it makes model calls.

Send working notes from the skill:

mkdir -p work
bun think-out-loud/scripts/think.ts --state work/task.json --live http://127.0.0.1:4317 --session main --thought "The failing requests follow token refresh. I still need to compare successful requests before treating refresh as the cause." --thoughtNumber 1 --totalThoughts 3 --nextThoughtNeeded true

Click Add your thought on a note to reply to that specific note. The reply enters the producing agent's inbox unchanged. The agent reads pending replies before publishing its next note, or explicitly checks between actions:

bun think-out-loud/scripts/think.ts --live http://127.0.0.1:4317 --session main --feedback

A reply is shown as queued until the agent reads it. Reading means delivered, not that the agent has completed the requested change. Delivery happens at checkpoints; this app does not inject messages into an arbitrary running chat. The skill tells the agent to check and incorporate feedback during the task.

Use a different --session for each investigation, and open http://127.0.0.1:4317/?session=your-session. You can pause the feed while reading or writing; incoming notes continue to collect. Notes and replies persist locally in .local/live-state.json, which is ignored by Git. The server listens on this computer only.

The formatter preserves source facts and uncertainty; it does not create private reasoning traces. If rewriting fails, the original stays available and the view reports the failure. The full upstream MIT notice and source revision are retained in live/vendor/i-have-adhd.

Optional notebook

The inherited think.ts script keeps a JSON history of public working notes. Use a different state file for each task, with an existing parent directory:

mkdir -p work
bun think-out-loud/scripts/think.ts --state work/investigation.json --reset
bun think-out-loud/scripts/think.ts --state work/investigation.json --thought "Fresh sessions fail before the request reaches the server; checking client validation next." --thoughtNumber 1 --totalThoughts 3 --nextThoughtNeeded true
bun think-out-loud/scripts/think.ts --state work/investigation.json --status

The notebook retains the original flags for revisions, branches, and extending the estimate. See SKILL.md for the commands. Tool output can be collapsed by the host, so the skill also puts useful notes directly in the chat.

Existing users

Install think-out-loud using the new URL. If you manually installed the old sequential-thinking folder, remove that copy once you have moved any notebook you want to keep; leaving both installed can create duplicate guidance. Existing script flags and the default .think_state.json behavior remain supported.

License

MIT. The original Git history and license are retained.