workflow-map

See what your AI is doing — and what's next. A live plan for Claude Code, right above your prompt.

▶ Watch the full intro (MP4, 30 s)

_{Desktop shots are the plugin's own drawing code; the terminal shots are real Claude Code CLI captures, with the plan updates written to the plan file by a script (the model was not called). The install confirmation at the end is a mock of the CLI's success line, not a captured install.}

What it does

• One row above the prompt — the step that is running, what comes next, and a segmented progress bar (3/9).
• Expand for the card graph — GitHub-Actions-style cards: finished work folded into "✓ N done", parallel steps stacked in one card, later steps folded into a dashed "+N later" card at the end of the line. Point at "✓ N done" or "+N later" to peek at the steps inside.
• Your interjections are kept — when you ask for something mid-plan, Claude records it as a violet ◇ step (with the time and your words) before acting on it, so it doesn't get lost.
• Diagram view — the Diagram button in the full view (or /workflow diagram) draws the plan as a flowchart, one stage per row from top to bottom: steps that share a lane become one box with a count ("Review · 5 steps"), groups of the same stage sit side by side, pairs like "Build n → Test n" share a row, decisions are dashed and warnings amber. Between two rows there is just one thin line, with short drops into the boxes below; a wait on an earlier stage is written in the box ("← waits for Review") instead of drawn as a long line, and edge labels appear as a "via …" caption under the group's title. Made for many agents working in parallel. Try /workflow-demo team.
• Review mid-plan requests — each request you add mid-plan records what it changed ("+1 step · 3 steps now wait for this · 5 downstream"); open its Details to see the affected steps marked, Show changes to see on the current plan (stage cards or diagram) what it actually moved — added steps (+, green), steps that now wait for it (~, violet, "now waits for ◇…"), steps pushed to a later stage ("Stage 3 → 4"), steps now waiting downstream (●) and removed ones (struck through) — or Plan before this request to see the plan as it was; switch between them with Before | After. Both views are read-only. Timeline lists everything in order (plan started, steps added, your requests in your words, status changes and who made them, undo), and /workflow export includes it. Violet ◇ is kept for requests from the current turn: from the next turn they look like any other step (open ones keep a small dim ◇ before the title).
• See whether "also do this" made it in — when Claude records your mid-plan request, a short notice says so ("Recorded: …") and the new ◇ step pulses a few times. If a message that looks like a request reaches the end of the turn without Claude touching the plan, the band's title row says "Not on the plan: …" with Add to plan, which puts a draft ("Add this to the plan: …") in the prompt box for you to send — nothing is ever sent for you. ✕ hides it; each message is flagged at most once.
• Full view on demand — /workflow opens stage-by-stage cards, showing what each waiting step is waiting for. Press Details on a step to see more: your original words, what it waits for and unblocks, owner, start/finish times and its status history.
• Full names on hover — owner tags are kept short on screen (general-purpose shows as "agent", long agent ids are shortened, other long names are cut to 10 cells; the plan keeps the full name). When a card in the band cuts a title or owner with "…", point at the card graph to see the full title and owner of each one.
• Made for several agents — each step can have an owner (Builder, Grok, "me"…), shown as a small tag with the time it has taken. Start a sub-agent with [wm:<id>] in its description and its step turns in progress on its own, then done (or blocked if the agent failed). A step in progress with no update for 30 minutes turns amber ("no update").
• One plan per session — two Claude Code sessions in the same project each keep their own plan. To work on the same plan, open Plans in the full view and press Join (or run /workflow join <title>); /workflow leave goes back to your own.
• Plans come and go — when you start an unrelated task, the old plan moves to History (in the full view) instead of mixing with the new one; a plan another session is still using is never archived.
• Notifications — a short notification when a sub-agent finishes a step, when a step becomes blocked, or when a step in progress goes stale; several at once are merged into one.
• Time left, as an honest range — once three finished steps have timings, the band and the full view show a range (≈ 40–70m) instead of a single number: the middle half (p25–p75) of the finished steps' times, summed along the remaining stages, where parallel steps count once (the longest per stage) and a running step adds only its remaining time. The more uneven the steps, the wider the range; with fewer than six timed steps it says rough instead of ≈. Point at the progress bar for a one-line explanation.
• Export, undo, projects — /workflow export (or Export in the full view) writes the plan as Markdown to .claude/workflow-map.export.md and copies it, ready for a hand-off note or a PR description. /workflow undo (or Undo) restores the plan as it was before the last change, the AI's changes included (last 10 kept). Projects lists your other projects that have a plan and opens any of them read-only.
• Next-prompt suggestions — after each answer, the band's last row offers up to three likely next prompts (ready plan steps first). Press 1, 2 or 3 to put one in the prompt box as a draft you can edit, 0 to hide them. Nothing is ever sent for you.

