task-progress · Claude Code mod

README

cyxj-notch

cyxj-notch is a macOS notch dashboard for Claude Code: hover over the MacBook notch to see your 5-hour and weekly usage limits, every open Claude Code session (working / idle / just finished), task progress, prompt-cache countdown, and your content to-dos — fed by five small Claude Code mods that are included in this repo.

v0.1.0 · updated 2026-10-09 · tested on Claude Code 2.1.295 and macOS 26.7.1 · Changelog

What it does

When the mouse is away, the panel is exactly the size of the hardware notch, so you don't see it. Hover for 0.15 s and it grows out of the notch into a frosted-glass panel; move away and it tucks back in.

Section	What you see	Data comes from
Usage	5-hour and weekly limit used (%), when each resets	`quota-status` mod
Cache	The idle session whose prompt cache expires soonest ("12 min left")	`quota-status` mod
Sessions	Every open Claude Code session: running / idle / just finished, step `3/5` with a progress bar; click a session to jump to its Terminal.app tab	`quota-status` + `task-progress` mods
Versions	Preview servers started by headless `claude -p` runs, click to open	`version-board` mod
To-dos	Items from a Markdown log, "waiting on you" first, then "AI can continue", then "waiting until a time"	`todo-pane` mod
Publish cadence	Days since the last release and the next scheduled one	`publish-pulse` mod

Design notes:

Collapsed = the notch itself (220 × 38 pt on a 16" MacBook Pro), no extra "ears", so it never looks like something stuck on top of the menu bar.
The strip touching the notch is pure black and fades into NSVisualEffectView glass, so there's no visible seam with the hardware.
Opening uses a slightly bouncy spring and staggers the sections in (fade + 8 pt drop + blur); closing is faster, with no bounce. Exits are shorter than entrances.

How it compares

	Claude Code status line	cyxj-notch
Where	Inside one terminal	Top of the screen, reachable from any app
Sessions shown	The one it's running in	Every open session, across terminals and projects
Usage limits (5 h / weekly)	Yes, via `rate_limits`	Yes, same data, written by the `quota-status` mod
Task progress, cache countdown, to-dos	Only what you script	Built in, from the five mods
Setup	One script in `settings.json`	Build the app + load five mods

The two work together: quota-status keeps its own status line and also feeds the notch.

Requirements

macOS 14 or later (a notched MacBook is best; on other screens it uses a 200 pt "virtual notch" at the top center)
Swift 5.9+ (Xcode or Command Line Tools)
Claude Code v2.1.287 or later, where mods are on by default (tested on 2.1.295)
A Pro or Max subscription for the usage section: Claude Code only reports the 5-hour and weekly windows to subscribers, and only after the session's first response (docs)

Quick start

git clone https://github.com/chenyuxiaojin/cyxj-notch.git
cd cyxj-notch
./build.sh                      # swift build + package into build/刘海台.app
open build/刘海台.app           # no Dock or menu-bar icon
pkill -x NotchDesk              # quit

Then load the mods so the panel has something to show — add their folders to CLAUDE_CODE_PLUGIN_DIRS in ~/.claude/settings.json (colon-separated, absolute paths):

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/cyxj-notch/mods/quota-status:/path/to/cyxj-notch/mods/task-progress:/path/to/cyxj-notch/mods/version-board:/path/to/cyxj-notch/mods/todo-pane:/path/to/cyxj-notch/mods/publish-pulse",
    "NOTCH_TODO_LOG": "/path/to/your/todo-log.md",
    "NOTCH_PUBLISH_ROOT": "/path/to/your/publish-folder",
    "NOTCH_TZ_OFFSET_HOURS": "8"
  }
}

CLAUDE_CODE_PLUGIN_DIRS loads plugin folders the same way as --plugin-dir (docs); to try a mod for one session instead, run claude --plugin-dir mods/quota-status.

quota-status and task-progress need no configuration. The last three variables are optional; without them the to-do and publish sections simply stay hidden.

