In questo articolo

🧩 Cosa sono i mod di Claude Code (e cosa cambia rispetto alla status line)

Un mod è un plugin che cambia come Claude Code appare e si comporta. È fatto di event handler in JavaScript o TypeScript: Claude Code ne chiama uno quando accade un evento — una tool call, un prompt inviato, un pezzo di interfaccia da disegnare — e l'handler può osservare l'evento, riscriverlo o rispondere al posto di Claude Code.

La differenza con quello che c'era prima è dove gira il codice. Settings hook, skill, status line e server MCP lavorano da fuori: lanciano uno script oppure danno a Claude testo o tool. Un mod gira dentro il processo di Claude Code, quindi può disegnare un pane o una band sopra il prompt, registrare un comando che risponde senza un turno del modello e condividere variabili tra un hook e l'altro.

Requisiti: Claude Code 2.1.287 o successivo nel terminale (claude --version); i mod sono attivi di default. Nella scheda Code dell'app Desktop funzionano dalla 2.1.286 inclusa nell'app. Una nota di lessico: la documentazione chiama hook gli handler di un mod e settings hook quelli configurati in settings.json. Uso la stessa convenzione.

Da fuori o da dentro

Status line e settings hook — da fuori

  • Uno script o una richiesta HTTP lanciati su un evento
  • Riceve JSON, risponde con testo o con un esito
  • Non disegna pane, band o controlli
  • Configurazione in settings.json

Mod — da dentro

  • Funzioni chiamate nel processo di Claude Code
  • Osserva, riscrive o risponde a ogni evento
  • Disegna pane, band, toast e righe di stato
  • Un plugin: manifest, hooks.json, hooks module

Se uno script esistente basta, resta lo strumento giusto: il mod serve quando voglio disegnare o intervenire sull'evento.

🗺️ Dove disegna un mod: i render site

Ogni punto in cui un mod può disegnare si chiama render site. Due sono vuoti finché un mod non li riempie: il pane — una sidebar accanto al transcript nei terminali larghi a schermo intero, altrimenti un riquadro sopra il prompt — e la band, la striscia subito sopra il campo del prompt, sempre presente e condivisa da tutti i mod.

Poi ci sono tre uscite da una sola chiamata: $.ui.status(testo) scrive una riga sotto il prompt, $.ui.toast(testo) mostra un avviso in alto a destra che sparisce da solo, $.ui.log(testo) aggiunge al transcript una riga tenue che Claude non legge. Infine i site che Claude Code disegna già — spinner, righe delle tool call, messaggi — che un mod può ritoccare o sostituire.

Per la usage bar scelgo la band: è sempre visibile, sta attaccata al prompt e accetta un albero di elementi con i colori. La riga di stato costerebbe una sola chiamata, ma è solo testo e inizia sempre con ⚠ e il nome del mod.

Dove si vede il risultato: gli hook girano in ogni sessione che carica il plugin, ma il disegno appare nel terminale, nella scheda Code dell'app Desktop e nel pannello dell'estensione VS Code (dalla 2.1.299). Con claude -p e con l'Agent SDK gli hook girano e non viene disegnato nulla.

I render site di un mod
Mappa di una sessione di Claude Code nel terminale con i punti in cui un mod può disegnare: pane a destra, toast in alto, riga di log nel transcript, band sopra il prompt e riga di stato sotto il prompt.

La usage bar vive nella band: la striscia subito sopra il prompt.

🧱 L'anatomia: una cartella, tre file obbligatori

Un mod è una directory di plugin con tre file obbligatori: il manifest .claude-plugin/plugin.json, il file hooks/hooks.json che punta al codice e il codice stesso, l'hooks module. Non servono Node.js, bundler o build: Claude Code carica direttamente i file .js, .ts e .tsx.

Per la usage bar aggiungo due file facoltativi: types/index.d.ts, richiesto quando il mod usa lo stato reattivo $.state, e un file di test. Uso l'estensione .tsx per l'hooks module perché voglio scrivere l'albero dell'interfaccia in JSX.

La cartella del mod
$ mkdir -p usage-bar/.claude-plugin usage-bar/hooks usage-bar/types usage-bar/tests