Collapsed	Expanded

Full view (Details open)	Help

_{The collapsed and expanded rows are rendered by the plugin's own drawing code (dark theme). In the full view, the Help card and the band's hover lists the app lays out the elements itself; those pictures are rendered from the plugin's element tree with an approximation of the app's layout. The intro video uses the same renders.}

Install

Requires Claude Code 2.1.287 or later.

Desktop app

Settings → Plugins → Add from a repository → enter mimateinn/workflow-map.

Inside a Claude Code session

/plugin install workflow-map --marketplace mimateinn/workflow-map

From your shell

claude plugin install workflow-map --marketplace mimateinn/workflow-map

Or in two steps (add the marketplace, then install from it):

claude plugin marketplace add mimateinn/workflow-map
claude plugin install workflow-map@workflow-map

Add --scope project to install for the current project only (default: user).

Install with one prompt

Paste this into Claude Code and it will install the plugin for you:

Install the Claude Code plugin "workflow-map" from the GitHub marketplace mimateinn/workflow-map.
Run: claude plugin install workflow-map --marketplace mimateinn/workflow-map
If that command is not available, run `claude --version` and tell me — it needs 2.1.287 or later.
When it succeeds, confirm with `claude plugin list` and tell me to restart Claude Code if the map does not appear.

To try it without a real plan, run /workflow-demo (shows a sample; run it again to hide it).

How it works

• No CLAUDE.md edits needed. Once installed, the plugin itself tells Claude to keep the plan: it gives Claude a workflow_map tool (new_plan / set_plan / upsert / status / insert / remove / show) and adds a short rule to every session's system prompt (120 words at most): for any task of 3 or more steps start a new_plan, keep statuses current (doing / done / blocked), record your mid-plan requests with insert before acting on them, tag delegated agents with [wm:<step id>], group parallel workers with lane (and label key arrows with edgeLabel), and write titles in your language. Tool answers are kept short — a one-line summary plus the steps that changed — so the map costs few tokens.
• Safety net: if Claude forgets and uses its own to-do list instead (TodoWrite, or TaskCreate / TaskUpdate), a session with no plan gets one built from that list (3 or more open items; steps in order, owner auto; a one-time notice says so), and later to-do updates keep the step statuses in sync. A session that already has a plan never gets a second one; only steps whose titles match a to-do item follow it. After a turn with real work (3 or more edits or commands) and still no plan, the band shows a one-line hint, once per session.
• Turn all of this off with autoPlan: false: Claude then gets only a one-line note and uses the plan when you ask for one.
• The map is stored in your project at .claude/workflow-map.json, so later sessions and other agents can read it. Updates that would create a cycle or point to a missing step are rejected and the map is left unchanged. A damaged file is backed up before the map restarts.
• Safe with other writers: before writing, the plugin reads the file again and merges step by step (the newer change wins; deleted steps stay deleted), so a Codex or Grok session editing the same plan doesn't lose its changes. The format, merge rules and history folder are documented in docs/FORMAT.md for tools that want to read or write the plan.
• History: finished or replaced plans are kept in .claude/workflow-map.history/, one file per plan; the full view lists them under History. Files from older versions are backed up once and upgraded in place, never trimmed.
• The amber dot after the count means you sent a request that isn't on the map yet. Short replies like "ok", "go on" or "好" and image-only messages don't count.
• Focus mode: with more than six steps, only what's running, what's ready and the next level are drawn; done and far-future steps fold into one card each. Steps you inserted this turn are always shown.
• Language follows you: the interface uses the script of your most recent prompt: Traditional Chinese, Japanese or Korean, otherwise English (Simplified Chinese gets the English interface). Spanish, French and German are available through the language option. Step titles are shown as Claude wrote them.
• Suggestions come from one extra short model call per answer (a fork of the session, so it shares the prompt cache); the plan's ready steps fill the slots first, and with three ready steps no call is made.
• Help: press ? at the top right of the full view, or run /workflow help, for a short guide with the icon legend.
• /workflow export and /workflow undo do the same as the Export and Undo buttons; /workflow join <id or title> and /workflow leave switch this session's plan.
• Upgrading from 0.3.0: the old shared file .claude/workflow-map.json is left exactly as it is and becomes the plan called default; a session sees it only after joining it.
• /workflow — open the full map (registered as /workflow-map if another plugin already owns /workflow); /workflow diagram opens it as a flowchart. /workflow-demo — toggle a sample map, /workflow-demo team a sample of many parallel agents in the diagram view (on screen only, nothing is written).
• In the terminal, the diagram view is an indented outline by group (Review · 5 steps, ✓ Build 1 → ○ Test 1, ↓ between layers).
• In the terminal (Claude Code CLI) the same band and full view are drawn with text characters — see Terminal (CLI) below.
• The map hides when there is no plan, and hides itself again shortly after everything is done.

