image-peek

README

my-claude-code-mods

Six mods for Claude Code: a one-line status bar, image previews for pasted screenshots, boxed cards for tool calls, a keepalive for the prompt cache, a weekly calendar of your sessions, and animated diagrams Claude can draw in the transcript.

Mods are Claude Code plugins built from function hooks. They need Claude Code 2.1.287 or newer. Mods are an early-access feature: the hooks API can change between releases.

Mod	What it does
`slick-bar`	Replaces the hint line under the prompt with a one-line bar: model, effort, folder, branch, context gauge, prompt-cache health, rate-limit gauges
`image-peek`	Shows a preview of a pasted image above the prompt and under the message that sent it
`tool-cards`	Draws each tool call as a boxed card: highlighted command, output preview, timing footer
`cache-warm`	Keeps the prompt cache of an idle chat warm with a small capped ping, and counts cache hits and misses
`week-calendar`	`/week` draws a calendar of the week's sessions with commits, hours per project, and a 3-line report
`diagram-mod`	Gives Claude a `show_diagram` tool: animated diagrams that play a story step by step, with packets, gauges and a live log

Install

Clone the repo:

   git clone https://github.com/mustafa89/my-claude-code-mods.git ~/.claude/mods

Tell Claude Code to load the mods. Add this to the env block of ~/.claude/settings.json (paths separated by :; ~ is allowed):

   {
     "env": {
       "CLAUDE_CODE_PLUGIN_DIRS": "~/.claude/mods/slick-bar:~/.claude/mods/image-peek:~/.claude/mods/tool-cards:~/.claude/mods/cache-warm:~/.claude/mods/week-calendar:~/.claude/mods/diagram-mod"
     }
   }

Leave out the mods you do not want. slick-bar lists cache-warm as a dependency for its cache segment, so load the two together.

Start a new Claude Code session. Each mod prints <name>: loaded in the transcript.

To try one mod for a single session only:

claude --plugin-dir ~/.claude/mods/slick-bar

If you use a statusLine command, the bar does not replace it. The bar sits on the hint line under the prompt; your status line stays below it. Remove statusLine from your settings if you want only the bar.

slick-bar

One line under the prompt, after Claude Code's own permission-mode label:

Model and effort: ✻ Opus 5.5 1M · medium. The ✻ turns into ◉ while a turn runs.
Folder and branch: repository name (plus subfolder), branch, ± when the tree has changes, ↑/↓ for commits ahead of or behind the upstream.
Context gauge: how full the context window is, green → amber → red.
Rate-limit gauges (subscription plans): 5-hour and 7-day usage, the time until each window resets (↻ 3h12m), and a ┃ tick that marks how much of the window has passed. Usage to the right of the tick means you are using it faster than the window allows; the percentage turns amber when the current pace projects past 100%.
Prompt cache (with cache-warm): cache ● 97% 52m ✗1 ⟳2. The dot is green while the cache is warm, amber in the last minutes before it expires, and ○ cold after. Then the share of the last request served from cache, the time until the cache expires, misses (✗) and keepalive pings (⟳).

When the terminal is narrow, segments drop in this order: hint text, 7-day gauge, token count, cache, branch, folder. The model and the context gauge always stay.

The bar needs a Nerd Font for the pill shapes and icons.

