think-do

A fluid work method for building software with AI agents. Two skills — /think to think, /do to act — over a thought stream: a central per-project memory that survives every session, stays silent while you work, and never touches your repositories. For Cursor, Claude Code, Codex, and GitHub Copilot.

The idea

Working with AI agents usually fails in two ways: the agent forgets everything when the context window ends, and the fix for that — heavyweight plans, ceremonies, bookkeeping — kills the flow that made the agent useful in the first place.

think-do keeps both: memory without ceremony.

Think with the agent — it remembers only what matters. Do the smallest verified move, then the next, while everything stays green.

The memory is a stream of thoughts. One thought = one markdown file: a status, an optional next action, free prose, and the verification evidence it earned. That's the entire structure ongoing work has:

~/.think-do/projects/my-app/thoughts/
  ● moving  payment-retry — next: wire the backoff into the webhook
  ◐ shaped  catalog-cache — next: spike redis vs in-process
  ○ raw     that-weird-cors-bug
  ✓ done    onboarding-flow

A dev's real day fits it exactly: you have an idea at 9, shape it at 11, abandon it at lunch, resume it Thursday, ask something on the fly in between. The stream orders itself by ripeness; resuming is reading one file.

What makes the memory work

The stream orders itself by ripeness, then importance, then recency — the retrieval signals the agent-memory literature converges on — so the thought most worth resuming floats to the top without you sorting anything. And it stays cheap forever: done thoughts don't pile up, they page out to a cold archive under pressure (MemGPT-style hot/cold tiering), so the live stream — and the cost of reading it each turn — stays bounded whether a project lives a week or five years.

One rule keeps that stream worth reading: iron selection — a thought is written only when it's a hard-won discovery (would a different session act differently knowing this?) or evident planning. Anything a grep or the git history answers is never written; most turns write nothing, and that's correct. Stream I/O is silent, and think-do stream shows everything on demand.

Big work doesn't get a different method: a thought grows a checklist inside its body, each move verified with your project's real commands (✓ npm test — 56/56 lands at the tail) — structure as a detail of the thought, not a ceremony around it.

Two skills, one gate

• /think — think. Answers, brainstorms, decisions; what matters settles into the stream silently. Never changes code.
• /do — act. Picks the ripest thought (or the one you name, or the small fix you asked for), executes the smallest verified move, and keeps going while verification stays green. Never touches git.

Both open with one command — think-do context — which answers everything at once: where am I, is the memory set up, is it fresh against HEAD, and what does the stream hold. No repo? You're in the ideas stream: think with zero setup, and when an idea becomes real work, stream adopt moves it into the project.

The memory

All memory is central: everything lives under ~/.think-do/, one store per project plus the global ideas stream. Nothing is ever written inside your repositories — no dotfolders, no .gitignore edits, no commits.

| | Where (inside ~/.think-do/) | Rule | |---|-------|------| | Who owns what | registry.json (repo path + remote → slug) | the identity authority; survives repo moves | | What the project is | projects/<slug>/base/ (index, map, standards, verify) | edited in place when facts change | | What we're thinking and doing | projects/<slug>/thoughts/*.md | iron selection in, ruthless compaction out | | Loose ideas | ideas/thoughts/*.md | same shape, no project needed |

Freshness follows a SHA-anchored delta-scan contract: the memory records the commit it was derived from; when HEAD moves, only the changed files are examined and only the stale prose is refreshed — everything else carries forward at zero cost.

Backup? The whole memory is one folder. Copy ~/.think-do/, you have everything.

Start in two minutes

npm i -g think-do        # once per machine — puts the think-do (and td) CLI on your PATH
think-do install         # detects Cursor, Claude Code, Codex, Copilot (VS Code); installs
                         # /think and /do, and prunes what older versions left behind

No global install? npx think-do install works everywhere too — the skills always call the CLI through npx, so they run either way.

Then, anywhere:

you>  /think what if we cached the whole catalog in redis?
td>   <no repo here → ideas stream: three directions, trade-offs, zero setup>

you>  /think add retry to the payment webhook        (inside your project)
td>   <first time: quick setup — scans the repo, confirms test commands — then thinks with you>

you>  /do
td>   <picks the ripest thought, executes, verifies with your real commands, keeps going while green>

Uninstall cleanly anytime: think-do uninstall (your memory in ~/.think-do/ survives).

Learn more

• User guide — the full walkthrough, troubleshooting included.
• Architecture — how the stream, registry, and delta scan fit together.
• think-do help — the whole CLI.

Design sources

The silent write-back and cold-resume rituals follow Anthropic's effective harnesses for long-running agents and effective context engineering (structured note-taking, memory outside the context window); skill authoring follows Anthropic's Agent Skills engineering (progressive disclosure, lean SKILL.md) and Matt Pocock's skill-writing principles (leading-word imperatives); the memory architecture follows the field's convergent design — the episodic/semantic/procedural split of Cognitive Architectures for Language Agents (CoALA) (thoughts vs base/ vs skills), the tiered hot/cold paging of MemGPT, and the ripeness → importance → recency retrieval signals of Generative Agents; the persistence layer follows a SHA-anchored delta-scanning strategy — persist a bounded map, not the code; re-derive only what changed; carry expensive prose forward.

Contributing

See CONTRIBUTING.md. npm test must be green; skill style is enforced by the suite.

MIT © Davide Baldassarre