Terminal (CLI)

The plugin is a first-class terminal app too. Everything is drawn with text characters in your terminal theme's own colours, so it fits light and dark themes:

• Band: a coloured status glyph (✓ done, ◉ in progress, ○ not started, ! blocked, ◇ added by you), the running step, "Next: …", a progress bar of ━ segments coloured per step, the count and the time left.
• Expand draws the card graph as rounded boxes joined by ───: finished work folds into "✓ N done", parallel steps share a card with owner · time, and whatever doesn't fit the width folds into a dashed +N later card at the end of the line. A card is never cut in half and no line is left hanging.
• Keys: press ctrl+x tab to put the focus on the band, then e expands or collapses and f opens the full view. Suggestions are picked with 1 / 2 / 3, and 0 hides them.
• Full view (/workflow) docks on the right when the terminal is wide enough. It has the same sections, stage cards with ─ dividers, Details, Help (with the language menu), Plans and Projects.

_{Captured from the real Claude Code CLI 2.1.293 running the demo plan (/workflow-demo) in a 150 × 42 terminal, then drawn to an image cell by cell.}

Options

Option	Values	Default
autoPlan	true, false	true (Claude starts and keeps a plan for any task of 3+ steps; its to-do list becomes a plan when it forgets)
language	auto, en, zh-Hant, ja, ko, es, fr, de	auto (script of your latest prompt; English when unsure)
suggestions	true, false	true (next-prompt suggestions as the band's last row)
notify	true, false	true (notifications for finished, blocked and stale steps)
staleMinutes	0–1440	30 (a step in progress with no update for this long turns amber; 0 turns it off)

Set it in the plugin's settings, or from the shell:

claude plugin configure workflow-map                                   # show options
echo '{"language":"en"}' | claude plugin configure workflow-map --values-stdin

Privacy

The map lives in local files in your project (.claude/workflow-map.json and the .claude/workflow-map.history/ folder). The plugin makes no network requests of its own; the only model use is the suggestions' one short fork per answer, made through Claude Code like any other turn (turn it off with suggestions: false).

Feedback

Ideas, questions and bug reports are very welcome:

• Feature ideas: open a feature request or start a thread in Discussions.
• Something broken or ugly: file a bug; a screenshot helps.

Development

claude plugin validate .
claude plugin test .

License

MIT — see LICENSE.

The next-prompt suggestions are derived from next-steps by Thariq Shihipar / Anthropic, licensed under Apache-2.0 — see NOTICE and LICENSE-APACHE.

---

繁體中文

workflow-map 在 Claude Code 輸入框上方以一行顯示目前工作：正在做甚麼、下一步、分段進度條。按 ˅ 展開成卡片圖（已完成收成「✓ N 已完成」、並行步驟疊在同一張卡）；輸入 /workflow 開啟全圖。你中途提出的要求會先以紫色菱形 ◇ 記錄下來，不會被遺忘。每一步可標示負責人（Builder、Grok、me…）和用時；派子代理時在描述寫 [wm:<步驟 id>]，步驟會自動變成進行中、完成（或出錯時受阻）；進行中超過 30 分鐘沒有更新會變琥珀色（「久未更新」，可用 staleMinutes 調整）。全圖每一步按「詳情」可看：你的原話、等待／完成後可開始的步驟、負責人、時間、狀態紀錄。開始另一件工作時，舊計劃移到「歷史紀錄」。資料只存於專案的 .claude/workflow-map.json 和 .claude/workflow-map.history/，不連網；檔案格式見 docs/FORMAT.md（英文），其他工具（Codex、Grok）可按規則安全地一同讀寫。子代理完成、步驟受阻或久未更新時會彈出簡短通知（notify 可關）；有三個以上已完成步驟有時間時顯示剩餘時間的範圍（≈ 40–70 分鐘：取已完成步驟用時的中間一半，沿剩下的階段相加，並行的只算最長一步，進行中的只算餘下時間；步驟用時越參差範圍越闊，少於六步時寫「約」）；/workflow export（或全圖的「匯出」）把計劃寫成 Markdown 並複製；/workflow undo（或「還原」）還原上一次修改；「專案」列出其他有計劃的專案，可唯讀查看。每個工作階段有自己的計劃，同一個專案的兩個工作階段互不干擾；想一起用同一份計劃，在全圖按「計劃」→「加入」（或 /workflow join <標題>），/workflow leave 離開。舊版的共用檔 .claude/workflow-map.json 原封不動，成為名叫 default 的計劃，加入了才會看見。每次回答後，橫條最後一行會建議最多三句下一步（計劃中可開始的步驟優先），按 1／2／3 放入輸入框（不會自動送出），0 收起；可用 suggestions 關閉。介面語言跟隨你最近一次輸入的文字（繁中、日文、韓文，其餘英文；簡體用英文介面），亦可在設定 language 指定英文、繁中、日文、韓文、西班牙文、法文或德文。建議功能改編自 Anthropic 的 next-steps（Apache-2.0，見 NOTICE）。

**流程圖：**全圖工具列的「流程圖」（或 /workflow diagram）把計劃畫成流程圖，由上而下每個階段一行：同一個 lane 的步驟畫成一個框（標題 + 數目，如「獨立覆核 5 個」），同一階段的組並排，「開發 n → 測試 n」同一行，決策用虛線框、提醒用琥珀框。兩行之間只有一條細線，短線落到下一行的框；要等更早階段的，框內寫「← 待 獨立覆核」，不畫長線；線上的標籤變成組名下面的「經：…」。適合多個代理並行。輸入 /workflow-demo team 看示範。

**回看中途要求：**你中途加的每個要求都會記下它改了甚麼（「影響：+1 步 · 3 步改為等它 · 後續 5 步」）；按「詳情」會標出受影響的步驟；「顯示改動」在現在的計劃（階段卡或流程圖）上標出它實際改了甚麼：新增（+，綠框）、改為等它（~，紫框，「改為等 ◇…」）、移到後面階段（「階段 3 → 4」）、因此要等的後續（●）、已移除（刪除線）；「插入前的計劃」顯示加入之前的計劃；兩者用「插入前｜插入後」切換，都是唯讀。「時間線」按時間列出開計劃、加步驟、你的原話、狀態變化（誰）、還原，/workflow export 亦包括時間線。紫色 ◇ 只用於本輪的要求；下一輪起回復一般樣式（未完成的標題前留一個淡色 ◇）。

**要求有沒有記下：**Claude 把你中途的要求記入計劃時，會彈出「已記錄：…」，新的 ◇ 步驟閃幾下。像要求的訊息到這一輪完結仍未記入計劃，橫條標題行尾會顯示「未記錄：…」和「加入計劃」：按下只把一句草稿（「把這個加入計劃：…」）放入輸入框，由你決定送不送；✕ 收起，每則訊息最多提示一次。

**完整名稱：**負責人在畫面上用短名（general-purpose 顯示為「agent」，長的代理 id 縮短，其他長名稱截到 10 格；計劃裏保留完整名稱）。橫條的卡片把標題或負責人截成「…」時，指著卡片圖會列出這幾項的完整標題和負責人。

**終端機（CLI）：**同樣的橫條和全圖，用文字字元畫，顏色跟你的終端機主題：狀態符號（✓ ◉ ○ ! ◇）、━ 分段進度條、圓角卡片以 ─── 相連、放不下的收成虛線「+N 稍後」卡。按 ctrl+x tab 讓橫條取得焦點，e 展開／收起，f 開全圖；全圖在終端機夠闊時停靠在右邊。

**運作方式：**裝好就生效，不用改 CLAUDE.md。外掛自己會在每個工作階段的系統提示加一段簡短規則（120 字以內），叫 Claude：三步以上的工作一開始就 new_plan、做的時候更新狀態（進行中／完成／受阻）、你中途加的要求先用 insert 記下再做、派子代理時在描述寫 [wm:<步驟 id>]、步驟名稱用你的語言。萬一 Claude 忘了開計劃而用了自己的待辦清單（TodoWrite 或 TaskCreate／TaskUpdate），沒有計劃的工作階段會照清單自動建立一個（3 項以上未完成；按次序、負責人 auto，並通知一次「已根據待辦清單建立工作流程」），之後清單更新時同步狀態；已有計劃就不會另開，只同步名稱相同的步驟。做了不少工作（一輪內 3 次以上改檔或執行指令）仍未有計劃，橫條會提示一行「可用 /workflow 開始計劃」，每個工作階段只一次。不想要這些：設定 autoPlan 為 false，Claude 只會收到一句簡短說明，你要求時才用計劃。

安裝（需要 Claude Code 2.1.287 或以上）：

• 桌面版：設定 → Plugins → Add from a repository → mimateinn/workflow-map
• 對話內：/plugin install workflow-map --marketplace mimateinn/workflow-map
• 終端機：claude plugin install workflow-map --marketplace mimateinn/workflow-map

全圖右上角的 ?（或輸入 /workflow help）有簡短說明和圖示解釋。想先看效果：輸入 /workflow-demo（只在畫面顯示，不寫入任何檔案）。

**意見與建議：**歡迎到 Discussions 提出想法，或開 功能建議／錯誤回報。