While you write a prompt, every pasted image shows above the prompt with its size (Image #3 · 1246×846).
After you send it, the image shows under your message in the transcript.

image-peek draws real images through the kitty graphics protocol, so it needs a terminal that supports it, such as kitty or Ghostty. Elsewhere it shows the image's label instead.

It also needs macOS: it uses sips to make a smaller copy of each image.

Terminal multiplexers: inside a multiplexer that passes kitty graphics through but identifies itself differently (for example herdr, which reports libghostty), Claude Code turns graphics off. To turn them on, add this to the same env block:

"CLAUDE_CODE_FORCE_TERMINAL_IMAGES": "1"

Only do this if your terminal really supports kitty graphics. Otherwise images draw as empty boxes.

tool-cards

Every tool call becomes a card:

Header: tool name and status: ✓ done, ◌ running, ✗ error, ⊘ interrupted. The command's description follows.
Bash: the command with syntax colours, then the first 5 lines of output (errors in red).
Edit and Write: a split diff, old on the left and new on the right, with line numbers, red and green rows, and the changed words highlighted. A +N -M header with a bar shows the size of the change. Narrow terminals stack old over new. A new file from Write keeps Claude Code's own view.
MCP tools: the arguments, then the output folded behind ▾ output · N lines. JSON is indented; errors show in red.
Other tools: one line saying what the call acted on, for example src/cart/total.js:10-30 for a Read.
Footer: how long the call took, how many words it printed, and the Bash timeout if one was set.
Diagrams from diagram-mod: a rounded card headed ◇ diagram, as wide as the diagram, with the animation inside and ▴ collapse / ▾ expand.

Claude Code normally folds runs of reads and searches into one line (Searched for 2 patterns). tool-cards unfolds them, so each call gets its own card.

Expanding output

Click ▾ expand on a card to see all of its output or diff (up to 400 lines). Clicks reach the card in fullscreen mode.
/cards full expands every card; /cards compact goes back to the preview (5 output lines, 16 diff rows, MCP output folded); /cards switches between the two.

Ctrl+o does not expand a card. Claude Code does not tell mods when the Ctrl+o view is open.

cache-warm

Claude Code caches the conversation on the API side. A request that reads the cache pays a small part of the input price; a request after the cache expired writes the whole conversation again. cache-warm sends one small request just before the cache expires, so an idle chat stays warm.

How it works

Timer: a 15-second timer runs inside the Claude Code session. There is no cron job; the timer stops when the session closes or the computer sleeps.
Ping: when the chat is idle and the cache is 2 minutes from expiry, the mod calls $.model.fork. The fork sends the session's last request again with a one-line prompt. The API reads the conversation from the cache, and that read starts the cache lifetime again. The fork runs no tools and does not show in the transcript.
Hits and misses: after each turn, the mod reads the token counts of the turn's first request. If less than half of the input came from the cache, the turn counts as a miss.

Why it is worth it

Prompt caching prices, as a multiple of the normal input price:

Request	Price
Cache write, 1-hour cache	2×
Cache write, 5-minute cache	1.25×
Cache read	0.1× (Opus 5.5: 0.05×, Fable 5.1: 0.025×)

Example: a 400k-token chat on Opus 5.5 with the 1-hour cache.

The cache expires: your next prompt writes 400k tokens at 2×, the cost of 800k input tokens.
The cache is warm: your next prompt reads 400k tokens at 0.05×, the cost of 20k input tokens.
One ping: the same read, 20k.

A ping costs 1/40 of a cold restart. Four pings cost 80k, one tenth of a restart, even if you never come back to the chat. The keepalive pays for itself when there is a better than 1-in-40 chance that you come back within the next hour. At the general read price of 0.1×, the break-even is 20 pings.

Limits on the pings

Cap: at most maxPings pings (default 4) per idle stretch. A prompt you type resets the count.
Rate limit: no pings while the 5-hour usage window is 80% full or more.
Expired cache: no ping after the cache expired, for example after the computer slept. A ping then would pay a full cache write.
Missed ping: when a ping does not read from the cache, the mod stops pinging until your next turn.
Failed ping: an API error does not count as a refresh. The next tick tries again.

Settings and command

Setting	Values	Default
`ttl`	`1h`, `5m`	`1h`
`maxPings`	a number	`4`

Change them in /config. Claude Code sessions use the 1-hour cache on most plans. Use 5m for the API default, or when your account runs in usage overage.

/cache-warm status shows the cache state, /cache-warm off stops the pings, /cache-warm on starts them again.

week-calendar

The screenshot shows a real week with every title, project and commit replaced.

/week builds a calendar of this week's Claude Code and Codex sessions, opens it in your browser, and prints a 3-line report:

Shipped: rate limiting, CI runner migration, deploy runbook
Most time: api-service, 22h 27m
Next: Prototype caching layer, Upgrade database driver

/week last shows last week; /week -2 goes two weeks back.

What the calendar shows

Sessions as blocks, one colour per project. A session splits into blocks at gaps longer than 30 minutes.
Commits you made during each block, matched by your git config user.email.
Sessions that ended without a commit: a dashed outline and an amber dot. The sidebar lists them, longest first.
Active time: hours per project and per day. Sessions that run in parallel count once.
Details: click a block to see its time, model, commits, and the first message you typed.

How it works

bin/build.mjs reads ~/.claude/projects/**/*.jsonl and ~/.codex/sessions/**/*.jsonl, runs git log in each project, and writes one HTML file to ~/.calendar/week-<monday>.html. Node only, no network.
The hook sends the week's commit subjects to Sonnet once to write the "Shipped" line.
The HTML file holds all its data inline and loads nothing from the network.

The calendar file holds the first message of each session as plain text. It stays on your machine.

Settings

~/.calendar/config.json is created on the first run:

Setting	Default	What it does
`dayStartHour`	`6`	Work before this hour counts toward the previous day
`gapMinutes`	`30`	A gap longer than this starts a new block
`minNoCommitMinutes`	`15`	Shorter blocks are not flagged as ending without a commit
`weekStart`	`mon`	`mon` or `sun`
`theme`	`dark`	`dark` or `light`
`accent`, `palette`		Colours for today, the busiest day, and the projects

It needs Node and git. It opens the file with open on macOS or xdg-open on Linux.

diagram-mod

Ask Claude for a diagram or a visual explanation and it calls the mod's show_diagram tool. The diagram draws in the tool's row in the transcript:

Boxes: a label, detail lines and a status, with dashed borders in the colour of their role. A status has a tone: a spinner while running, ✓ ok, ✗ error, ! warning.
Edges: dashed arrows with optional labels. The layout runs top to bottom and is computed from the edges; Claude never gives coordinates. Edges that point back up, or skip a row, run along the right margin.
Packets: braille "comets" with a fading tail, moving a quarter cell at a time.
Gauges: bars (meters) that fill in eighths of a cell, and a moving activity wave (spark).
Side panels: a node with side: "left" or "right" becomes a tall panel beside the tree, with rows a step can highlight.
Frame: a legend under the title, a caption under the diagram, a log table (time, actor, message, status) and a footer of counters.

Stories

Give the spec steps and the diagram plays them in a loop. Each step names the edges carrying traffic (only those light up), changes node statuses, meters and panel highlights, adds log rows, and moves the counters. Meters ease to their new values and counters count up across the step. Without steps, packets loop on the edges you name.

examples/agent-tree.json is the story in the GIF; examples/dispatcher.json is a simple diagram without steps. The bundled skill tells Claude when to use the tool and how to keep a diagram readable: one idea, about 12 nodes at most, labels of 1-3 words, 3-6 steps.

How it animates

About 60 frames a second, repainting one cell grid in place; frames that would not change are skipped.
Only the newest diagram moves; older ones keep a still frame.
The animation waits while Claude is still writing its reply, so the streaming text stays fast, and pauses while the row is scrolled out of view or folded.
A terminal narrower than the diagram gets a still text version instead.

Settings

Setting	Default	What it does
`display`	`inline`	`inline`: the diagram animates in the transcript row. `pane`: it opens in a side pane, closed with `q` or `Esc` (Claude Code only seats a pane it did not ask for from 144 columns)

Development

Each mod is a folder:

<mod>/
  .claude-plugin/plugin.json   name, version, description, types
  hooks/hooks.json             { "modules": ["./register.tsx"] }
  hooks/register.tsx           the hooks
  types/index.d.ts             the state the mod keeps
  tests/*.test.tsx             tests

Check and test a mod:

claude plugin validate ./slick-bar
claude plugin test ./slick-bar

Claude Code writes the API types into <mod>/.claude-plugin/types/ the first time it loads a mod; those files are not committed. A session started with --plugin-dir reloads a mod when you save its files.

Limits

These come from the mods API, not from the mods:

Permission mode: mods cannot read it, so the bar sits after Claude Code's own mode label.
Space above the prompt: the empty row between the transcript and the prompt belongs to Claude Code.
Ctrl+o: tool rows do not report the expanded view (see Expanding output).
Cache lifetime: mods cannot read which cache lifetime the session uses, so cache-warm takes it from the ttl setting.
Tool names: Claude Code lists a tool a mod registers as mcp__<mod>__<tool>, so diagram-mod's tool is mcp__diagram-mod__show_diagram though no MCP server is involved.

License

MIT

Source 2 files

hooks/register.tsx 164 lines

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Preview } from '../types'
5
6const draft = atom({ plugin: 'image-peek', key: 'draft' } as const, [])
7const previews = atom({ plugin: 'image-peek', key: 'pictures' } as const, {})
8
9// Long side of the PNG sent to the terminal: sharp at preview size, well under the 2 MiB Image limit.
10const MAX_PIXELS = 1000
11const MAX_COLUMNS = 100
12const MAX_ROWS = 18
13const IMAGE_REF = /\[Image #(\d+)\]/g
14// A paste can reach the box before its file is written: retry a few times.
15const ATTEMPTS = 4
16const RETRY_MS = 400
17
18type $ = EngineInterface
19
20function imageRefs(text: string) {
21  return [...new Set([...text.matchAll(IMAGE_REF)].map(m => Number(m[1])))]
22}
23
24const sameList = (a: readonly number[], b: readonly number[]) => a.length === b.length && a.every((n, i) => n === b[i])
25
26// Pasted images live in /private/tmp/claude-<uid>/<project>/<session id>/images/<n>.<ext>.
27async function findImage($: $, n: number) {
28  const id = await $.session.id()
29  if (!/^[0-9a-f-]+$/i.test(id)) return null
30  const { stdout } = await $.process.run([
31    '/bin/sh',
32    '-c',
33    `ls /private/tmp/claude-*/*/${id}/images/${n}.* 2>/dev/null | head -1`,
34  ])
35  return stdout.trim() || null
36}
37
38async function render($: $, src: string): Promise<Preview | null> {
39  const dims = await $.process.run(['sips', '-g', 'pixelWidth', '-g', 'pixelHeight', src])
40  const width = Number(/pixelWidth: (\d+)/.exec(dims.stdout)?.[1])
41  const height = Number(/pixelHeight: (\d+)/.exec(dims.stdout)?.[1])
42  if (!width || !height) return null
43
44  const out = `${src}.peek.png`
45  const conv = await $.process.run(['sips', '-s', 'format', 'png', '-Z', String(MAX_PIXELS), src, '--out', out])
46  if (conv.exitCode !== 0) return null
47  const { base64 } = await $.fs.read(out, { as: 'bytes' })
48  await $.process.run(['rm', '-f', out])
49  return { width, height, png: base64 }
50}
51
52// Cells for a picture: at most `maxColumns` x `maxRows`, aspect kept (a cell is about twice as tall as wide).
53function box(p: Preview, maxColumns: number, maxRows: number) {
54  const columns = Math.max(1, Math.min(maxColumns, Math.round((maxRows * 2 * p.width) / p.height)))
55  const rows = Math.max(1, Math.min(maxRows, Math.round((columns * p.height) / (2 * p.width))))
56  return { columns, rows }
57}
58
59async function ensure($: $, ns: readonly number[]) {
60  for (const n of ns) {
61    if ((await read($, previews))[n] !== undefined) continue
62    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
63      const src = await findImage($, n)
64      const preview = src !== null ? await render($, src) : null
65      if (preview !== null) {
66        await update($, previews, map => ({ ...map, [n]: preview }))
67        break
68      }
69      await $.clock.sleep(RETRY_MS)
70    }
71  }
72}
73
74export const register: Register = on => {
75  // Earlier images of this session (a resume, a reload) get previews too.
76  on('session.start', async ($, e, next) => {
77    const result = await next(e)
78    const id = await $.session.id()
79    if (/^[0-9a-f-]+$/i.test(id)) {
80      const { stdout } = await $.process.run(['/bin/sh', '-c', `ls /private/tmp/claude-*/*/${id}/images/ 2>/dev/null`])
81      const ns = [...stdout.matchAll(/^(\d+)\.(png|jpe?g|gif|webp)$/gm)].map(m => Number(m[1]))
82      $.clock.after(0, () => void ensure($, ns).catch(() => undefined))
83    }
84    return result
85  })
86
87  // Track which pasted images the draft holds.
88  on('prompt.edit', async ($, e, next) => {
89    const ns = imageRefs(e.text.slice(0, e.start) + e.inputText + e.text.slice(e.end))
90    if (!sameList(ns, await read($, draft))) {
91      await update($, draft, () => ns)
92      if (ns.length > 0) $.clock.after(0, () => void ensure($, ns).catch(() => undefined))
93    }
94    return next(e)
95  })
96
97  on('prompt.submit', async ($, e, next) => {
98    const ns = imageRefs(e.text)
99    if (ns.length > 0) $.clock.after(0, () => void ensure($, ns).catch(() => undefined))
100    await update($, draft, () => [])
101    return next(e)
102  })
103
104  // While drafting: the pasted images above the prompt.
105  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
106    if (e.props.hasSurvey || e.surface !== 'terminal') return next(e)
107    const [ns, map] = await Promise.all([read($, draft), read($, previews)])
108    const shown = ns.filter(n => map[n] !== undefined)
109    if (shown.length === 0) return next(e)
110
111    const { Box, Text, Image } = $.ui.resolve(e)
112    const maxColumns = Math.min(MAX_COLUMNS, Math.floor(e.props.bodyColumns / shown.length) - 2)
113    // The band scrolls past `maxRows`: keep the picture and its caption inside it.
114    const maxRows = Math.max(1, Math.min(MAX_ROWS, e.props.maxRows - 1))
115    return (
116      <Box flexDirection="row" gap={2}>
117        {shown.map(n => {
118          const p = map[n]!
119          const label = `Image #${n} · ${p.width}×${p.height}`
120          return (
121            <Box key={`draft-${n}`} flexDirection="column">
122              <Image key={`draft-img-${n}`} source={{ png: p.png }} {...box(p, maxColumns, maxRows)} alt={label} />
123              <Text dimColor>{label}</Text>
124            </Box>
125          )
126        })}
127      </Box>
128    )
129  })
130
131  // In the transcript: the images under the message that sent them.
132  on('ui.render', { component: 'UserMessage' }, async ($, e, next) => {
133    if (e.surface !== 'terminal') return next(e)
134    const ns = imageRefs(e.props.text)
135    if (ns.length === 0) return next(e)
136    const map = await read($, previews)
137    const shown = ns.filter(n => map[n] !== undefined)
138    if (shown.length === 0) return next(e)
139
140    const base = await next(e)
141    const { Box, Image } = $.ui.resolve(e)
142    const width = (e.viewport?.columns ?? 120) - 4
143    const maxColumns = Math.min(MAX_COLUMNS, Math.floor(width / shown.length) - 2)
144    return (
145      <Box flexDirection="column">
146        {base}
147        <Box flexDirection="row" gap={2} marginLeft={2} marginTop={1}>
148          {shown.map(n => {
149            const p = map[n]!
150            return (
151              <Image
152                key={`msg-img-${n}`}
153                source={{ png: p.png }}
154                {...box(p, maxColumns, MAX_ROWS)}
155                alt={`Image #${n} · ${p.width}×${p.height}`}
156              />
157            )
158          })}
159        </Box>
160      </Box>
161    )
162  })
163}
164

types/index.d.ts 19 lines

1export type Preview = {
2  /** Source size in pixels. */
3  width: number
4  height: number
5  /** The picture as a PNG, base64, downscaled to fit the Image byte limit. */
6  png: string
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    'image-peek': {
12      /** Image numbers referenced by the prompt draft, in order. */
13      draft: number[]
14      /** Previews by image number. */
15      pictures: Record<string, Preview>
16    }
17  }
18}
19