Intermediate6 min readAutomations

Build a Claude Code mod that remembers your review checkpoints

Build a slash command that responds immediately, keeps a count during a session and displays it beside Claude Code’s spinner.

What you should be able to do

A mod registers functions for events. One function can record a checkpoint and another can display it without asking a model to count.

Saved only in this browser.
In this article

You are editing a long guide. Each time you verify a section against its source, you want to mark the checkpoint and get back to reading. Asking Claude to remember the tally would spend a turn on arithmetic. A mod lets you type /desk-check add, receive a count immediately, and see that count beside the spinner the next time Claude works.

In Claude Code, a mod is a plugin that supplies a JavaScript or TypeScript hooks module. Claude Code loads the module and calls its functions when specific events occur. The functions can share state, draw an interface, or handle a command directly. Anthropic’s hands-on mod guide specifies Claude Code 2.1.287 or later. Run claude --version in your terminal first. Use a macOS, Linux or WSL terminal with Claude Code signed in. The code below creates the files for you. Run shell blocks at your normal terminal prompt and slash commands inside Claude. Use /exit to switch back. Claude Code setup · What mods do · Version and setup

1. Follow a checkpoint through the mod

Open /plugin, go to Installed and look under Built-in. The entry cc-plugin-diff is the mod that draws the terminal’s /diff pane. Our mod has three jobs. At startup it registers a command. When you type the command, it adds or displays a checkpoint. When Claude draws its spinner, it appends the current count. Typing an unknown argument should leave the count alone. You can also describe a mod to Claude and inspect what it generates. Save a copy of a session-generated mod if you want to keep it. Built-in mods

2. Create the manifest and hook configuration

Start a new lab. Exit Claude with /exit. In your shell, run lab=$(mktemp -d "${TMPDIR:-/tmp}/claude-mod-lab.XXXXXX") && cd "$lab" && pwd. Save the printed path. Paste the file-creation blocks in full on your first visit.

Resume the lab. Type cd followed by a space and your saved path in quotes. Skip blocks that create files you already have. To try the existing mod, go directly to step 4. If the temporary folder has expired, start a new lab.

mkdir -p review-counter/.claude-plugin review-counter/hooks

cat > review-counter/.claude-plugin/plugin.json <<'JSON'
{ "name": "review-counter", "version": "1.0.0" }
JSON

cat > review-counter/hooks/hooks.json <<'JSON'
{ "modules": ["./checkpoints.js"] }
JSON

The manifest names the plugin. The modules path is relative to hooks.json. Claude Code will look for checkpoints.js in the same hooks directory. The modules entry is what makes this plugin a mod. Hooks modules in a plugin

3. Register the command and draw the result in checkpoints.js

cat > review-counter/hooks/checkpoints.js <<'JS'
let checked = 0

export function register(on) {
  on('session.start', async ($, event, next) => {
    await $.command.register({
      name: 'desk-check',
      description: 'Show review checkpoints, or add one with /desk-check add'
    })
    return next(event)
  })

  on('command.run', { command: 'desk-check' }, async ($, event) => {
    const action = (event.args ?? '').trim()
    if (action === 'add') {
      checked += 1
      $.ui.invalidate('ui.render')
    } else if (action !== '') {
      return { text: 'Use /desk-check or /desk-check add.' }
    }
    return { text: 'Checked sections: ' + checked }
  })

  on('ui.render', { component: 'Spinner' }, async ($, event, next) => {
    if (checked === 0) return next(event)
    const suffix = (event.props.suffix || '') + ' · checked ' + checked
    return next({ ...event, props: { ...event.props, suffix } })
  })
}
JS

Read the first handler from left to right. on names the event to listen for. $ gives access to Claude Code’s mod API. event holds the facts of this occurrence. next(event) passes it along to the next handler and ultimately to Claude Code. The second handler returns its own text because it has supplied the complete answer. The third sends on a copy with one display property changed. Losing the call to next in a handler that only means to observe can interrupt normal behavior. Mod events and handler results · Mods API

4. Try it in a terminal session

In the lab shell, run claude plugin validate ./review-counter. After validation passes, run claude --plugin-dir ./review-counter. Inside Claude, type /desk-check to see review-counter: Checked sections: 0. Claude Code puts the plugin’s name in front of the command’s text. Type /desk-check add twice, pressing Enter each time. The replies should count up to 1 and 2. Enter /desk-check typo for a usage hint, then /desk-check to verify the count is still 2.

Now send Suggest a title for a guide to proofreading. Look for checked 2 beside the spinner while Claude answers. If it finishes too quickly to see, the slash command still shows the count. Watch the terminal demonstration

The value lives in a JavaScript variable in the loaded module. A fresh process or a module reload creates it again at zero. That is appropriate for a temporary reading tally. A durable editorial record needs a deliberate storage choice. Claude Code provides a store API for mods that need persistence. State and storage

5. Test startup and a mistyped command offline

Type /exit to return to the shell. The first test starts a simulated session and records which command the mod registers. The second calls the handler directly and checks that a typo leaves the count alone. Its stand-in for ui.invalidate handles a redraw request without a screen. Called directly, the handler returns its text without the plugin name.

mkdir -p review-counter/tests
cat > review-counter/tests/checkpoints.test.ts <<'TEST'
import { expect, test } from 'claude-code/testing'

test('startup registers the desk-check command', async ($, on) => {
  let registeredName = ''
  on('session.start', () => ({ cwd: '/work' }))
  on('command.register', (_, event) => {
    registeredName = event.name
    return { value: undefined }
  })
  await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })
  expect(registeredName).toBe('desk-check')
})

test('only an explicit add counts a section', async ($, on) => {
  on('ui.invalidate', () => ({ value: undefined }))
  const run = (args: string) => $.command.run({ command: 'desk-check', args })
  expect((await run('')).text).toBe('Checked sections: 0')
  expect((await run('add')).text).toBe('Checked sections: 1')
  expect((await run('typo')).text).toBe('Use /desk-check or /desk-check add.')
  expect((await run('')).text).toBe('Checked sections: 1')
})
TEST
claude plugin test ./review-counter

A successful run prints 2 pass and 0 fail. If the startup test fails, check the name passed to $.command.register and that the handler runs on session.start. Use the spinner check in step 4 to see the display. Mod test kit · Where mods run

6. Diagnose, change or share it

If the command is missing, check the version, run the validator and inspect the Errors tab in /plugin. Verify the modules path and the named register export. If every mod is absent, check whether safe mode or organizational policy disabled mods. The CLI’s generated type declarations in .claude-plugin/types/ describe the API your installed release offers. External capabilities such as file access, processes and network requests go through the mods API and deserve review before installing someone else’s module. Mod troubleshooting · Mod reference

To change the wording, edit the file in your development folder. Claude Code watches locally loaded modules and reports reloads. Expect the in-memory count to restart. To stop using this development mod, start a session without --plugin-dir. To distribute it, package the whole review-counter folder through a plugin marketplace. A useful handoff includes the expected command sequence above, so the next person can establish that their installation actually works. Mod development and distribution

Read next

Continue through the same learning path with the next practical articles.