# a fine tutorial la cartella è questa
usage-bar/
├── .claude-plugin/
│   └── plugin.json        # il manifest del plugin
├── hooks/
│   ├── hooks.json         # punta all'hooks module
│   └── register.tsx       # il codice del mod
├── types/
│   └── index.d.ts         # i valori tenuti in $.state
└── tests/
    └── register.test.ts   # i test per claude plugin test

Create a mod · Claude Code Docs ↗

Tre file obbligatori, due facoltativi. Nessuna dipendenza da installare. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

📄 Manifest e hooks.json: cosa trasforma un plugin in un mod

Il manifest non ha campi speciali per i mod: nome, versione, descrizione, autore. L'unica riga in più è types, che dice a Claude Code dove ho dichiarato i valori di stato. La uso tra due passi.

È hooks.json a fare la differenza: la chiave modules elenca un solo percorso, relativo al file stesso, ed è la sua presenza a trasformare il plugin in un mod. Un'attenzione sul nome: claude plugin validate rifiuta i nomi che sembrano di Anthropic, per esempio quelli che iniziano con claude-.

plugin.json e hooks.json
// usage-bar/.claude-plugin/plugin.json
{
  "name": "usage-bar",
  "version": "0.1.0",
  "description": "Mini progress bars above the prompt with the remaining plan usage",
  "author": { "name": "Your Name" },
  "types": "./types/index.d.ts"
}

// usage-bar/hooks/hooks.json
{
  "description": "The usage-bar hooks module",
  "modules": ["./register.tsx"]
}

Files · Mods reference ↗

Due file distinti: il commento in testa a ciascuno ne indica il percorso. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

📊 Da dove arriva il dato: $.session.usage() e session.measure

Il mod non parla con nessuna API esterna: i numeri li ha già Claude Code. $.session.usage() restituisce { startedAt, context, rateLimits, cost }: context è l'uso della context window (tokens, window, percent), rateLimits è una lista di finestre del piano, ognuna con kind, percentUsed e resetsAt.

Nelle mie sessioni i kind sono five_hour per la finestra da 5 ore e seven_day per quella settimanale. Sono le cifre dell'ultima risposta dell'API: prima della prima risposta della sessione la lista è vuota, e la barra deve gestire quel caso.

Per non interrogare a vuoto c'è l'evento session.measure, che scatta dopo ogni turno e quando cambia la percentuale di un limite. Il flusso diventa: l'evento aggiorna lo stato, lo stato fa ridisegnare la band, un timer al minuto fa avanzare i countdown.

Dal dato alla band
Flusso dei dati della usage bar: session.measure e $.session.usage() scrivono le finestre del piano nello stato reattivo, un timer al minuto incrementa un contatore, e l'hook ui.render sul site AbovePrompt legge entrambi e disegna le barre sopra il prompt.

Due sorgenti, uno stato, un solo punto in cui si disegna.

🗂️ Lo stato reattivo: dichiarare i valori in types/index.d.ts

Un mod ha tre posti dove tenere un valore. Una variabile di modulo dura finché il modulo non viene ricaricato, cioè a ogni salvataggio durante lo sviluppo. $.state dura per la sessione, sopravvive al reload ed è reattivo. $.store è un key-value su disco, condiviso tra le sessioni.

Per la barra uso $.state: un hook ui.render che legge un valore si iscrive a quel valore, e Claude Code ridisegna il site ogni volta che lo scrivo. Non devo chiamare $.ui.invalidate.

I valori vanno dichiarati. La chiave esterna di PluginState è il nome del plugin; dentro ci sono i valori con il loro tipo. Me ne servono due: limits, le finestre del piano, e tick, un contatore che il timer incrementa per far avanzare i countdown.

types/index.d.ts · i valori in $.state
export type UsageWindow = {
  kind: string
  percentUsed: number
  resetsAt?: string
}

declare module 'claude-code' {
  interface PluginState {
    'usage-bar': { limits: UsageWindow[]; tick: number }
  }
}

Keep state · Claude Code Docs ↗

Un valore usato nel codice ma non dichiarato qui fa fallire la validazione. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

📥 register.tsx, parte 1: gli atom e la lettura dei limiti

