In questo articolo
- 🧩 Cosa sono i mod di Claude Code (e cosa cambia rispetto alla status line)
- 🗺️ Dove disegna un mod: i render site
- 🧱 L'anatomia: una cartella, tre file obbligatori
- 📄 Manifest e hooks.json: cosa trasforma un plugin in un mod
- 📊 Da dove arriva il dato: $.session.usage() e session.measure
- 🗂️ Lo stato reattivo: dichiarare i valori in types/index.d.ts
- 📥 register.tsx, parte 1: gli atom e la lettura dei limiti
- 🧮 register.tsx, parte 2: dalla percentuale alle celle
- 🔄 register.tsx, parte 3: session.start, timer e session.measure
- 🎨 register.tsx, parte 4: disegnare nella band
- ⌨️ register.tsx, parte 5: il comando /usage-bar e il pane
- 🔁 Il loop di sviluppo: --plugin-dir, hot reload e validate
- 🧪 Testare il mod senza una sessione
- 📦 Installarlo in ogni sessione: un marketplace locale
- 🔒 Fidarsi di un mod: cosa può toccare
- 🤖 La scorciatoia: chiedere il mod a Claude
- 📦 GitHub repo
- ✅ Checklist finale: la usage bar in otto mosse
🧩 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.
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.
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.
$ 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 testCreate a mod · Claude Code Docs ↗
📄 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-.
// 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"]
}📊 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.
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.
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 ↗
📥 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.
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 ↗
🧮 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.
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 ↗
🔄 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.
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 ↗
🎨 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.
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 ↗
⌨️ 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.
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 ↗
🔁 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ì.
# 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 passedValidate a mod · Claude Code Docs ↗
🧪 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.
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 ↗
📦 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.
# 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-pluginsInstall plugins · Claude Code Docs ↗
🔒 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.
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.
# 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-barAsk Claude for a mod · Claude Code Docs ↗
📦 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.
# 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-pluginsclaude-code-mods-usage-bar · GitHub ↗
✅ 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.
- 01Versioneclaude --version: 2.1.287 o successiva
- 02Tre fileplugin.json, hooks.json con modules, register.tsx
- 03Stato dichiaratotypes/index.d.ts e types nel manifest
- 04Dato$.session.usage() e l'evento session.measure
- 05Bandui.render su AbovePrompt, next(e) tra i figli
- 06Timer$.clock.every per far avanzare i countdown
- 07Validate e testclaude plugin validate e claude plugin test
- 08Installazionemarketplace 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.



