In this article
- π§© What a Codex plugin is (and how it differs from a Claude Code mod)
- πΊοΈ The architecture: server, providers, coordinator, iframe
- π The two manifests and the local marketplace
- π Where the data comes from: codex app-server and account/rateLimits/read
- π’ Ollama Cloud, optional: a key in the server environment
- π The coordinator: one read at a time, never more than one a minute
- π The MCP server: four tools and one ui:// resource
- π¨ The interface: one page, two cards, no framework
- π§ͺ Testing without Codex and without the network
- π¦ Build and install: five files and three commands
- π Trusting a plugin: what it can touch
- π€ The shortcut: asking Codex for the plugin
- β Final checklist: the usage dashboard in eight moves
π§© What a Codex plugin is (and how it differs from a Claude Code mod)
A Codex plugin follows the Agent Plugins 1.0 specification: a folder with plugin.json (name, version, the com.openai extension with display name, category and icon) and mcp.json (the MCP servers to start). Codex registers it from a marketplace, a JSON catalogue pointing at plugin folders, and starts it like any MCP server.
The difference from a Claude Code mod is where the code runs. A mod runs inside the Claude Code process and draws in the terminal; a Codex plugin runs outside, as a separate process, and draws in an iframe that Codex opens when a tool declares a ui:// resource. The channel between the two is the MCP Apps protocol: the iframe calls the server's tools with App.callServerTool, the server answers with structured data.
For this tutorial I need Codex desktop with the codex CLI 0.166 or newer on the PATH, Node.js 22 or newer and Yarn 1. I verified everything on macOS with Apple silicon; the code uses nothing OS-specific, but I have not tried other platforms.
Claude Code mod β from inside
- TypeScript functions called in the process
- Draws in the terminal with native elements
- Data already in memory: $.session.usage()
- No build, no dependencies
Codex plugin β from outside
- Stdio MCP server started by Codex
- Draws in an iframe: HTML, CSS, JS
- Data to request: local codex app-server
- esbuild build into five files
Same goal, two architectures: the mod lives in the app process, the plugin is a server with a page.
πΊοΈ The architecture: server, providers, coordinator, iframe
The plugin has four parts. The MCP server (server.mjs) exposes four tools and one HTML resource. Two providers read the data: the Codex one spawns codex app-server and asks for the limits; the Ollama one calls GET https://ollama.com/api/balance with the key. A coordinator keeps one read in flight per provider, waits at least 60 seconds between reads and keeps the last good data when a read fails. The iframe (dashboard.html) shows the data and has two refresh buttons.
The rule behind everything: only normalized data crosses the MCP boundary. Provider responses are validated with zod against a strict schema and errors become a fixed reason (authentication, rate_limited, connection, timeout, unavailable, invalid). The original error text never reaches the iframe, the model or the logs.
- 01Click in iframeApp.callServerTool('refresh_codex')
- 02CoordinatorOne read at a time, at least 60 s apart
- 03Codex providerspawn codex app-server, initialize, account/rateLimits/read
- 04Normalizationzod: percentages, ISO resetsAt, credits
- 05Responsevalidated structuredContent + one text line
- 06RenderTwo meters, countdown to reset, status
The iframe never talks to Codex or Ollama: every piece of data goes through the local server.
π The two manifests and the local marketplace
plugin.json declares the plugin to Codex. The com.openai.interface extension is what Codex shows: display name, short description, category, icon for the sidebar and for the composer. mcp.json says how to start the server. Here comes the first practical constraint: command must stay node, because Codex rejects an absolute path as the command, and the file is reached through the ${PLUGIN_ROOT} variable.
The marketplace is a third JSON, .agents/plugins/marketplace.json, at the repo root: it lists the plugin with a local source and the path to dist/. codex plugin marketplace add <folder> registers it, and codex plugin add <plugin>@<marketplace> installs it.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"usage_dashboard": {
"type": "stdio",
"command": "node",
"args": ["${PLUGIN_ROOT}/server.mjs"]
}
}
}π Where the data comes from: codex app-server and account/rateLimits/read
Codex has no public HTTP API for quotas, but the CLI knows how to read them: codex app-server --listen stdio:// opens a JSON-RPC server on stdin/stdout that uses the existing login. The provider spawns it as a child process, sends initialize, the initialized notification and then account/rateLimits/read. The answer carries rateLimits with two windows, primary and secondary: for each, usedPercent, windowDurationMins (300 for 5 hours, 10080 for 7 days) and resetsAt in Unix seconds.
Three defensive choices, because I am starting a process with my permissions. The environment passed to the child is an allow-list (HOME, CODEX_HOME, PATH, temp and locale variables) and the PATH keeps absolute entries only. There is a cap of 15 seconds in total and 1 MiB of output, then SIGTERM and SIGKILL. And lines that are not JSON β the CLI sometimes prints a log line before the reply β are skipped instead of failing the read.
The binary is looked up in absolute PATH entries first, then in the desktop app bundle; the install script also writes CODEX_CLI_PATH into the manifest, because the PATH Codex uses to start MCP servers is minimal and often lacks the Homebrew directory.
// 1) handshake
send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'codex-usage-dashboard', version: '0.1.0' } } });
// 2) on the reply with id 1: notification + limits read
send({ method: 'initialized' });
send({ id: 2, method: 'account/rateLimits/read', params: { excludeResetCreditDetails: true } });
// 3) on the reply with id 2: normalize and close the child
settle({ ok: true, data: normalizeCodexUsage(message.result) });
// errors become a fixed reason, never the original text
// -32600 'authentication required' β authentication
// -32603 '... failed: 429 ...' β rate_limitedπ’ Ollama Cloud, optional: a key in the server environment
Ollama Cloud exposes GET https://ollama.com/api/balance with a bearer token. The response has included (balance and monthly allowance in USD, with the period) and purchased (bought credits). The provider normalizes it into remainingUsd, allowanceUsd, remainingPercent, the period dates and the credits.
The key is the project's only secret, and the rule is one: it lives only in the MCP server environment. The provider reads it from OLLAMA_API_KEY, puts it in the request header and that is all. It appears in no schema, no structuredContent, no text line. The iframe has a Content Security Policy with connectDomains: []: it cannot open any connection, so it could not use the key even if it had it.
When the variable is missing or empty, the provider reports itself as not configured: no request is sent and the card shows one line explaining how to enable it. In the private project I started from, the key went through a native helper bound to the macOS Keychain; for the public version I chose the environment variable because it is portable and takes five lines to explain. Anyone who wants more can put the helper back in front of the 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) };
}π The coordinator: one read at a time, never more than one a minute
Every read starts a process or makes an HTTP request, so it must not run on every click. The coordinator has one slot per provider with three rules: when a read is in flight, newcomers await the same promise; when the last read is less than 60 seconds old, it returns the cached result; when a read fails after a success, it keeps the old data with status stale and the new reason.
Each provider's status is ok, stale, not_configured or error, with an ISO checkedAt. It is the same object the get_usage_snapshot tool returns without contacting anyone: it is the only tool visible to the model too, so I can ask in chat how much I have left without opening the dashboard.
π The MCP server: four tools and one ui:// resource
The server uses the official MCP SDK plus two packages: @modelcontextprotocol/ext-apps, which defines the text/html;profile=mcp-app MIME type and the ui tool metadata, and @openai/mcp-extensions, which adds Codex's entrypoints. _meta['openai/ui'].entrypoints decides where the plugin shows up: global adds an entry to the sidebar, thread adds it to the right panel of every chat.
There are four tools. show_usage_dashboard opens the UI and reads nothing. get_usage_snapshot returns the last known state, visible to app and model. refresh_codex and refresh_ollama perform one read and are visible to the app only. Every answer goes through a respond function that validates the output against the schema and, when something is off, returns one fixed sentence.
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: [] } } } }],
}));π¨ The interface: one page, two cards, no framework
The UI is one HTML page with CSS and JavaScript inlined by the build. The controller creates an MCP Apps App with a PostMessageTransport towards window.parent, calls connect(), reads the theme from the host (getHostContext().theme) and applies it as data-theme, then asks for the snapshot and performs a first refresh_codex. The render is a pure function: it takes the snapshot and the date and produces the HTML of the two cards.
Each Codex window is a meter with the remaining percentage and the countdown to the reset (35m, 4h12m, 5d0h, or now when the reset is in the past). The Ollama card shows the monthly allowance with the balance in dollars and the renewal date, plus the purchased credits. Every string that comes from a provider goes through an escape function, even though it arrives validated: the iframe is the only place where data becomes markup.
A timer repaints the page every 30 seconds to move the countdowns. In tests the timer is disabled: it was the first bug I found, because setInterval kept the node:test process alive.
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`;
}π§ͺ Testing without Codex and without the network
There are 54 tests, with node:test and tsx, and none touches Codex or Ollama. The Codex provider receives a fake spawn function that answers from a script: that covers the handshake, the log line before the JSON, the authentication error, the wrapped 429, the timeout and the missing binary. The Ollama provider receives a fake request that records headers and URL: I check that the bearer goes only to ollama.com/api/balance and that with an empty key no request is sent.
The MCP server is tested with InMemoryTransport.createLinkedPair() and an SDK Client: I list the tools and check their UI metadata, read the resource and its CSP, call the tools and validate the structuredContent. The UI is tested with linkedom: render of a snapshot, meter count, countdown text, is-stale class. The build has its own test: five files in dist/, no marker left in the HTML, and a server.mjs that imports only node: modules.
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 and install: five files and three commands
yarn build runs esbuild twice: the server into a single server.mjs for Node 22, and the browser code into a bundle that is inlined into dashboard.html. The dist/codex-usage-dashboard/ folder ends up with five files: the two manifests, the server, the page and the icon. No node_modules at runtime: only Node is needed.
scripts/install.sh does the rest. It runs the build, writes env.PATH with the node and codex directories and CODEX_CLI_PATH with the binary path into the manifest, then runs codex plugin marketplace add and codex plugin add. With the --ollama-key-from-env flag it also copies OLLAMA_API_KEY from the shell into the server environment. The manifest in dist/ is git-ignored and has mode 600, but it is still a plain-text file: the README says so.
After the install, quit and reopen Codex. The dashboard appears in the sidebar; in a chat it opens from Right panel β New tab β Usage Dashboard.
$ git clone https://github.com/fscamuzzi/codex-usage-dashboard.git
$ cd codex-usage-dashboard
$ yarn install
$ scripts/install.sh
# with Ollama Cloud: the key stays in the MCP server environment
$ export OLLAMA_API_KEY=...
$ scripts/install.sh --ollama-key-from-env
# checks
$ yarn test && yarn typecheck && yarn verify
# removal
$ codex plugin remove codex-usage-dashboard@codex-usage-dashboard-localcodex-usage-dashboard Β· GitHub β
π Trusting a plugin: what it can touch
A Codex plugin is a process with my permissions, like any MCP server. Before I install one I read the server: here server/ is short on purpose. I check four things: which environment it uses to spawn child processes, where it makes network requests, what it returns to the model and what ends up in the iframe.
For the public version I ran a separate security review before the push, with an independent reviewer. The code passed; what did not pass were the design documents, which named paths on my machine and the private repo I started from. I removed them from the git history before the first push and added scripts/audit.sh, which fails yarn verify when a tracked file contains a token, a personal path or a key.
What it does
- Spawns codex app-server with an allow-listed env
- One HTTPS request to ollama.com, only with a key
- Returns normalized data and fixed reasons
- Serves an HTML page with no connections
How I keep it in check
- No secret in schemas, text or logs
- Caps: 15 s and 1 MiB for Codex, 10 s and 64 KiB for Ollama
- yarn verify: manifest schemas + audit
- Every external string goes through escape
A local MCP server has the same permissions as my user: the guarantees live in the code, not in the protocol.
π€ The shortcut: asking Codex for the plugin
As with the Claude Code mod, the short road is describing the plugin to the agent. I gave Codex three constraints: "a plugin with a stdio MCP server and an MCP App, command fixed to node, no secret in the iframe", and the link to the MCP Apps documentation. The result deserves the same attention as a downloaded plugin: the independent reviewer I used before the push was a second agent whose only job was to look for problems.
What cannot be delegated: deciding what stays out. No usage history, no telemetry, no background polling, no inference. Those are the four things a quota plugin has no reason to do.
β Final checklist: the usage dashboard in eight moves
Recapping the journey. Compared to the Claude Code mod, the plugin is bigger β two manifests, a server, a page, a build β but every piece has a clear boundary and a test that covers it. And the data is the same Codex already has: I ask the CLI instead of reading it from memory.
- 01Prerequisitescodex 0.166+, Node 22+, Yarn 1
- 02Manifestsplugin.json, mcp.json with command node and ${PLUGIN_ROOT}
- 03Contractsstrict zod schemas shared by server and iframe
- 04Codex providercodex app-server, initialize, account/rateLimits/read
- 05Ollama providerOLLAMA_API_KEY in the server env, optional
- 06MCP serverfour tools, ui:// resource, global and thread entrypoints
- 07UI and testsone framework-free page, 54 tests without network
- 08Installinstall.sh: build, PATH in the manifest, marketplace add
Data Codex already has, drawn where I look.
Frequently asked questions about Codex plugin
What is the difference between a Codex plugin and a Claude Code mod?
A Claude Code mod is TypeScript code that runs inside the app process and draws in the terminal with native elements. A Codex plugin is a separate MCP server that Codex starts; when a tool declares a ui:// resource, Codex opens it as an MCP App in an HTML iframe. The plugin takes more to build, but it can show a full interface and lives outside the app process.
Where does the dashboard get the quotas from?
From the CLI itself: codex app-server --listen stdio:// opens a JSON-RPC server that uses the existing login, and the account/rateLimits/read method returns the primary and secondary windows with usedPercent, duration and resetsAt. The plugin calls no external API for Codex and handles no token.
Is the Ollama Cloud key safe?
The key lives only in the MCP server environment, read from OLLAMA_API_KEY, and is used in the header of a single request to ollama.com/api/balance. It appears in no schema, structured response, text or log, and the iframe has a CSP with no connections. It remains a plain-text file in the dist/ manifest, git-ignored and with mode 600: anyone who wants more can put a Keychain helper in front of the provider.
Why must the manifest keep command node and an env.PATH?
Codex rejects an absolute path as the MCP server command and starts servers with a minimal PATH, which often lacks the Homebrew or nvm directory. The install script writes env.PATH with the node and codex directories and CODEX_CLI_PATH with the binary path into the manifest, so node is found and the provider finds the CLI.
How do I check what the plugin does before installing it?
By reading server/, which is short on purpose, and running yarn test, yarn build and yarn verify: the tests touch neither Codex nor the network, the build produces five files without node_modules, and verify checks the manifests against the Agent Plugins schemas and fails when a tracked file contains a token or a personal path.
Let's talk
If this topic is relevant to you, write to me: comparing notes on code and AI is always time well spent.



