Codex Capability Registry

An installable proof-of-concept plugin that remembers configured Codex capabilities and helps avoid repeated discovery when a capability is explicitly failing.

Version 0.2 narrows automatic activation and compact output to reduce the plugin's own context overhead. It does not guarantee lower total token use on every task; savings depend on whether the registry prevents a longer repeated-discovery loop.

Why

An installed capability can be configured correctly yet still be unavailable to a particular thread because of authentication, startup, policy, runtime, or session-attachment problems. Treating every failure as "not installed" causes repeated probing, misleading installation prompts, unnecessary fallbacks, and extra context usage.

This project distinguishes configured, ready, needs_auth, unavailable_in_session, unhealthy, and missing.

What changed in v0.2

• The skill activates only for explicit missing, unavailable, authentication-blocked, unhealthy, repeated-rediscovery, or fallback symptoms.
• show returns only name, kind, state, and known enabled/checked_at fields by default.
• show --verbose returns the complete cached entry.
• Schema-1 caches created by v0.1 remain readable.
• A deterministic fixture benchmark reports context-facing character and token estimates.

Install

Add this repository as a Codex marketplace:

codex plugin marketplace add BochengYao/codex-capability-registry

Restart Codex, open /plugins, select the Capability Registry marketplace, and install Codex Capability Registry. Start a new thread after installation.

Use

The skill activates automatically only when a capability problem is explicit. It can also be invoked directly:

$use-capability-registry Check why Browser is unavailable before choosing a fallback.

Refresh the local inventory:

python plugins/codex-capability-registry/scripts/capability_registry.py scan

Inspect one capability:

python plugins/codex-capability-registry/scripts/capability_registry.py show --name browser

Request the complete cached entry only when needed:

python plugins/codex-capability-registry/scripts/capability_registry.py show --name browser --verbose

The default cache is $CODEX_HOME/capability-registry/cache.json, falling back to ~/.codex/capability-registry/cache.json.

Benchmark

Run:

python plugins/codex-capability-registry/scripts/benchmark_context.py

The v0.2.0 fixture uses the conservative estimate ceil(characters / 4):

Artifact	Characters	Estimated tokens
Skill metadata	205	52
Skill body	952	238
Scan output	155	39
Compact single-capability output	151	38
Verbose single-capability output	425	107
Full disk cache	643	161

The full disk cache is measured for comparison but is not automatically loaded into model context. These figures measure deterministic plugin artifacts, not a real tokenizer bill or universal end-to-end savings.

What is cached

The registry stores capability names, types, enabled flags, versions, short descriptions, local metadata source paths, fingerprints, timestamps, states, and short diagnostics.

It intentionally does not store tokens, secrets, credentials, environment-variable names or values, MCP endpoints, headers, commands, arguments, complete tool output, or skill instruction bodies.

Important boundary

This plugin cannot change Codex's core tool injection or make a tool appear in the current session. A cached ready or configured state is evidence about local setup, not proof of current-thread availability. The skill still requires one targeted live check before an action depends on a session-scoped tool.

The plugin also cannot bypass sandboxing, approvals, authentication, workspace policy, or administrator controls. It never installs missing software silently.

Commands

scan       Refresh configured skills, plugins, and MCP servers
show       Print compact cached entries; add --verbose for complete entries
check      Record an evidence-based state after one targeted check
invalidate Remove one entry or clear the plugin-owned cache

Run python plugins/codex-capability-registry/scripts/capability_registry.py COMMAND --help for command options.

Development

The runtime uses only the Python 3.11+ standard library.

python -m unittest discover -s tests -v
python plugins/codex-capability-registry/scripts/benchmark_context.py

Plugin and skill validation use the validators bundled with Codex's plugin-creator and skill-creator skills.

Uninstall

Open /plugins, select Codex Capability Registry, and choose Uninstall. Remove the marketplace with:

codex plugin marketplace remove codex-capability-registry

The optional cache can then be deleted from ~/.codex/capability-registry/cache.json. No Codex core files are modified.

Status

This is an independent proof of concept, not an OpenAI product. A linked feature request proposes native capability-state caching and session diagnostics inside Codex itself.