L'hooks module inizia con gli atom: atom dà un nome e un default a un valore di stato, read lo legge, update lo scrive. Sono helper importati da claude-code, l'unico import non relativo ammesso in un hooks module. plugin e key vanno scritti come stringhe letterali, perché la validazione li legge dal sorgente.

refreshLimits chiede le finestre al motore e le salva solo se ce ne sono: una lettura vuota non deve cancellare le cifre che la band sta già mostrando. Nota il parametro $: l'analisi statica accetta che io passi $ a una funzione dichiarata al top level dello stesso file, e nel report la chiamata compare come $.session.usage (via refreshLimits).

I tipi EngineInterface e Register non arrivano da npm: Claude Code li scrive in .claude-plugin/types/ ogni volta che carica il mod con --plugin-dir, e descrivono eventi e metodi della versione che sto usando.

hooks/register.tsx · parte 1 di 5
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'

import type { UsageWindow } from '../types'

const limits = atom({ plugin: 'usage-bar', key: 'limits' } as const, [] as UsageWindow[])
const tick = atom({ plugin: 'usage-bar', key: 'tick' } as const, 0)

const PANE = 'usage-bar'
const BAR_CELLS = 10
const VIOLET = '#8b5cf6'
const LABELS: Record<string, string> = { five_hour: '5h', seven_day: 'Week', spend_limit: 'Spend' }

// Read the rate-limit windows from the engine; keep the old ones on an empty reading
const refreshLimits = async ($: EngineInterface): Promise<UsageWindow[]> => {
  const { rateLimits } = await $.session.usage()
  const rows = rateLimits.map(r => ({ kind: r.kind, percentUsed: r.percentUsed, resetsAt: r.resetsAt }))
  if (rows.length > 0) await update($, limits, () => rows)
  return rows
}

Mods API methods · Mods reference ↗

I cinque blocchi di register.tsx vanno incollati in ordine nello stesso file. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🧮 register.tsx, parte 2: dalla percentuale alle celle

Questa parte è TypeScript puro, senza API dei mod: trasforma una finestra in pezzi di testo da disegnare. Mostro quello che resta, non quello che ho consumato: 100 - percentUsed, limitato tra 0 e 100, diventa un numero di celle piene su dieci.

formatEta rende il tempo che manca al reset in forma compatta: 35m, 2h14m, 5d0h. toParts restituisce l'elenco dei pezzi — etichetta, celle piene, celle vuote, percentuale, countdown — e scarta quelli vuoti.

textProps esiste per un motivo preciso: ogni elemento accetta solo le props previste, e un albero che non valida viene scartato — Claude Code disegna la propria versione del site. Passo quindi color e dimColor solo quando servono.

hooks/register.tsx · parte 2 di 5
const formatEta = (ms: number): string => {
  if (ms <= 0) return 'now'
  const minutes = Math.floor(ms / 60000)
  const days = Math.floor(minutes / 1440)
  const hours = Math.floor((minutes % 1440) / 60)
  if (days > 0) return `${days}d${hours}h`
  if (hours > 0) return `${hours}h${minutes % 60}m`
  return `${minutes}m`
}

type Part = { text: string; color?: string; dim?: boolean }

// Pass only the props that are set
const textProps = (p: Part) => ({
  ...(p.color === undefined ? {} : { color: p.color }),
  ...(p.dim ? { dimColor: true } : {}),
})

// One window: label, bar of what is LEFT, percent and reset countdown
const toParts = (w: UsageWindow, now: number): Part[] => {
  const remaining = Math.max(0, Math.min(100, 100 - w.percentUsed))
  const filled = Math.round((remaining / 100) * BAR_CELLS)
  const eta = w.resetsAt ? ` ↻ ${formatEta(Date.parse(w.resetsAt) - now)}` : ''
  const parts: Part[] = [
    { text: `${LABELS[w.kind] ?? w.kind} `, dim: true },
    { text: '█'.repeat(filled), color: VIOLET },
    { text: '░'.repeat(BAR_CELLS - filled), dim: true },
    { text: ` ${Math.round(remaining)}%`, color: VIOLET },
    { text: eta, dim: true },
    { text: '   ' },
  ]
  return parts.filter(p => p.text !== '')
}

Build a tree from elements · Claude Code Docs ↗

