Skip to content

README.md

Latest commit

 

History

History
92 lines (70 loc) · 3.56 KB

README.md

File metadata and controls

92 lines (70 loc) · 3.56 KB
Raw

SuperBased Observer — Codex plugin

Local-first token, cost and cache observability for Codex.

Requires the observer binary already on your PATH. This plugin is wiring only — it declares an MCP server that runs observer; it does not download or bundle it.

npm i -g @superbased/observer     # or: pipx install superbased-observer
observer start                    # run the local daemon

Layout

codex/                                  ← marketplace root
├── .agents/plugins/marketplace.json     ← the catalog
└── plugins/superbased/
    ├── .codex-plugin/plugin.json        ← the plugin manifest
    └── .mcp.json                        ← the MCP server it bundles

Codex looks for a repo-scoped catalog at $REPO_ROOT/.agents/plugins/marketplace.json (and a personal one at ~/.agents/plugins/marketplace.json), so the marketplace root is the directory that holds .agents/. The entry's source.path is ./plugins/superbased — relative to that root, ./-prefixed, never ../.

Install

codex plugin marketplace add superbasedapp/plugins

Then, inside Codex, open the plugin browser with /plugins, find SuperBased Observer under the superbased marketplace, and install it. Start a new thread afterwards — sessions already open do not pick up newly installed plugin files.

Other documented marketplace verbs: codex plugin marketplace list, … upgrade [name], … remove <name>. Installs are cached under ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/.

What it wires

Component What it declares
.mcp.json The observer MCP server: observer serve — the same launch observer init --codex writes into ~/.codex/config.toml's [mcp_servers.observer], transposed into the plugin's JSON shape.

Hooks are NOT in this plugin. Observer's Codex hook registrar writes TOML into ~/.codex/config.toml, and a Codex plugin's hooks live in a hooks/hooks.json whose schema is not documented on any first-party page — and the plugin-manifest spec notes that marketplace ingestion rejects an unsupported hooks manifest field. Rather than guess a schema, this plugin ships the MCP server only:

observer init --codex --skip-mcp    # hooks + proxy route, no duplicate MCP entry

Don't double-wire

observer init --codex writes the same observer server into ~/.codex/config.toml. Carrying both that entry and this plugin loads observer's MCP tool schema twice per turn (wasted context, no data corruption — observer's rows are keyed and upsert).

Codex is not auto-detected. The detect-and-skip observer init performs is internal/claudeplugin — claude-code-only, by design. There is no Codex equivalent, so if you install this plugin, pass --skip-mcp to observer init --codex yourself (or run observer uninstall --codex and re-init with --skip-mcp if you already wired it). This is documented, not built.

Not submitted anywhere

This directory is the local/self-hosted marketplace form. The manifest deliberately omits interface assets (logo, composerIcon, screenshots) and the privacy/terms URLs a public directory submission requires — those have to point at real files and real https:// pages, so an operator adds them at submission time rather than shipping placeholders.

Links