turn-notify

README

claude-code-mods

Five mods for Claude Code that show what is happening in a session without getting in your way:

Mod	Where it shows	What it does
Tokachu (`context-pet`)	Band above the prompt	A pet that grows and turns from green to red as the context fills up
usage-meter	Status line under the prompt	Your 5-hour and 7-day usage limits, with warnings at 80% and 95%
turn-notify	Desktop notification	Tells you when a turn of one minute or more is done
changed-files	Side pane	The files that differ from HEAD, as `git diff` shows them, with added and removed lines
pr-checks	Side pane	The GitHub checks of the current branch's pull request: failed, running, passed

The mods work together: each one uses a different part of the screen, and the two panes show as tabs of the side pane. You can install all of them or only the ones you want.

Installation

You need a Claude Code version that supports mods (plugins with function hooks). The mods are tested with Claude Code 2.1.295.

Add the marketplace, then install the mods you want:

claude plugin marketplace add RenaudLavoisier/claude-code-mods

claude plugin install context-pet@claude-code-mods --scope user
claude plugin install usage-meter@claude-code-mods --scope user
claude plugin install turn-notify@claude-code-mods --scope user
claude plugin install changed-files@claude-code-mods --scope user
claude plugin install pr-checks@claude-code-mods --scope user

With --scope user, the mods load in every Claude Code session. In a session that is already open, run /reload-plugins to load them.

To get a new version:

claude plugin marketplace update claude-code-mods
claude plugin update context-pet@claude-code-mods   # same for the other mods

To remove a mod:

claude plugin uninstall context-pet@claude-code-mods

Tokachu (context pet)

Tokachu lives above the prompt and eats your context. The more of the context window the conversation uses, the bigger and redder Tokachu gets.

 /\___/\           Tokachu · 10% of context
(  ^_^  )          20k / 200k tokens
 \_____/           feeling great

 /\_____________/\   Tokachu · 70% of context
(       O_O       )  140k / 200k tokens
(                 )  bloated
(                 )
(                 )
 \_______________/