Nessuna chiamata a $: sono funzioni qualsiasi. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🔄 register.tsx, parte 3: session.start, timer e session.measure

register è la funzione che Claude Code chiama al caricamento del mod: riceve on, e ogni chiamata a on registra un hook. Ogni hook riceve tre argomenti: l'API $, l'evento e e next, che passa l'evento agli altri mod e poi a Claude Code.

In session.start faccio tre cose: una prima lettura, il timer e il comando. Nell'hooks module non esistono setInterval e setTimeout: i timer passano da $.clock.every e $.clock.after. Ogni minuto incremento tick e rileggo le cifre. Il callback gira fuori dagli eventi, tra un turno e l'altro, senza avviare un turno.

session.start scatta di nuovo a ogni reload del mod, e i timer si fermano insieme al modulo: nessun timer doppio. L'evento va registrato una sola volta: due on('session.start') senza matcher fanno fallire il caricamento, quindi tutto il lavoro di avvio sta in un solo hook.

In session.measure aggiorno lo stato solo se e.changed contiene rateLimits, poi restituisco next(e): osservo l'evento senza cambiarlo.

hooks/register.tsx · parte 3 di 5
export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    await refreshLimits($)
    // Every minute: move the countdowns and re-read the figures
    $.clock.every(60000, () => {
      void update($, tick, n => n + 1)
      void refreshLimits($).catch((error: unknown) =>
        $.ui.log(`usage not re-read (${String(error)})`, { to: 'debug' }),
      )
    })
    await $.command.register({ name: 'usage-bar', description: 'Show remaining plan usage in a pane' })
    return next(e)
  })

  // After each turn, and when a plan limit's percent changes
  on('session.measure', async ($, e, next) => {
    if (e.changed.includes('rateLimits')) {
      await update($, limits, () =>
        e.rateLimits.map(r => ({ kind: r.kind, percentUsed: r.percentUsed, resetsAt: r.resetsAt })),
      )
    }
    return next(e)
  })

Run work in the background · Claude Code Docs ↗

Il comando si registra per ultimo: un register che lancia un errore fa saltare il resto dell'hook. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🎨 register.tsx, parte 4: disegnare nella band

Il disegno è un hook su ui.render filtrato con il matcher { component: 'AbovePrompt' }: Claude Code lo chiama ogni volta che sta per disegnare la band, e l'hook restituisce un albero di elementi. Gli elementi li prendo da $.ui.resolve(e). In un file .tsx posso poi scriverli in JSX, ma vanno destrutturati prima, perché un hooks module non ha elementi globali.

Le due read in testa fanno il lavoro reattivo: leggendo limits e tick l'hook si iscrive a entrambi, quindi viene richiamato quando arrivano nuove cifre e a ogni scatto del timer. Il valore di tick non mi serve: mi serve la sottoscrizione.

La band è condivisa. Un albero restituito sostituisce quello che disegnano i mod dopo il mio; per tenerlo metto il risultato di await next(e) tra i figli del mio Box. Quando non ho nulla da mostrare — nessuna lettura, oppure e.props.hasSurvey vero perché un sondaggio occupa la band — restituisco next(e) e lascio il posto.

Il risultato nel terminale è una riga come 5h █████████░ 87% ↻ 35m Week ██████████ 95% ↻ 5d0h.

hooks/register.tsx · parte 4 di 5
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const rows = await read($, limits)
    await read($, tick)
    // Nothing to show yet, or a survey holds the band: leave it alone
    if (e.props.hasSurvey || rows.length === 0) return next(e)

    const { Box, Text } = $.ui.resolve(e)
    const now = await $.clock.now()
    // Keep what the mods after mine draw in the band
    const below = await next(e)
    return (
      <Box flexDirection="column">
        {below}
        <Box>
          {rows.flatMap(w => toParts(w, now)).map(p => (
            <Text {...textProps(p)}>{p.text}</Text>
          ))}
        </Box>
      </Box>
    )
  })

Pick where to draw · Claude Code Docs ↗

Un hook ui.render può leggere lo stato, mai scriverlo. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

⌨️ register.tsx, parte 5: il comando /usage-bar e il pane

