How to use Hunch Board with Claude Code

Claude Code is very good at reading files and bad at reading a photo of your whiteboard. Hunch Board closes that gap: the board you draw is a text file in your repository, so Claude reads and edits the same plan you see. This guide goes from an empty folder to a feature built from a board.

You need Node 20 or newer and Claude Code. You don't need a Hunch account: the board opens in your browser without one.

Step 1: add Hunch to your project

Run this in the root of your project:

npx hunch-board init

It creates a few small files. They're all plain text, so read them and commit them like anything else.

Step 2: draft the board with Claude

You can draw first or describe first. If the idea is still vague, let Claude ask. Anthropic's best practices for Claude Code suggest exactly this: ask Claude to interview you until it could write the spec. Point the result at the board:

I want to build appointment reminders for small clinics, but I haven't thought it through. Interview me until you could draw the plan, then write it to board.hunch. Mark anything I didn't decide with a [question] note. Don't write code yet.

The skill tells Claude to mark what it's unsure of instead of inventing it, so you should get something like this. This is a real board, drawn from the text below it:

title Appointment reminders

clinic: Web app "Clinic panel" "Next.js"
api: Monolith "Reminders" "Next.js" "Pages and API in one deploy"
db: PostgreSQL "Appointments"
jobs: Scheduled job "Send reminders" "" "Every 15 minutes"
wa: WhatsApp "Patient messages"

clinic => api "books"
api => db "SQL"
jobs => db "due soon?"
jobs => wa "reminder"

note "One deployable until something needs to scale on its own." [decision status=accepted]
note "Can a patient reschedule by replying?" [question]

The syntax is short: key: Type "Title" "Technology" "Text" is a box, and a => b "label" is an arrow. Any technology works as a type, so wa: WhatsApp gets its logo. The whole language is on one page: the grammar.

Step 3: open it and correct it yourself

This is where you stop being a reviewer of prose and become the architect. Open the board, choose File, then Open file, and pick your board.hunch. Drag things around, delete what's wrong, and add what's missing. Then choose Save to file.

Your layout is saved as @layout lines in the same file. The skill tells Claude to leave those alone, so your arrangement survives its edits. Commit the file, and every later change to the plan shows up in a normal git diff.

Step 4: build from the board

Start a fresh session for the build, so it begins with a clean context and a written plan. The same Anthropic guide recommends this after writing a spec. Then be specific about the slice:

Read board.hunch. Build the "Send reminders" job as drawn, and only that. Open any file the board names. If you change the design or find something the board doesn't answer, update board.hunch and tell me what changed.

The last sentence matters most. A plan that isn't updated stops being trusted, and the skill already tells Claude to edit the lines and keep the keys when the plan changes.

Step 5: give Claude a check to run

check answers one question: does every line of the board read, and is every file it names really in the folder?

npx hunch-board check --json

{
  "ok": true,
  "issues": []
}

Because the answer is pass or fail, Claude can correct its own mistakes in the file without you. It checks the board, not your code: keep running your tests for that.

Step 6: connect the MCP server (optional)

The skill and the CLI are enough for most projects. If you'd rather give Claude tools than commands, add the MCP server, which runs on your machine:

claude mcp add hunch-board -- npx hunch-board mcp

It offers read_board, write_board, check_board, render_board, search_community and clone_board.

Start from a design someone already drew

You don't have to start from an empty file. Search the community from the terminal and copy a board into a new folder:

npx hunch-board search telegram
npx hunch-board clone telegram-support-bot

Next, read how to architect a project with AI before you write code, which takes the board above through its next round of decisions.