sequential-thinking-skill

Sequential thinking as a CLI + Agent Skill, with a compaction-proof thought chain — a file-backed replacement for the sequential-thinking MCP server.

The original MCP server has no external capability: it is a long tool description (a prompt), a JSON schema, and an in-memory thought history that returns an ack per call. All three map cleanly onto a skill:

MCP server	this project
tool description (~1k tokens, resident every turn)	SKILL.md body, loaded only when triggered
JSON schema constraints	argparse + semantic validation (revise/branch targets must exist)
thought history in server memory (dies with the process, not queryable)	JSON file on disk — replayable with show, survives context compaction

That last row is the point. In long agentic sessions the context gets compacted; an MCP server's memory-only history is unreachable and the transcript copy may be summarized away. Here the chain is an external, compression-immune record: after compaction (or days later) think.py show replays the full reasoning chain.

Install

npx skills add dengshu2/sequential-thinking-skill

Then remove the MCP server so the two don't compete for the same trigger (claude mcp remove sequential-thinking, or wherever you registered it).

Usage (what the agent does)

think.py new "why did metric X drop in March" --total 5
think.py add "candidate causes are A/B/C; B matches the timeline because ..."
think.py add "step 2's assumption fails, because ..." --revises 2
think.py add "alternative: viewed from the demand side ..." --branch-from 3 --branch-id demand
think.py add "conclusion: ..., verified against steps 1/3/5" --done
think.py show          # replay the chain (also after /compact)

State lives in ${XDG_STATE_HOME:-~/.local/state}/think/<cwd-hash>/thoughts.json (one chain per working directory — nothing is written into your project). Override with --file or $THINK_FILE; the skill instructs agents to prefer a session-scoped file (their session scratchpad) when the harness provides one.

Known limitations

• Concurrent sessions sharing a working directory share the fallback per-cwd state file: their thoughts would interleave into one garbled chain (worst case — no corruption, new resets). The chain's natural unit is a session, and cwd is only an approximation of that, which is why the skill prefers a session-scoped --file when available. Worktree-isolated sessions have distinct cwds and don't collide.
• Stale chains: a later session in the same directory could add onto a leftover chain. The add ack carries a warning field once a chain has been idle for 6+ hours; the skill treats that as "start a fresh chain".
• Plain-text persistence: thoughts are stored unencrypted on disk and outlive the session — keep secrets out of thought text.

CLI vs MCP: measured, not vibes

python3 benchmark/bench_mcp_vs_cli.py compares the two mechanically (details and caveats in benchmark/README.md). Initial run (M-series Mac, warm npx cache):

mechanism	calls	failures	cold start	median/call	p95/call
CLI (think.py add subprocess)	100	0	22 ms	19.5 ms	20 ms
MCP stdio (npx server + JSON-RPC)	50	0	1320 ms	0.1 ms	0.2 ms

Honest reading: a healthy local stdio server does not fail at the transport layer — both sides scored zero failures, and both latencies are noise next to LLM token generation. The real differences are structural:

• MCP pays ~1.3 s process spawn per session and keeps a Node process resident; the CLI pays ~20 ms per call and keeps nothing resident.
• The MCP tool schema + description sit in context every turn; the skill loads on demand.
• Real-world "MCP call failed" incidents are mostly client↔server session drops, schema rejections, or npx cold-download flakiness at session start — failure classes a fresh-process, state-on-disk CLI cannot have. The qualitative A/B protocol in benchmark/README.md is how to measure those in real sessions.

Should you use this at all?

Also honest: Claude's native interleaved thinking, plan mode, and todo lists have eaten most of the original tool's value. If your only motive is "the MCP occupies context", just uninstall it. This project earns its place only if you want the persistent, replayable chain — for compaction recovery, or for post-hoc review of how an agent reached a conclusion.

Development

python3 tests/test_think.py            # unit tests (stdlib only, no deps)
python3 benchmark/bench_mcp_vs_cli.py  # mechanical benchmark

中文说明

把 sequential-thinking MCP 改造成 CLI + Skill:工具 description 变成按需加载 的 SKILL.md,JSON schema 变成 argparse 语义校验,server 内存里的思考历史变成 本地 JSON 文件。核心增量是思考链落盘——上下文被 compaction 压掉之后, think.py show 仍能回放完整推理链,也可用于事后复盘 agent 的推理过程。

安装:npx skills add dengshu2/sequential-thinking-skill,装完建议卸载原 MCP 避免同名双入口。基准测试与手动 A/B 对比方案见 benchmark/。

License

MIT. SKILL.md adapts the tool description of @modelcontextprotocol/server-sequential-thinking (MIT, Anthropic PBC) — see LICENSE.