Il comando l'ho registrato in session.start; qui lo gestisco con command.run e il matcher { command: 'usage-bar' }. L'hook non chiama next: il comando non ha altro comportamento oltre al mio. Il text restituito finisce nel transcript, preceduto dal nome del plugin.

$.ui.open dice a Claude Code che il pane esiste, con un id scelto da me. Aprire un pane non disegna nulla: Claude Code solleva ui.render per il site Pane, e il secondo hook — filtrato su quell'id con requestId — restituisce le stesse barre, una per riga.

Perché un pane, se c'è già la band? È il posto giusto per le superfici dove la band non c'è, e un pane aperto da un comando dell'utente appare a qualsiasi larghezza. Uno aperto dal mod di propria iniziativa compare invece solo da 144 colonne in su.

hooks/register.tsx · parte 5 di 5
  on('command.run', { command: 'usage-bar' }, async $ => {
    await $.ui.open({ id: PANE, title: 'Usage' })
    return { text: 'Usage pane opened.' }
  })

  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
    const rows = await read($, limits)
    await read($, tick)
    const { Box, Text } = $.ui.resolve(e)
    if (rows.length === 0) return <Text dimColor>No usage data yet.</Text>
    const now = await $.clock.now()
    return (
      <Box flexDirection="column">
        {rows.map(w => (
          <Box>
            {toParts(w, now).map(p => (
              <Text {...textProps(p)}>{p.text}</Text>
            ))}
          </Box>
        ))}
      </Box>
    )
  })
}

Add a command · Claude Code Docs ↗

Con questo blocco register.tsx è completo. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🔁 Il loop di sviluppo: --plugin-dir, hot reload e validate

Durante lo sviluppo non installo niente: claude --plugin-dir ./usage-bar carica la cartella per una sessione e ricarica l'hooks module a ogni salvataggio. Una riga nel transcript conferma il reload ed elenca gli hook. Dopo la prima risposta di Claude la barra compare sopra il prompt; /usage-bar apre il pane.

A ogni caricamento Claude Code scrive in .claude-plugin/types/ le dichiarazioni TypeScript della versione in uso: eventi, metodi dell'API, elementi. Sono il riferimento più completo, e quando una pagina di documentazione e quei file non concordano valgono i file.

claude plugin validate fa l'analisi statica senza eseguire il codice. La riga hooks: elenca gli eventi con il loro matcher, calls: ogni metodo dell'API chiamato. Se un evento che volevo gestire manca dalla prima riga, Claude Code non chiamerà quell'hook: di solito è un nome scritto male, segnalato con un errore come "tool.calls" is not an event.

L'analisi impone qualche regola di scrittura: ogni chiamata all'API per esteso ($.ui.open, mai const ui = $.ui), i nomi degli eventi come stringhe letterali, solo import statici di file dentro il plugin. Dopo l'esito, il comando stampa anche i controlli del catalogo plugin di Anthropic (README, licenza, icona): non cambiano il risultato e riguardano chi vuole pubblicare lì.

Caricare e validare il mod
# carica la cartella per una sessione, senza installare nulla
$ claude --plugin-dir ./usage-bar

# cosa legge Claude Code dal mod, senza eseguirlo
$ claude plugin validate ./usage-bar
  ❯ ./register.tsx hooks: session.start, session.measure, ui.render{component=AbovePrompt}, command.run{command=usage-bar}, ui.render{component=Pane, requestId=usage-bar}
  ❯ ./register.tsx answers its own command: command.run{command=usage-bar}
  ❯ ./register.tsx calls: $.clock.every, $.clock.now, $.command.register, $.session.usage (via refreshLimits), $.state.get, $.state.set, $.ui.log, $.ui.open, $.ui.resolve
  ❯ ./register.tsx state writes: usage-bar.limits, usage-bar.tick
  ❯ ./register.tsx state reads: usage-bar.limits, usage-bar.tick

✔ Validation passed

Validate a mod · Claude Code Docs ↗

Output della validazione sul mod di questa pagina, con Claude Code 2.1.322. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🧪 Testare il mod senza una sessione

I test girano dalla shell con claude plugin test: nessuna sessione, nessun login, nessuna rete. Un test solleva gli eventi che gli hook gestiscono e controlla che cosa hanno fatto.

