In questo articolo

🧩 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 o plugin di Codex

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.

Dal click su Refresh alla barra aggiornata
  1. 01
    Click in iframeApp.callServerTool('refresh_codex')
  2. 02
    CoordinatorUna lettura alla volta, minimo 60 s tra due
  3. 03
    Provider Codexspawn codex app-server, initialize, account/rateLimits/read
  4. 04
    Normalizzazionezod: percentuali, resetsAt ISO, crediti
  5. 05
    RispostastructuredContent validato + una riga di testo
  6. 06
    RenderDue 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.

plugin/mcp.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "usage_dashboard": {
      "type": "stdio",
      "command": "node",
      "args": ["${PLUGIN_ROOT}/server.mjs"]
    }
  }
}

mcp.json · GitHub ↗

Il comando resta node: il percorso del binario va nel campo env.PATH, che compila lo script di installazione.

📊 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.

server/providers/codex.ts — la sequenza JSON-RPC
// 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

codex.ts · GitHub ↗

Il figlio riceve due richieste e una notifica; qualsiasi altra riga viene ignorata.

🟢 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.

server/providers/ollama.ts — la chiave non esce dalla closure
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) };
}

ollama.ts · GitHub ↗

Senza chiave il reader restituisce unavailable senza aprire alcuna connessione.

🔄 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/mcp.ts — il tool che apre la dashboard
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: [] } } } }],
}));

mcp.ts · GitHub ↗

resourceUri collega il tool alla risorsa HTML; gli entrypoint decidono sidebar e pannello della chat.

🎨 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.

web/view.ts — il countdown al reset
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`;
}

view.ts · GitHub ↗

Mai un valore negativo: un reset già passato si legge now.

🧪 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:.

tests/codex-reader.test.ts — la riga di log prima del JSON
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 ↗

Il figlio finto scrive una riga non JSON prima di rispondere: la lettura deve riuscire lo stesso.

📦 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.

Installare il plugin
$ 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-local

codex-usage-dashboard · GitHub ↗

Codice completo nel repo: https://github.com/fscamuzzi/codex-usage-dashboard

🔒 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 il plugin e come lo tengo sotto controllo

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.

Una usage dashboard per Codex in 8 mosse
  1. 01
    Prerequisiticodex 0.166+, Node 22+, Yarn 1
  2. 02
    Manifestplugin.json, mcp.json con command node e ${PLUGIN_ROOT}
  3. 03
    Contrattischemi zod stretti condivisi da server e iframe
  4. 04
    Provider Codexcodex app-server, initialize, account/rateLimits/read
  5. 05
    Provider OllamaOLLAMA_API_KEY nell'env del server, opzionale
  6. 06
    Server MCPquattro tool, risorsa ui://, entrypoint global e thread
  7. 07
    UI e testuna pagina senza framework, 54 test senza rete
  8. 08
    Installazioneinstall.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.