task-progress

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Step } from '../types'
5import { describe, normalize, summarize } from './format'
6
7const TOOL = 'mcp__task-progress__progress'
8
9// Kept in $.state so a reload of the mod can put the sidebar back as it was.
10const steps = atom({ plugin: 'task-progress', key: 'steps' } as const, [] as Step[])
11
12const RULES = `# Task progress
13The person follows your work in their cmux sidebar. For work of 3 or more steps, call ${TOOL} with the whole step list: once before you start, then again each time a step finishes or the plan changes. Use 2 to 8 steps, each title at most 6 words in the person's language, exactly one step "active" while you work, and every step "done" when you finish. Skip it for quick answers and questions.`
14
15// Set at session.start when Claude Code runs inside a cmux terminal; outside cmux
16// the mod registers nothing and adds nothing to the prompt.
17let cmux: { bin: string; workspace: string } | undefined
18
19/** Writes the list into the cmux workspace: the full list as its description, the summary as its progress. */
20async function push($: EngineInterface, list: readonly Step[]) {
21  if (!cmux) return
22  const { bin, workspace } = cmux
23  const run = (args: string[]) =>
24    $.process.run([bin, ...args, '--workspace', workspace], { timeoutMs: 5_000 }).catch(() => undefined)
25
26  if (list.length === 0) {
27    await Promise.all([run(['clear-progress']), run(['workspace-action', '--action', 'clear-description'])])
28    return
29  }
30  const { value, label } = summarize(list)
31  await Promise.all([
32    run(['set-progress', value.toFixed(3), '--label', label]),
33    run(['workspace-action', '--action', 'set-description', '--description', describe(list)]),
34  ])
35}
36
37async function setSteps($: EngineInterface, list: Step[]) {
38  await update($, steps, () => list)
39  await push($, list)
40}
41
42export const register: Register = on => {
43  on('session.start', async ($, e, next) => {
44    const result = await next(e)
45    const workspace = await $.env.get('CMUX_WORKSPACE_ID')
46    if (!workspace) return result
47    cmux = { bin: (await $.env.get('CMUX_BUNDLED_CLI_PATH')) ?? 'cmux', workspace }
48    await $.tool.register({
49      name: 'progress',
50      description:
51        'Shows your step list for the current task in the person\'s cmux sidebar. Send the whole list every time; an empty list clears it.',
52      inputSchema: {
53        type: 'object',
54        required: ['steps'],
55        properties: {
56          steps: {
57            type: 'array',
58            items: {
59              type: 'object',
60              required: ['title', 'status'],
61              properties: {
62                title: { type: 'string', description: 'At most 6 words, in the person\'s language' },
63                status: { enum: ['done', 'active', 'todo'] },
64              },
65            },
66          },
67        },
68      },
69    })
70    // After a reload, put back what the sidebar showed.
71    const current = await read($, steps)
72    if (current.length > 0) await push($, current)
73    return result
74  })
75
76  on('prompt.compose', async ($, e, next) => {
77    const result = await next(e)
78    if (!cmux) return result
79    return { sections: [...result.sections, { id: 'task-progress:rules', text: RULES, scope: 'session' as const }] }
80  })
81
82  on('tool.call', { tool: TOOL }, async ($, e) => {
83    // A subagent's own plan would overwrite the main conversation's.
84    if (e.agentId) return { result: '只有主對話的進度會顯示在側欄，這次沒有更新。' }
85    const list = normalize((e as unknown as { steps?: unknown }).steps)
86    if (typeof list === 'string') return { result: `沒有更新：${list}` }
87    await setSteps($, list)
88    return { result: list.length === 0 ? '側欄的任務清單已清除。' : `側欄已更新：${summarize(list).label}` }
89  })
90
91  // A finished list stays up until the person starts the next request.
92  on('prompt.submit', async ($, e, next) => {
93    const current = await read($, steps)
94    if (current.length > 0 && summarize(current).isFinished) await setSteps($, [])
95    return next(e)
96  })
97
98  on('classic.SessionStart', async ($, e, next) => {
99    const result = await next(e)
100    if (e.source === 'clear') await setSteps($, [])
101    return result
102  })
103
104  // Leave nothing behind in the sidebar once the session is gone.
105  on('session.end', async ($, e, next) => {
106    await push($, [])
107    return next(e)
108  })
109}
110

1import type { Step } from '../types'
2
3const MAX_STEPS = 12
4const MAX_TITLE = 40
5
6/** The glyph each status starts its line with; the cmux sidebar reads them back. */
7export const GLYPH: Record<Step['status'], string> = { done: '✓', active: '▸', todo: '·' }
8
9const STATUSES = new Set<string>(['done', 'active', 'todo'])
10
11/** The model's input as a clean list, or why it can't be used. An empty list clears. */
12export function normalize(raw: unknown): Step[] | string {
13  if (!Array.isArray(raw)) return 'steps 必須是陣列'
14  const steps: Step[] = []
15  for (const item of raw.slice(0, MAX_STEPS)) {
16    const title = typeof item?.title === 'string' ? item.title.replace(/\s+/g, ' ').trim().slice(0, MAX_TITLE) : ''
17    const status = typeof item?.status === 'string' && STATUSES.has(item.status) ? (item.status as Step['status']) : null
18    if (!title || !status) return '每一步都要有 title 和 status（done、active 或 todo）'
19    steps.push({ title, status })
20  }
21  return steps
22}
23
24/** The list as the sidebar shows it: one line per step, its glyph first. */
25export const describe = (steps: readonly Step[]): string =>
26  steps.map(step => `${GLYPH[step.status]} ${step.title}`).join('\n')
27
28export type Summary = { value: number; label: string; isFinished: boolean }
29
30/** 2/5 · 寫測試 — what is done, and the step under way (or the next one). */
31export function summarize(steps: readonly Step[]): Summary {
32  const total = steps.length
33  const done = steps.filter(step => step.status === 'done').length
34  const current = steps.find(step => step.status === 'active') ?? steps.find(step => step.status === 'todo')
35  const isFinished = total > 0 && done === total
36  return {
37    value: total === 0 ? 0 : done / total,
38    label: `${done}/${total} · ${isFinished ? '完成' : current?.title ?? ''}`,
39    isFinished,
40  }
41}
42

1/** One step of the task list Claude reports. */
2export type Step = { title: string; status: 'done' | 'active' | 'todo' }
3
4declare module 'claude-code' {
5  interface PluginState {
6    'task-progress': {
7      /** The main conversation's current list; empty when there is none. */
8      steps: Step[]
9    }
10  }
11}
12