Il file importa test, expect e mock da claude-code/testing. Con on rispondo io al posto del motore: session.usage restituisce cifre finte — ogni metodo dell'API è anche un evento, con lo stesso nome senza $. — e mock.clock mi dà un orologio che controllo io.

$.ui.mount monta il site AbovePrompt del plugin su una superficie, e findAll cerca gli elementi Text disegnati. Con il 40% usato mi aspetto 60% e il countdown ↻ 42m; faccio avanzare l'orologio di due minuti e il timer deve portarlo a ↻ 40m.

Dalla cartella del mod, claude plugin test stampa (pass) draws the remaining bar with a live reset countdown e il riepilogo 1 pass, 0 fail. Il comando esce con stato 1 quando un test fallisce, quindi funziona anche in CI.

tests/register.test.ts
import { expect, mock, test } from 'claude-code/testing'

const PROPS = {
  hasSurvey: false,
  isWorking: false,
  maxRows: 10,
  bodyColumns: 120,
  scroll: { offset: 0, bodyRows: 10 },
  view: {},
}
const MINUTE = 60000

test('draws the remaining bar with a live reset countdown', async ($, on) => {
  const clock = mock.clock(on)
  const now = clock.now()
  // 40% used, so 60% left; the window resets in 42 minutes
  const rateLimits = [
    { kind: 'five_hour', percentUsed: 40, resetsAt: new Date(now + 42 * MINUTE + 30000).toISOString() },
  ]
  // Answer in the engine's place: no session, no network
  on('session.start', (_$, e) => ({ cwd: e.cwd }))
  on('session.usage', () => ({ value: { startedAt: 0, context: { window: 200000 }, rateLimits } }))
  on('session.measure', (_$, e) => ({ changed: e.changed }))

  await $.session.start({ cwd: '/tmp', surface: 'terminal', isInteractive: true })
  await $.session.measure({ context: { window: 200000 }, rateLimits, changed: ['rateLimits' as const] })

  const ui = await $.ui.mount({ plugin: 'usage-bar', surface: 'terminal', component: 'AbovePrompt', props: PROPS })
  const found = async (text: string): Promise<number> => (await ui.findAll({ type: 'Text', text })).length

  expect(await found('5h')).toBeGreaterThan(0)
  expect(await found('60%')).toBe(1)
  expect(await found('↻ 42m')).toBe(1)

  // Two minutes later the timer has moved the countdown
  await clock.advance(2 * MINUTE)
  expect(await found('↻ 40m')).toBe(1)
  expect(await found('↻ 42m')).toBe(0)
})

Test a mod · Claude Code Docs ↗

Cifre finte, orologio finto, disegno vero. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

📦 Installarlo in ogni sessione: un marketplace locale

--plugin-dir vale per una sessione. Per avere la barra ovunque il mod va installato come plugin, da un marketplace. Il marketplace può essere una cartella locale: basta un file .claude-plugin/marketplace.json nella directory che contiene usage-bar/.

Aggiungo il marketplace e installo indicando il nome del plugin, una chiocciola e il nome del marketplace. Dentro una sessione gli stessi comandi sono /plugin marketplace add e /plugin install. Se installo dalla shell mentre una sessione è aperta, /reload-plugins lo carica subito.

Per controllare: /plugin mostra sotto le schede una riga come 1 mod active · usage-bar. Due cose da sapere. Il marketplace locale punta alla cartella: se la sposto, il mod smette di caricarsi. E la copia installata è in cache per versione: una modifica arriva solo dopo aver alzato version nel manifest e reinstallato. Per questo continuo a sviluppare con --plugin-dir.

Marketplace locale e installazione
# nella cartella che contiene usage-bar/
$ mkdir -p .claude-plugin
$ cat > .claude-plugin/marketplace.json <<'EOF'
{
  "name": "my-mods",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "usage-bar",
      "source": "./usage-bar",
      "description": "Mini progress bars above the prompt with the remaining plan usage"
    }
  ]
}
EOF

$ claude plugin marketplace add "$PWD"
✔ Successfully added marketplace: my-mods (declared in user settings)
$ claude plugin install usage-bar@my-mods
✔ Successfully installed plugin: usage-bar@my-mods (scope: user)

# in una sessione già aperta
/reload-plugins

