ClauDHD
Focus and drift control for Claude Code.
ClauDHD is a small Claude Code plugin that remembers where you are in a project, so ending a session mid-thought doesn't lose you the thread. It's easy to wander off a task: you chase a new idea, switch branches, or close the tab and come back days later unsure where you were. Rather than trying to stop that, it writes your place down as you go, into a few plain Markdown files at the root of your repo, so picking the work back up means reading a file instead of reconstructing your own train of thought.
It has zero dependencies and runs on local files: no ClauDHD account, no ClauDHD server, and no network calls beyond normal Claude Code usage. It uses the Node.js runtime that Claude Code already bundles, plus ordinary git.
What it gives you
- A NOW cursor (
NOW.md). One active thread at a time, the next physical action, and an ordered queue behind it.
- Session breadcrumbs. A
Stop hook writes a checkpoint after every turn, and a SessionStart hook opens your next session with a summary: where you left off, what shipped, and what is drifting. You never have to remember to checkpoint.
- An idea inbox (
IDEAS.md). When an idea comes up mid-task, /claudhd:idea <text> records it in one line so you can keep working instead of opening a new chat. Review it later with /claudhd:triage.
- A quick-fixes lane (
/claudhd:quick). Small, self-contained chores that aren't worth their own thread go into a capped batch in NOW.md, cleared in one focused pass — so they skip the queue without becoming a second backlog or fragmenting your focus.
- A shipped log (
SHIPPED.md). /claudhd:shipped adds your finished commits to a running list.
Quick Start
1. Install
/plugin marketplace add kidsmeal/ClauDHD
/plugin install claudhd@claudhd
If you install during an existing Claude Code session, run /reload-plugins to activate it. No restart is needed.
2. Verify installation
Confirm the plugin loaded and check which version you're on:
/claudhd:version
You should see a line like ClauDHD v0.6.0. If the command isn't recognized, the plugin didn't load — run /reload-plugins (or restart Claude Code) and try again.
3. Initialize a project
ClauDHD does nothing in a project until you opt in. In the project you want to manage:
/claudhd:init
That scaffolds NOW.md, IDEAS.md, and SHIPPED.md (without overwriting any you already have) and adds .now/ to your .gitignore. Then Claude reads the repo, proposes your one active thread and its next tiny step, and you confirm or correct it. That is it.
Scope the cursor to the work you're doing, not the repo. If a feature spans several repos, run /claudhd:init in each and let each repo's NOW.md hold that repo's slice of it — there is no cross-repo cursor, by design (see Non-goals).
In every other repo, ClauDHD stays completely silent.
Usage Flow
Once a project is initialized, most of ClauDHD runs through the automatic hooks; the commands cover the points where you act explicitly. A typical session:
- Resume a session. Starting a session triggers the
SessionStart hook, which injects a brief: your active thread, the next action, what shipped on this branch, and any drift flags. No command required.
- Check the current cursor.
NOW.md holds one cursor — the active thread, the next physical step, and the queue behind it. Run /claudhd:now to reprint it mid-session.
- Capture an idea.
/claudhd:idea <text> appends an unrelated idea to IDEAS.md as a single line, without changing the active thread.
- Refocus after drift.
/claudhd:regroup identifies the current drift, sets aside any side tasks, and returns you to the active thread.
- Reconcile before stopping.
/claudhd:wrap updates NOW.md: marks completed steps, records the next action, and closes out loose ends so the next session starts clean.
- Record shipped work. After a commit,
/claudhd:shipped adds the finished commits to SHIPPED.md.
- Process the idea inbox. Periodically,
/claudhd:triage reviews IDEAS.md (promote, park, or delete each entry, or route a small chore to the quick-fixes batch — promotion runs a readiness gate, so nothing under-baked reaches the cursor), and /claudhd:harvest backfills ideas mentioned in past sessions that were never recorded.
Small, self-contained chores don't need the full loop. /claudhd:quick <text> drops one into a capped quick-fixes batch in NOW.md in a single local, zero-token write; run /claudhd:quick with no argument to clear the batch in one focused pass (anything that turns out to need real thinking gets kicked back to IDEAS.md). Triage routes small ideas here too, so they skip the queue without fragmenting your focus — and the single-cursor rule still holds, because the batch is a batch, not a second active thread.
