In questo articolo
- 🧩 Cos'è un plugin di Codex (e cosa cambia rispetto a un mod di Claude Code)
- 🗺️ L'architettura: server, provider, coordinator, iframe
- 📄 I due manifest e il marketplace locale
- 📊 Da dove arriva il dato: codex app-server e account/rateLimits/read
- 🟢 Ollama Cloud, opzionale: una chiave nell'ambiente del server
- 🔄 Il coordinator: una lettura alla volta, mai più di una al minuto
- 🔌 Il server MCP: quattro tool e una risorsa ui://
- 🎨 L'interfaccia: una pagina, due card, nessun framework
- 🧪 Testare senza Codex e senza rete
- 📦 Build e installazione: cinque file e tre comandi
- 🔒 Fidarsi di un plugin: cosa può toccare
- 🤖 La scorciatoia: chiedere il plugin a Codex
- ✅ Checklist finale: la usage dashboard in otto mosse
🧩 Cos'è un plugin di Codex (e cosa cambia rispetto a un mod di Claude Code)
Un plugin di Codex segue la specifica Agent Plugins 1.0: una cartella con plugin.json (nome, versione, l'estensione com.openai con nome visibile, categoria e icona) e mcp.json (i server MCP da avviare). Codex lo registra da un marketplace, cioè un catalogo JSON che punta alle cartelle dei plugin, e lo avvia come qualsiasi server MCP.
La differenza con un mod di Claude Code è dove gira il codice. Un mod gira dentro il processo di Claude Code e disegna nel terminale; un plugin di Codex gira fuori, come processo separato, e disegna in un iframe che Codex apre quando un tool dichiara una risorsa ui://. Il canale tra i due è il protocollo MCP Apps: l'iframe chiama i tool del server con App.callServerTool, il server risponde con dati strutturati.
Per questo tutorial servono: Codex desktop con la CLI codex 0.166 o successiva sul PATH, Node.js 22 o successivo e Yarn 1. Ho verificato tutto su macOS con Apple silicon; il codice non usa nulla di specifico del sistema, ma non ho provato altre piattaforme.
Mod di Claude Code — da dentro
- Funzioni TypeScript chiamate nel processo
- Disegna nel terminale con elementi nativi
- Dato già in memoria: $.session.usage()
- Nessun build, nessuna dipendenza
Plugin di Codex — da fuori
- Server MCP stdio avviato da Codex
- Disegna in un iframe: HTML, CSS, JS
- Dato da chiedere: codex app-server locale
- Build con esbuild in cinque file
Stesso obiettivo, due architetture: il mod vive nel processo dell'app, il plugin è un server con una pagina.
🗺️ L'architettura: server, provider, coordinator, iframe
Il plugin ha quattro parti. Il server MCP (server.mjs) espone quattro tool e una risorsa HTML. Due provider leggono i dati: quello Codex lancia codex app-server e gli chiede i limiti; quello Ollama chiama GET https://ollama.com/api/balance con la chiave. Un coordinator tiene una sola lettura in corso per provider, aspetta almeno 60 secondi tra due letture e conserva l'ultimo dato buono quando una lettura fallisce. L'iframe (dashboard.html) mostra i dati e ha due pulsanti di refresh.
La regola che guida tutto: solo dati normalizzati attraversano il confine MCP. Le risposte dei provider vengono validate con zod contro uno schema stretto e gli errori diventano una ragione fissa (authentication, rate_limited, connection, timeout, unavailable, invalid). Il testo degli errori originali non arriva mai all'iframe, al modello o ai log.
- 01Click in iframeApp.callServerTool('refresh_codex')
- 02CoordinatorUna lettura alla volta, minimo 60 s tra due
- 03Provider Codexspawn codex app-server, initialize, account/rateLimits/read
- 04Normalizzazionezod: percentuali, resetsAt ISO, crediti
- 05RispostastructuredContent validato + una riga di testo
- 06RenderDue meter, countdown al reset, stato
L'iframe non parla con Codex né con Ollama: ogni dato passa dal server locale.
📄 I due manifest e il marketplace locale
plugin.json dichiara il plugin a Codex. L'estensione com.openai.interface è quello che Codex mostra: nome, descrizione breve, categoria, icona per la sidebar e per il composer. mcp.json dice come avviare il server. Qui c'è il primo vincolo pratico: command deve restare node, perché Codex rifiuta un percorso assoluto come comando, e il file si raggiunge con la variabile ${PLUGIN_ROOT}.
Il marketplace è un terzo JSON, .agents/plugins/marketplace.json, nella radice del repo: elenca il plugin con sorgente local e il percorso di dist/. Con codex plugin marketplace add <cartella> Codex lo registra, e con codex plugin add <plugin>@<marketplace> lo installa.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"usage_dashboard": {
"type": "stdio",
"command": "node",
"args": ["${PLUGIN_ROOT}/server.mjs"]
}
}
}📊 Da dove arriva il dato: codex app-server e account/rateLimits/read
Codex non ha un'API HTTP pubblica per le quote, ma la CLI sa leggerle: codex app-server --listen stdio:// apre un server JSON-RPC su stdin/stdout che usa il login già fatto. Il provider lo lancia come processo figlio, manda initialize, la notifica initialized e poi account/rateLimits/read. La risposta ha rateLimits con due finestre, primary e secondary: per ognuna usedPercent, windowDurationMins (300 per le 5 ore, 10080 per i 7 giorni) e resetsAt in secondi Unix.
Tre scelte difensive, perché sto lanciando un processo con i miei permessi. L'ambiente passato al figlio è una allowlist (HOME, CODEX_HOME, PATH, temp e locale) e il PATH contiene solo voci assolute. C'è un limite di 15 secondi totali e di 1 MiB di output, poi SIGTERM e SIGKILL. E le righe che non sono JSON — la CLI a volte stampa un log prima della risposta — vengono saltate invece di far fallire la lettura.
Il binario si cerca prima nelle voci assolute del PATH, poi nel bundle dell'app desktop; lo script di installazione scrive comunque CODEX_CLI_PATH nel manifest, perché il PATH con cui Codex avvia i server MCP è minimo e spesso non contiene la cartella di Homebrew.
// 1) handshake
send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'codex-usage-dashboard', version: '0.1.0' } } });
// 2) alla risposta con id 1: notifica + lettura dei limiti
send({ method: 'initialized' });
send({ id: 2, method: 'account/rateLimits/read', params: { excludeResetCreditDetails: true } });
// 3) alla risposta con id 2: normalizzo e chiudo il figlio
settle({ ok: true, data: normalizeCodexUsage(message.result) });
// errori con ragione fissa, mai il testo originale
// -32600 'authentication required' → authentication
// -32603 '... failed: 429 ...' → rate_limited🟢 Ollama Cloud, opzionale: una chiave nell'ambiente del server
Ollama Cloud espone GET https://ollama.com/api/balance con un bearer token. La risposta ha included (saldo e allowance mensile in USD, con il periodo) e purchased (i crediti comprati). Il provider la normalizza in remainingUsd, allowanceUsd, remainingPercent, le date del periodo e i crediti.
La chiave è l'unico segreto del progetto, e la regola è una: vive solo nell'ambiente del server MCP. Il provider la legge da OLLAMA_API_KEY, la mette nell'header della richiesta e basta. Non compare in nessuno schema, in nessun structuredContent, in nessuna riga di testo. L'iframe ha una Content Security Policy con connectDomains: []: non può aprire nessuna connessione, quindi non potrebbe usarla neanche se l'avesse.
Se la variabile manca, o è vuota, il provider si dichiara non configurato: nessuna richiesta parte e la card mostra una riga che spiega come attivarlo. Nel progetto privato da cui sono partito la chiave passava da un helper nativo legato al Keychain di macOS; per la versione pubblica ho scelto la variabile d'ambiente perché è portabile e si spiega in cinque righe. Chi vuole di più può rimettere l'helper davanti al provider.
export function createOllamaReader(options: OllamaReaderOptions): OllamaReader {
const key = (options.environment['OLLAMA_API_KEY'] ?? '').trim();
const request = options.request ?? httpsRequest;
if (!key)
return { configured: false, read: async () => failed(UsageFailure.Unavailable) };
return { configured: true, read: signal => requestBalance(key, request, signal) };
}🔄 Il coordinator: una lettura alla volta, mai più di una al minuto
Ogni lettura lancia un processo o fa una richiesta HTTP, quindi non deve partire a ogni click. Il coordinator ha uno slot per provider con tre regole: se c'è una lettura in corso, chi arriva aspetta la stessa promise; se l'ultima lettura è di meno di 60 secondi fa, restituisce il risultato in cache; se una lettura fallisce dopo un successo, tiene i dati vecchi con stato stale e la nuova ragione.
Lo stato di ogni provider è ok, stale, not_configured o error, con checkedAt in ISO. È lo stesso oggetto che il tool get_usage_snapshot restituisce senza contattare nessuno: è l'unico tool visibile anche al modello, così posso chiedere in chat quanto mi resta senza aprire la dashboard.
🔌 Il server MCP: quattro tool e una risorsa ui://
Il server usa l'SDK MCP ufficiale più due pacchetti: @modelcontextprotocol/ext-apps, che definisce il MIME type text/html;profile=mcp-app e i metadati ui dei tool, e @openai/mcp-extensions, che aggiunge gli entrypoint di Codex. È _meta['openai/ui'].entrypoints a decidere dove compare il plugin: global mette una voce nella sidebar, thread la aggiunge al pannello destro di ogni chat.
I tool sono quattro. show_usage_dashboard apre la UI e non legge nulla. get_usage_snapshot restituisce l'ultimo stato noto, visibile ad app e modello. refresh_codex e refresh_ollama fanno una lettura e sono visibili solo all'app. Ogni risposta passa da una funzione respond che valida l'output con lo schema e, se qualcosa non torna, restituisce una sola frase fissa.
server.registerTool('show_usage_dashboard', {
title: 'Usage Dashboard',
description: 'Open the usage dashboard from the sidebar or beside the chat.',
inputSchema: z.strictObject({}), outputSchema: z.strictObject({ opened: z.literal(true) }),
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
_meta: {
ui: { resourceUri: 'ui://usage-dashboard/dashboard.html', visibility: ['app'] },
'openai/ui': { entrypoints: [{ type: 'global' }, { type: 'thread' }] },
},
}, async () => respond(OpenedResult, () => ({ opened: true as const }), () => 'Usage dashboard opened.'));
server.registerResource('usage-dashboard', 'ui://usage-dashboard/dashboard.html', { mimeType: RESOURCE_MIME_TYPE }, async () => ({
contents: [{ uri: 'ui://usage-dashboard/dashboard.html', mimeType: RESOURCE_MIME_TYPE, text: html,
_meta: { ui: { csp: { connectDomains: [], resourceDomains: [] } } } }],
}));🎨 L'interfaccia: una pagina, due card, nessun framework
La UI è una pagina HTML con CSS e JavaScript inlinati dal build. Il controller crea un App di MCP Apps con un PostMessageTransport verso window.parent, chiama connect(), legge il tema dall'host (getHostContext().theme) e lo applica come data-theme, poi chiede lo snapshot e fa un primo refresh_codex. Il render è una funzione pura: prende lo snapshot e la data, produce l'HTML delle due card.
Ogni finestra Codex è un meter con la percentuale che resta e il countdown al reset (35m, 4h12m, 5d0h, oppure now se il reset è passato). La card Ollama mostra l'allowance mensile con il saldo in dollari e la data di rinnovo, più i crediti comprati. Ogni stringa che viene dai provider passa da una funzione di escape, anche se arriva già validata: l'iframe è l'unico posto dove un dato diventa markup.
Un timer ridisegna la pagina ogni 30 secondi per far avanzare i countdown. Nei test il timer è disattivato: è stato il primo bug che ho trovato, perché setInterval teneva vivo il processo di node:test.
export function formatCountdown(resetsAt: string | null, now: Date): string {
if (resetsAt === null)
return '—';
const left = Math.round((new Date(resetsAt).getTime() - now.getTime()) / 60_000);
if (left <= 0)
return 'now';
if (left < 60)
return `${left}m`;
const hours = Math.floor(left / 60);
if (hours < 24)
return `${hours}h${left % 60}m`;
return `${Math.floor(hours / 24)}d${hours % 24}h`;
}🧪 Testare senza Codex e senza rete
I test sono 54, con node:test e tsx, e nessuno tocca Codex o Ollama. Il provider Codex riceve una funzione spawn finta che risponde da uno script: così provo l'handshake, la riga di log prima del JSON, l'errore di autenticazione, il 429 incapsulato, il timeout e il binario mancante. Il provider Ollama riceve una request finta che registra header e URL: verifico che il bearer arrivi solo a ollama.com/api/balance e che con la chiave vuota non parta nessuna richiesta.
Il server MCP si prova con InMemoryTransport.createLinkedPair() e un Client dell'SDK: elenco i tool e controllo i metadati UI, leggo la risorsa e la CSP, chiamo i tool e valido lo structuredContent. La UI si prova con linkedom: render di uno snapshot, conteggio dei meter, testo del countdown, classe is-stale. Il build ha il suo test: cinque file in dist/, nessun marker rimasto nell'HTML, e server.mjs che importa solo moduli node:.
test('skips a log line printed before the JSON-RPC reply', async () => {
const result = await reader(fakeChild(happyScript, ['codex: starting app-server']))(new AbortController().signal);
assert.equal(result.ok, true);
});codex-reader.test.ts · GitHub ↗
📦 Build e installazione: cinque file e tre comandi
yarn build usa esbuild due volte: il server in un unico server.mjs per Node 22 e il codice del browser in un bundle che viene inlinato in dashboard.html. Nella cartella dist/codex-usage-dashboard/ restano cinque file: i due manifest, il server, la pagina e l'icona. Niente node_modules a runtime: serve solo Node.
scripts/install.sh fa il resto. Esegue il build, scrive nel manifest env.PATH con le cartelle di node e di codex e CODEX_CLI_PATH con il percorso del binario, poi lancia codex plugin marketplace add e codex plugin add. Con il flag --ollama-key-from-env copia anche OLLAMA_API_KEY dalla shell nell'ambiente del server. Il manifest in dist/ è escluso da git e ha permessi 600, ma resta un file in chiaro: lo dico nel README.
Dopo l'installazione va chiuso e riaperto Codex. La dashboard compare nella sidebar; in una chat si apre da Pannello destro → Nuova scheda → Usage Dashboard.
$ git clone https://github.com/fscamuzzi/codex-usage-dashboard.git
$ cd codex-usage-dashboard
$ yarn install
$ scripts/install.sh
# con Ollama Cloud: la chiave resta nell'ambiente del server MCP
$ export OLLAMA_API_KEY=...
$ scripts/install.sh --ollama-key-from-env
# verifiche
$ yarn test && yarn typecheck && yarn verify
# rimozione
$ codex plugin remove codex-usage-dashboard@codex-usage-dashboard-localcodex-usage-dashboard · GitHub ↗
🔒 Fidarsi di un plugin: cosa può toccare
Un plugin di Codex è un processo con i miei permessi, come qualsiasi server MCP. Prima di installarne uno leggo il server: qui server/ è corto apposta. Le cose che controllo sono quattro: con quale ambiente lancia i processi figli, dove fa richieste di rete, cosa restituisce al modello e cosa finisce nell'iframe.
Per la versione pubblica ho fatto una revisione di sicurezza separata prima del push, con un revisore indipendente. Il codice è passato; quello che non è passato erano i documenti di design, che citavano percorsi della mia macchina e il nome del repo privato da cui sono partito. Li ho tolti dalla storia di git prima del primo push e ho aggiunto scripts/audit.sh, che fallisce yarn verify se un file tracciato contiene un token, un percorso personale o una chiave.
Cosa fa
- Lancia codex app-server con env allowlist
- Una richiesta HTTPS a ollama.com, solo con chiave
- Restituisce dati normalizzati e ragioni fisse
- Serve una pagina HTML senza connessioni
Come lo controllo
- Nessun segreto in schemi, testo o log
- Limiti: 15 s e 1 MiB per Codex, 10 s e 64 KiB per Ollama
- yarn verify: schemi dei manifest + audit
- Ogni stringa esterna passa dall'escape
Un server MCP locale ha gli stessi permessi del mio utente: le garanzie stanno nel codice, non nel protocollo.
🤖 La scorciatoia: chiedere il plugin a Codex
Come per il mod di Claude Code, la strada breve è descrivere il plugin all'agente. A Codex ho dato tre vincoli: «un plugin con server MCP stdio e MCP App, command fisso a node, nessun segreto nell'iframe», e il link alla documentazione di MCP Apps. Il risultato va letto con la stessa attenzione di un plugin scaricato: il revisore indipendente che ho usato prima del push è stato un secondo agente con il solo compito di cercare problemi.
Quello che non si delega: decidere cosa deve restare fuori. Niente storico dell'uso, niente telemetria, niente polling in background, niente inferenza. Sono le quattro cose che un plugin di quote non ha motivo di fare.
✅ Checklist finale: la usage dashboard in otto mosse
Ricapitolo il percorso. Rispetto al mod di Claude Code il plugin è più grande — due manifest, un server, una pagina, un build — ma ogni pezzo ha un confine chiaro e un test che lo copre. E i dati sono gli stessi che Codex ha già: li chiedo alla CLI invece di leggerli in memoria.
- 01Prerequisiticodex 0.166+, Node 22+, Yarn 1
- 02Manifestplugin.json, mcp.json con command node e ${PLUGIN_ROOT}
- 03Contrattischemi zod stretti condivisi da server e iframe
- 04Provider Codexcodex app-server, initialize, account/rateLimits/read
- 05Provider OllamaOLLAMA_API_KEY nell'env del server, opzionale
- 06Server MCPquattro tool, risorsa ui://, entrypoint global e thread
- 07UI e testuna pagina senza framework, 54 test senza rete
- 08Installazioneinstall.sh: build, PATH nel manifest, marketplace add
Dati che Codex ha già, disegnati dove li guardo.
Domande frequenti su plugin di Codex
Che differenza c'è tra un plugin di Codex e un mod di Claude Code?
Un mod di Claude Code è codice TypeScript che gira dentro il processo dell'app e disegna nel terminale con elementi nativi. Un plugin di Codex è un server MCP separato che Codex avvia; se un tool dichiara una risorsa ui://, Codex la apre come MCP App in un iframe HTML. Il plugin è più grande da costruire, ma può mostrare un'interfaccia completa e vive fuori dal processo dell'app.
Da dove prende le quote la dashboard?
Dalla CLI stessa: codex app-server --listen stdio:// apre un server JSON-RPC che usa il login già fatto, e il metodo account/rateLimits/read restituisce le finestre primaria e secondaria con usedPercent, durata e resetsAt. Il plugin non chiama nessuna API esterna per Codex e non gestisce token.
La chiave di Ollama Cloud è al sicuro?
La chiave vive solo nell'ambiente del server MCP, letta da OLLAMA_API_KEY, e viene usata nell'header di una sola richiesta a ollama.com/api/balance. Non compare in schemi, risposte strutturate, testo o log, e l'iframe ha una CSP senza connessioni. Resta però un file in chiaro nel manifest di dist/, escluso da git e con permessi 600: chi vuole di più può mettere un helper del Keychain davanti al provider.
Perché il manifest deve avere command node e un env.PATH?
Codex rifiuta un percorso assoluto come comando del server MCP e avvia i server con un PATH minimo, che spesso non contiene la cartella di Homebrew o di nvm. Lo script di installazione scrive nel manifest env.PATH con le cartelle di node e di codex e CODEX_CLI_PATH con il percorso del binario, così node si trova e il provider trova la CLI.
Come verifico cosa fa il plugin prima di installarlo?
Leggendo server/, che è corto apposta, e lanciando yarn test, yarn build e yarn verify: i test non toccano Codex né la rete, il build produce cinque file senza node_modules e verify controlla i manifest contro gli schemi Agent Plugins e fallisce se un file tracciato contiene un token o un percorso personale.
Parliamone
Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.