Install plugins · Claude Code Docs ↗

Per distribuirlo su più macchine, lo stesso marketplace.json va in un repository. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

🔒 Fidarsi di un mod: cosa può toccare

Un mod è codice che gira con i miei permessi, e non è in sandbox: può leggere e scrivere file ovunque arrivi il mio utente, avviare processi, fare richieste di rete, leggere variabili d'ambiente e settings, vedere ogni prompt e ogni tool call, chiamare un modello sul mio piano.

La contromisura sta nell'architettura: un hook non ha altro modo di uscire dal proprio codice che l'API $. Per questo claude plugin validate può elencare prima dell'installazione che cosa fa un mod. La usage bar di questa pagina non chiama $.fs, $.process né $.http: legge l'uso, tiene uno stato, disegna.

Per spegnerli: un singolo mod si disabilita dalla scheda Installed di /plugin; claude --safe-mode avvia una sessione senza i mod installati e senza le altre personalizzazioni; "disableAllHooks": true in ~/.claude/settings.json li ferma in ogni sessione, insieme ai settings hook e alla status line personalizzata.

Permessi e contromisure

Cosa può fare un mod

  • Leggere e scrivere file come il mio utente
  • Avviare processi e fare richieste di rete
  • Vedere e riscrivere prompt e tool call
  • Chiamare un modello sul mio piano

Come lo tengo sotto controllo

  • claude plugin validate prima di installare
  • Le righe hooks: e calls: lette una per una
  • Solo autori e marketplace di cui mi fido
  • --safe-mode o disableAllHooks per spegnere

Il prompt dei permessi non è un render site: un mod non può cambiare quello che mostra.

🤖 La scorciatoia: chiedere il mod a Claude

Tutto questo si può anche non scrivere a mano. In una sessione interattiva descrivo il mod e Claude lo scrive, usando la skill integrata plugin-authoring, che sa dove salvare i file e quali eventi e metodi ha la mia versione. Posso caricarla io con /plugin-authoring.

Al primo file salvato Claude Code chiede se abilitare l'hot reloading per la sessione: se accetto, il mod si carica a fine turno e si ricarica a ogni turno che lo modifica. Nelle modalità default e acceptEdits approvo ogni file, perché ~/.claude è un path protetto.

Un mod scritto così si carica solo nella sessione che l'ha creato, e la sua cartella viene eliminata quando supera cleanupPeriodDays. Per tenerlo lo copio fuori e lo carico con --plugin-dir, oppure lo installo dal marketplace come sopra.

Conoscere matcher, atom e next resta utile anche così: è ciò che mi permette di leggere e correggere quello che Claude genera. Per altri esempi completi, Anthropic pubblica alcuni mod nel repository claude-code-playground, cartella claude-code/mods: token-weather disegna sopra il prompt una previsione della context window.

Dal prompt al mod
# in una sessione interattiva di Claude Code
> make a mod that shows my remaining 5-hour and weekly plan usage
  as small progress bars above the prompt, with a countdown to each reset

# Claude scrive il mod nella cartella dei mod della sessione
~/.claude/dev-mods/<session-id>/usage-bar/

# per tenerlo: lo copio fuori e lo carico
$ cp -r ~/.claude/dev-mods/<session-id>/usage-bar ~/mods/usage-bar
$ claude --plugin-dir ~/mods/usage-bar

Ask Claude for a mod · Claude Code Docs ↗

Stesso risultato, partendo da una frase. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

📦 GitHub repo

Tutto il codice dell'articolo è in un repository pubblico: claude-code-mods-usage-bar. Contiene il mod usage-bar con gli stessi file di questa pagina — manifest, hooks.json, register.tsx, i tipi e il test — più un README e la licenza MIT. Il manifest del repo ha in più autore, licenza e link.

Il repository è anche un marketplace: ha il suo .claude-plugin/marketplace.json, chiamato coolsolution-mods, quindi il mod si installa direttamente da GitHub senza clonare nulla. Per leggerlo e modificarlo, invece, lo clono e lo carico con --plugin-dir.

Per provarlo serve solo Claude Code 2.1.287 o successivo: niente Node.js, niente build, nessun servizio esterno.