To tag "waiting on you" with your own name instead of 我:

defaults write com.xiaochen.notchdesk ownerName YourName

Claude Code mods in practice

A Claude Code mod is a plugin with a hooks module: a JavaScript or TypeScript file whose functions (hooks) Claude Code calls on events such as session.start, turn.complete, tool.call and ui.render, and which can call the mod API ($.ui.status, $.ui.toast, $.fs.write, $.session.usage(), $.clock.every, $.tool.register, $.env.get, …). In an interactive session, mods loaded with --plugin-dir or CLAUDE_CODE_PLUGIN_DIRS reload when you save them. Official docs: overview · create a mod · reference · testing · loading plugins · example mods.

This repo is a working example of one pattern: mods write small JSON files, a native app reads them. Claude Code stays the source of truth; the notch app is read-only and never talks to Claude Code directly.

Claude Code session ──(mod hooks)──► ~/.claude/notch/*.json ──(poll every 2 s)──► notch app

Mod	What it does inside Claude Code	What it writes for the notch
`quota-status`	Status line with 5 h / weekly usage, reset day, session cost, cache countdown; toast at 90 % usage and 5 min before cache goes cold	`sessions/<id>.quota.json` every 60 s, marked `ended` on exit
`task-progress`	Registers a `progress` tool so Claude reports multi-step work; draws a progress bar above the input box	`sessions/<id>.progress.json` on every change
`version-board`	Side pane listing preview servers from headless `claude -p` runs, with effort level and done/running; blocks opening more than 3 at once	`versions.json` every 8 s
`todo-pane`	`/daiban` side pane showing "in progress" and "published, wrapping up" from a Markdown log	`todo.json` every 5 min and after each turn
`publish-pulse`	Status line with days since last publish (traffic light) and the next scheduled release	`pulse.json` every 10 min and after each turn

Each mod has its configuration at the top of hooks/register.ts(x) and its own tests:

cd mods/quota-status
claude plugin validate .   # checks the manifest and lists the events and API calls the mod uses
claude plugin test .       # runs every *.test.ts / *.test.tsx; quota-status: 9 passed, 0 failed

All five mods pass both commands on Claude Code 2.1.295 (44 tests in total: quota-status 9, task-progress 11, version-board 13, todo-pane 2, publish-pulse 9).

Lessons from building these:

Keep the mod tiny and the file format boring. One JSON object per file, with an at timestamp; the app treats a session as closed after 150 s without an update, so crashes clean themselves up.
Write, don't serve. Writing files beats running a local server: nothing to keep alive, nothing to secure, and any app (SwiftUI, a menu-bar script, a web page) can read it.
Pure logic in its own file. quota.ts, bar.ts, scan.ts, parse.ts, pulse.ts have no engine calls, so they're unit-tested without Claude Code running.
Command names must be ASCII letters, digits, _ or -, up to 64 characters (limits). On 2.1.295 /daiban registers but /待办 and /café are rejected at runtime, and claude plugin validate doesn't catch it.

Data format

Everything lives in ~/.claude/notch/:

File	Shape
`sessions/<id>.quota.json`	`{ id, cwd, at, working, cache, limits: [{ kind: "five_hour" \	"seven_day", percentUsed, resetsAt }], tty?, app? }`
`sessions/<id>.progress.json`	`{ id, at, progress: { done, total, now } \	null }`
`versions.json`	`{ at, rows: [{ label, port, effort, state, isRunning, isVersion }] }`
`todo.json`	`{ at, busy: [{ title, next }], wrapUp: [{ title, next }] }`
`pulse.json`	`{ at, text }`

The to-do log is plain Markdown with two sections. Each "next step" starts with who's up — 我: (you), AI:, or 等 10-13 14:59: (waiting until a time):

## 当前在忙

### Notch app open source
- 状态(10-09): screenshots done, README drafted.
- 下一步: 我: record a 30-second demo
- 入口: `projects/notch/README.md`

## 已发布待收尾
- Last video(10-01): add links on two platforms.

Developing the UI

NOTCH_FEED=<folder with sample JSON> NOTCH_OPEN=1 ./build/刘海台.app/Contents/MacOS/NotchDesk

NOTCH_FEED points the app at another data folder; NOTCH_OPEN=1 opens the panel on launch and keeps it open, handy for screenshots.

Source layout:

Sources/NotchDesk/main.swift       borderless NSPanel above the menu bar, hover tracking, notch geometry
Sources/NotchDesk/NotchView.swift  SwiftUI panel, glass background, motion, all sections
Sources/NotchDesk/Feed.swift       reads ~/.claude/notch/
mods/                              the five Claude Code mods
docs/                              screenshots and demo GIF

FAQ

How do I see Claude Code usage limits on my Mac without opening a terminal? Run cyxj-notch with the quota-status mod. Hovering the notch shows your 5-hour and weekly percentages and their reset times, refreshed every 60 seconds.

What does "cache 12 min left" mean? Claude Code reuses a prompt cache while you keep talking. Each cache hit resets the timer; once a session sits idle past the lifetime, the next message re-sends the whole context — slower and more expensive. By default the main conversation gets 1 hour on a Pro/Max subscription within plan usage, and 5 minutes with an API key, a cloud provider, or usage credits beyond the plan. The mod assumes 1 hour when Claude Code reports usage windows and 5 minutes otherwise; it doesn't detect a custom promptCacheTtl, or the switch to 5 minutes once you go past plan usage. The panel shows the idle session closest to expiring, so you know which one to continue first.

Does it work without a notch? Yes. On a screen without a notch it uses a 200 pt-wide area at the top center of the main screen.

Does it send any data anywhere? No. The app only reads local files in ~/.claude/notch/; the mods only write there. No network calls.

Can I use only some of the mods? Yes. Each section hides itself when its file is missing or stale.

For AI coding assistants

llms.txt lists every file worth reading in this repo, with one line each.

About

Write-up (in Chinese) on how it was designed and iterated: 给 MacBook 刘海装了个 Claude Code 面板.

Made by @cyxj_ai, a non-programmer building tools with Claude Code. More projects: cyxj-groksearch · cyxj-hyperframes · cyxj-remotion-starter

License

MIT

Source 3 files

hooks/register.tsx 106 lines

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Progress } from '../types'
5
6import { barParts, fromTodos, toProgress } from './bar'
7
8const progress = atom({ plugin: 'task-progress', key: 'progress' } as const, null)
9const TOOL = 'mcp__task-progress__progress'
10
11// ── 可配置项 ──
12// 刘海台读这里：~/.claude/notch/sessions/<对话id>.progress.json，每个对话一份
13const feedDir = async ($: EngineInterface) => `${(await $.env.get('HOME')) ?? ''}/.claude/notch/sessions`
14
15// 改进度条，同时把新值写给刘海台
16const save = async ($: EngineInterface, fn: (p: Progress | null) => Progress | null) => {
17  let value: Progress | null = null
18  await update($, progress, p => (value = fn(p)))
19
20  const id = await $.session.id()
21  const at = await $.clock.now()
22  void $.fs.write(`${await feedDir($)}/${id}.progress.json`, JSON.stringify({ id, at, progress: value })).catch(() => undefined)
23}
24
25
26const DESCRIPTION = [
27  '在用户界面输入框上方显示任务进度条，让用户一眼看到你做到第几步。',
28  '接到需要 3 步及以上的任务时：开始前先调用一次（done=0，total=总步数，now=第一步做什么）；',
29  '之后每完成一步调用一次，更新 done 和 now；全部做完时 done 等于 total。',
30  '中途步数有变化就直接改 total。now 用 10 个字以内的中文短语。',
31].join('')
32
33export const register: Register = on => {
34  on('session.start', async ($, e, next) => {
35    await $.tool.register({
36      name: 'progress',
37      description: DESCRIPTION,
38      inputSchema: {
39        type: 'object',
40        properties: {
41          done: { type: 'integer', minimum: 0, description: '已完成几步' },
42          total: { type: 'integer', minimum: 1, description: '一共几步' },
43          now: { type: 'string', description: '正在做的这一步，10 字以内' },
44        },
45        required: ['done', 'total', 'now'],
46      },
47    })
48
49    return next(e)
50  })
51
52  on('tool.call', { tool: TOOL }, async ($, e) => {
53    const p = toProgress(e as unknown as Record<string, unknown>)
54
55    if (p === null) {
56      return { deny: 'done 和 total 要是整数，total ≥ 1，且 0 ≤ done ≤ total' }
57    }
58
59    const failed = await save($, () => p)
60      .then(() => undefined)
61      .catch((error: unknown) => String(error))
62
63    return {
64      result: failed === undefined ? `进度条已更新：${p.done}/${p.total}` : `进度条没更新：${failed}`,
65    }
66  })
67
68  on('tool.call', { tool: 'TodoWrite' }, async ($, e, next) => {
69    const ran = await next(e)
70    await save($, () => fromTodos(e.todos)).catch(() => undefined)
71
72    return ran
73  })
74
75  // 上一件活已经做完，用户发新消息时把进度条收起来；没做完的留着
76  on('prompt.submit', async ($, e, next) => {
77    const finished = (p: Progress | null) => (p !== null && p.done >= p.total ? null : p)
78    await save($, finished).catch(() => undefined)
79
80    return next(e)
81  })
82
83  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
84    const p = await read($, progress)
85
86    if (p === null || e.props.hasSurvey) {
87      return next(e)
88    }
89
90    const { Box, Text } = $.ui.resolve(e)
91    const { filled, empty } = barParts(p)
92    const isDone = p.done >= p.total
93
94    return (
95      <Box>
96        <Text color="claude">{filled}</Text>
97        <Text dimColor>{empty}</Text>
98        <Text>{`  ${p.done}/${p.total}  `}</Text>
99        <Text dimColor wrap="truncate-end">
100          {isDone ? '✓ 完成' : `正在：${p.now}`}
101        </Text>
102      </Box>
103    )
104  })
105}
106

hooks/bar.ts 42 lines

1import type { Progress } from '../types'
2
3export const BAR_WIDTH = 16
4
5// 把进度切成「已完成」和「未完成」两段格子，分开上色
6export const barParts = (p: Progress, width = BAR_WIDTH) => {
7  const total = Math.max(1, p.total)
8  const done = Math.min(Math.max(0, p.done), total)
9  const filled = Math.round((done / total) * width)
10
11  return { filled: '▓'.repeat(filled), empty: '░'.repeat(width - filled) }
12}
13
14// Claude 调「报进度」工具时传来的参数，不合格就返回 null
15export const toProgress = (input: Record<string, unknown>): Progress | null => {
16  const { done, total, now } = input
17  const isValid =
18    typeof done === 'number' &&
19    typeof total === 'number' &&
20    Number.isInteger(done) &&
21    Number.isInteger(total) &&
22    total >= 1 &&
23    done >= 0 &&
24    done <= total
25
26  if (!isValid) return null
27
28  return { done, total, now: typeof now === 'string' ? now : '' }
29}
30
31type Todo = { content: string; status: string; activeForm: string }
32
33// 会话里有自带步骤清单（TodoWrite）时，也把它画成进度条
34export const fromTodos = (todos: readonly Todo[]): Progress | null => {
35  if (todos.length === 0) return null
36
37  const done = todos.filter(t => t.status === 'completed').length
38  const current = todos.find(t => t.status === 'in_progress')
39
40  return { done, total: todos.length, now: current?.activeForm ?? '' }
41}
42

types/index.d.ts 8 lines

1export type Progress = { done: number; total: number; now: string }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'task-progress': { progress: Progress | null }
6  }
7}
8