Size: the body grows from 5 to 21 cells wide and gets up to 5 rows of belly. It never takes more rows than the space above the prompt allows.
Color: a smooth gradient from green (#20df20) at 0%, through yellow (#dfdf20) at 50%, to red (#df2020) at 100%.
Face and mood:

Context used	Face	Mood
Less than 40%	`^_^`	feeling great
40% to 59%	`o_o`	well fed
60% to 79%	`O_O`	bloated
80% to 89%	`>_<`	about to burst
90% or more	`x_x`	about to explode, try /compact

While Claude works, the mood line shows nom nom….

Updates: after each API response, not only at the end of the turn. Subagents have their own context, so their requests do not feed Tokachu.
Alert: when the context goes past 80%, a toast says Tokachu ate too much: N% of context.
/clear: Tokachu goes back to its small, green size.
/pet: hides or shows Tokachu (Tokachu is taking a nap. / Tokachu is back.).

usage-meter

Shows your plan's usage limits in the status line under the prompt:

limits 5h 42% (resets in 2h10) · 7d 82% (resets in 3d4h) ⚠

Windows: 5h (five-hour limit), 7d (seven-day limit) and spend (spend limit), as Claude Code reports them.
Countdown: the time until each window resets. It refreshes every minute, also when Claude is idle.
80%: the window gets a ⚠ and a toast says, for example, 5h usage limit at 81%.
95%: a toast and a desktop notification.
Each alert fires once per level. When the usage goes down again (for example, after a reset), the alerts are ready to fire again.
The line appears only on plans with usage limits. It can stay empty until the first API response of the session.

Sends a desktop notification when a turn of one minute or more ends, so you can do something else while Claude works.

Claude Code
Done in 2m14s: The migration is ready and all tests pass.

Message: Done in <duration>: <first line of the answer>. The first line is cleaned of Markdown marks and cut at 120 characters. If the turn fails, the message is Turn failed after <duration> (or Turn refused after <duration>).
Skipped: turns that you cancel, turns shorter than one minute, and subagent turns.
Channel: the notification uses the channel set in /config (Notifications). Your own Notification hooks also receive it.
When Claude waits for a permission, Claude Code already sends its own notification, so this mod does not send a second one.

changed-files

A side pane that lists the tracked files that differ from HEAD in the session's git repository, as git diff and git status show them:

+12 -3 app/src/core/tasks.py
+40 -0 app/tests/test_tasks.py added
+0 -25 app/legacy.py deleted
bin logo.png

4 files · +52 -28 · press a file to mention it

What it lists: the staged and unstaged changes against HEAD (git diff HEAD). Untracked files are not listed: git add a new file to see it. The list shows every change in the repository, whoever made it: Claude, you in your editor, or a shell command.
Counts: +N lines added and -N lines removed, then added or deleted when the file is not only modified. bin marks a binary file. Paths are relative to the session's directory.
Updates: right after Claude runs Edit, Write, NotebookEdit or Bash, when you type /changes, and every 5 seconds while the pane is open. Git runs with --no-optional-locks, so these reads never block your own git commands.
Opening: the pane opens once per session, the first time Claude changes a file while the repository has changes, if the terminal is 144 columns wide or more. In a narrower terminal, a message tells you to type /changes, which opens the pane at any width.
Mention a file: press a file to insert @path in the prompt.
Outside a git repository: the pane says Not in a git repository.

pr-checks

A side pane that shows the GitHub checks of the pull request of the current git branch:

PR #3021
feat(core): Log caller and force flags of task API launches
✓ 14 ✗ 1 ● 2 ○ 2

✗ Run linters
● Run unit tests
● Run functional tests
✓ Run Sonarqube analysis
…

↻ refresh

Requirements: the GitHub CLI (gh), logged in with gh auth login. The mod runs git branch --show-current, gh pr view and gh pr checks.
What it lists: every check, failed (✗) and cancelled (⊘) first, then running (●), passed (✓) and skipped (○). PR #N and each check name are links to GitHub.
Updates: when the session starts, at the end of each turn, and when you press ↻ refresh. In between, every 30 seconds while a check runs or after you change branch, else every 2 minutes.
Toast: when the running checks are done, a toast says PR #N: all checks passed or PR #N: N checks failed.
Opening: the pane opens once per session, the first time the branch has a pull request, if the terminal is 144 columns wide or more. In a narrower terminal, a message tells you to type /pr-checks, which opens the pane at any width.
/pr-checks: opens the pane and lists every check with its link in the conversation, so you can ask Claude to fix a failing one.
No pull request: the pane says No pull request for branch <branch>. If gh fails, the pane shows the error.

Development

Each mod is a plugin folder:

context-pet/
├── .claude-plugin/plugin.json   # name, version, description
├── hooks/hooks.json             # points to register.tsx
├── hooks/register.tsx           # the hooks
├── hooks/*.ts                   # pure helpers
├── types/index.d.ts             # the mod's state (when it has one)
└── tests/*.test.ts

To work on the mods, clone the repository and add the clone as a local marketplace. Claude Code reads a local marketplace in place, so /reload-plugins loads your changes without a reinstall:

git clone git@github.com:RenaudLavoisier/claude-code-mods.git
claude plugin marketplace add ./claude-code-mods
claude plugin install context-pet@claude-code-mods --scope user

Check and test a mod:

claude plugin validate ./context-pet
claude plugin test ./context-pet

Before you push a change, increase version in the mod's plugin.json, so that claude plugin update finds the new version.

Source 2 files

hooks/register.tsx 17 lines

1import type { Register } from 'claude-code'
2
3import { MIN_DURATION_MS, messageOf } from './notify'
4
5export const register: Register = on => {
6  on('turn.complete', async ($, e, next) => {
7    const done = await next(e)
8    const isLongMainTurn = e.agentId === undefined && !e.isAborted && e.durationMs >= MIN_DURATION_MS
9
10    if (isLongMainTurn) {
11      await $.ui.notify(messageOf(e), { title: 'Claude Code' }).catch(() => undefined)
12    }
13
14    return done
15  })
16}
17

hooks/notify.ts 35 lines

1import type { TurnCompleteInput } from 'claude-code'
2
3export const MIN_DURATION_MS = 60_000
4
5const SUMMARY_LENGTH = 120
6
7export function formatDuration(ms: number): string {
8  const seconds = Math.round(ms / 1000)
9  if (seconds < 60) return `${seconds}s`
10
11  return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`
12}
13
14// First line of the answer that holds words, without Markdown marks.
15export function summaryOf(answer: string): string {
16  const line = answer
17    .split('\n')
18    .map(text => text.replace(/[#*`>_|-]/g, '').trim())
19    .find(text => text.length > 0)
20
21  if (line === undefined) return ''
22
23  return line.length > SUMMARY_LENGTH ? `${line.slice(0, SUMMARY_LENGTH - 1)}…` : line
24}
25
26export function messageOf(e: TurnCompleteInput): string {
27  const took = formatDuration(e.durationMs)
28  if (e.reason === 'error') return `Turn failed after ${took}`
29  if (e.reason === 'refusal') return `Turn refused after ${took}`
30
31  const summary = summaryOf(e.answer)
32
33  return summary === '' ? `Done in ${took}` : `Done in ${took}: ${summary}`
34}
35