Clona, prova e installa il repo
# provarlo senza installare
$ git clone https://github.com/fscamuzzi/claude-code-mods-usage-bar.git
$ cd claude-code-mods-usage-bar
$ claude --plugin-dir ./usage-bar

# validare e testare
$ claude plugin validate ./usage-bar
$ cd usage-bar && claude plugin test

# installarlo da GitHub, in una sessione di Claude Code
/plugin marketplace add fscamuzzi/claude-code-mods-usage-bar
/plugin install usage-bar@coolsolution-mods
/reload-plugins

claude-code-mods-usage-bar · GitHub ↗

Codice completo nel repo: https://github.com/fscamuzzi/claude-code-mods-usage-bar

✅ Checklist finale: la usage bar in otto mosse

Ricapitolo il percorso. Il mod finito è cinque file, uno solo con la logica: nessuna build, nessuna dipendenza, e un ciclo salva-e-guarda immediato grazie all'hot reload.

La versione che uso ogni giorno aggiunge alcune rifiniture che qui ho lasciato fuori: adatta le barre alla larghezza con e.props.bodyColumns, rispetta il budget di righe maxRows della band, sfuma il colore delle celle e registra un tool per il modello con $.tool.register, così posso chiedere a Claude quanto mi resta. Sono variazioni sugli stessi cinque hook.

Una usage bar sopra il prompt in 8 mosse
  1. 01
    Versioneclaude --version: 2.1.287 o successiva
  2. 02
    Tre fileplugin.json, hooks.json con modules, register.tsx
  3. 03
    Stato dichiaratotypes/index.d.ts e types nel manifest
  4. 04
    Dato$.session.usage() e l'evento session.measure
  5. 05
    Bandui.render su AbovePrompt, next(e) tra i figli
  6. 06
    Timer$.clock.every per far avanzare i countdown
  7. 07
    Validate e testclaude plugin validate e claude plugin test
  8. 08
    Installazionemarketplace locale e plugin install

Dati che Claude Code ha già, disegnati dove li guardo.

Domande frequenti su mod di Claude Code

Che differenza c'è tra un mod e una status line personalizzata?

La status line è uno script esterno che Claude Code lancia e di cui mostra l'output come testo. Un mod è codice che gira dentro Claude Code: reagisce agli eventi, tiene uno stato e disegna alberi di elementi in pane, band e altri render site, con colori e controlli. Se mi basta una riga di testo, uno script resta la scelta più semplice; se voglio un'interfaccia o intervenire su tool call e prompt, serve un mod.

Da quale versione di Claude Code funzionano i mod?

Dalla 2.1.287 nel terminale, attivi di default; l'app Desktop li supporta dalla 2.1.286 inclusa nell'app. Gli hook girano in ogni sessione che carica il plugin, ma il disegno appare solo nel terminale, nella scheda Code dell'app Desktop e nel pannello dell'estensione VS Code dalla 2.1.299. Con claude -p e l'Agent SDK gli hook girano senza disegnare.

Da dove prende i numeri la usage bar?

Da Claude Code stesso: $.session.usage() restituisce rateLimits, una lista di finestre con kind, percentUsed e resetsAt, e l'evento session.measure avvisa quando cambiano. Sono le cifre dell'ultima risposta dell'API, quindi prima della prima risposta della sessione non c'è nulla da mostrare. Il mod non fa richieste di rete.

Perché usare $.state e non una variabile del modulo?

Per due motivi. Una variabile si azzera a ogni reload del modulo, cioè a ogni salvataggio in sviluppo, mentre $.state dura per la sessione. E $.state è reattivo: un hook ui.render che legge un valore viene richiamato ogni volta che quel valore viene scritto, senza chiamare $.ui.invalidate. Per i dati che devono restare tra una sessione e l'altra c'è invece $.store.

Come capisco cosa fa un mod prima di installarlo?

Con claude plugin validate sulla cartella del plugin: senza eseguire il codice, elenca nella riga hooks: gli eventi gestiti e nella riga calls: ogni metodo dell'API chiamato, più le letture e scritture di variabili d'ambiente e di stato. Un mod gira con i miei permessi e non è in sandbox, quindi quelle righe vanno lette: $.fs, $.process, $.http e $.model sono le chiamate che guardo per prime.

Parliamone

Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.