feat(plugin): ship Codex plugin manifest + marketplace

[rohitg00]

Why

OpenAI Codex now has a plugin platform (developers.openai.com/codex/plugins). Same shape as Anthropic Claude Code plugins: .codex-plugin/plugin.json manifest, optional .mcp.json, hooks/hooks.json, and a skills/ directory.

Verified against the openai/codex source (not docs):

• codex-rs/hooks/src/engine/discovery.rs — Codex's hook engine explicitly injects CLAUDE_PLUGIN_ROOT into hook subprocesses for OOTB compat with existing Claude Code plugins:

  env.insert("PLUGIN_ROOT".to_string(), plugin_root_value.clone());
  // For OOTB compat with existing plugins that use this env var.
  env.insert("CLAUDE_PLUGIN_ROOT".to_string(), plugin_root_value);
  env.insert("PLUGIN_DATA".to_string(), plugin_data_root_value.clone());
  env.insert("CLAUDE_PLUGIN_DATA".to_string(), plugin_data_root_value);

• codex-rs/hooks/schema/generated/session-start.command.input.schema.json — wire-format input uses the same field names as Claude Code (session_id, cwd, hook_event_name, source, transcript_path, model, permission_mode). Our existing plugin/scripts/session-start.mjs already reads data.session_id and data.cwd.

Net result: our existing plugin/ directory already works as a Codex plugin with two small additions.

Changes

plugin/.codex-plugin/plugin.json (new)

Codex manifest pointing at the shared ./.mcp.json, ./skills/, and a Codex-specific ./hooks/hooks.codex.json. Same name + version as the Claude Code manifest (kebab-case agentmemory).

plugin/hooks/hooks.codex.json (new)

Codex-compatible hook subset. Drops SubagentStart, SubagentStop, SessionEnd, Notification, TaskCompleted, PostToolUseFailure (Claude-Code-only — Codex's input schemas don't define them). Keeps SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop. Adds Codex-specific statusMessage decorations on SessionStart + UserPromptSubmit. Script commands still reference ${CLAUDE_PLUGIN_ROOT} because Codex's engine injects it (cited above).

.codex-plugin/marketplace.json (new, at repo root)

git-subdir source pointing at ./plugin so codex plugin marketplace add rohitg00/agentmemory works the same way claude plugin marketplace add does. Mirrors the existing .claude-plugin/marketplace.json but in Codex's marketplace schema (name + interface.displayName + plugins[].source.{source, url, path, ref} + plugins[].policy).

README.md

• Codex CLI tile in the Works-with-every-agent grid now reads "6 hooks + MCP + skills" instead of "MCP server" to surface the upgraded surface.
• "Other agents" install table now distinguishes Codex CLI (MCP only) (existing codex mcp add path) from Codex CLI (full plugin) (new marketplace install).
• New Codex section in the "paste this prompt" block with the two-command install (server + codex plugin marketplace add + codex plugin install), the list of registered surfaces, and the env-var-injection note citing the Codex source line.

test/codex-plugin.test.ts (new — 6 cases)

1. .codex-plugin/plugin.json present with kebab-case name and required references.
2. Manifest version matches main package.json (future bumps won't drift the Codex side).
3. Every path referenced in the manifest resolves to a real file or directory on disk.
4. hooks.codex.json contains only events Codex supports — adding an unsupported event fails the test.
5. Every ${CLAUDE_PLUGIN_ROOT}/scripts/* command references an existing script (catches typos before users hit them).
6. .codex-plugin/marketplace.json declares git-subdir source with path: "./plugin".

Install (post-merge)

# 1. start the memory server
npx @agentmemory/agentmemory

# 2. register the marketplace + install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin install agentmemory

Registers @agentmemory/mcp MCP server + 6 lifecycle hooks + 4 skills (/recall, /remember, /session-history, /forget).

Test plan

• npm test — 874 / 874 (868 baseline + 6 new tests).
• npm run build — tsdown clean.
• Smoke install on a real Codex CLI: codex plugin marketplace add rohitg00/agentmemory + codex plugin install agentmemory should pick up the manifest and register MCP + hooks + skills.
• Once installed, verify a session triggers SessionStart and agentmemory writes a session row at http://localhost:3113.

Summary by CodeRabbit

• New Features

  • Added six lifecycle hooks for richer plugin event handling.
  • Added marketplace metadata to enable plugin installation via the Codex marketplace.

• Documentation

  • Updated integration guide to document Codex CLI/plugin platform, hooks, MCP servers, and skills.

• Tests

  • Added tests validating plugin packaging, hooks configuration, and marketplace entry.

• Chores

  • Plugin version bumped to 0.9.10.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	May 12, 2026 8:31pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 42c54643-a3a4-450e-bd0f-fa670494fb6b

📥 Commits

Reviewing files that changed from the base of the PR and between 59c1ea7 and 48ed0cb.

📒 Files selected for processing (2)

• plugin/.codex-plugin/plugin.json
• test/codex-plugin.test.ts

✅ Files skipped from review due to trivial changes (1)

• plugin/.codex-plugin/plugin.json

🚧 Files skipped from review as they are similar to previous changes (1)

• test/codex-plugin.test.ts

---

📝 Walkthrough

Walkthrough

The PR adds Codex plugin support: six lifecycle hooks, a marketplace registration file, a plugin manifest version bump, validation tests, and README updates documenting Codex CLI plugin-platform usage.

Changes

Codex Plugin Integration for agentmemory

Layer / File(s)	Summary
Plugin Hook Configuration and Manifest plugin/hooks/hooks.codex.json, plugin/.codex-plugin/plugin.json	Six lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) are registered as Node commands under ${CLAUDE_PLUGIN_ROOT}/scripts/. Plugin manifest version is bumped to 0.9.10.
Marketplace Plugin Registration .codex-plugin/marketplace.json	Registers agentmemory in the Codex marketplace using a git-subdir source (./plugin) with installation: AVAILABLE and authentication: ON_INSTALL, categorized as Memory.
Integration Documentation README.md	Updates agent compatibility matrix to "6 hooks + MCP + skills", adds a Codex CLI plugin-platform section with install steps and hook/skill listings, and splits Codex CLI rows into MCP-only and full-plugin modes.
Plugin Packaging Validation Tests test/codex-plugin.test.ts	Adds Vitest checks for .codex-plugin/plugin.json structure and version consistency with root package.json, verifies referenced skills/mcpServers/hooks paths and hook allowlist, ensures lifecycle hook script paths exist, and validates .codex-plugin/marketplace.json metadata.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

A rabbit hops through hooks so fine,
Each lifecycle event in perfect line,
Marketplace gates with auth in place,
Tests keep rhythm, docs embrace,
Plugin power, Codex grace! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(plugin): ship Codex plugin manifest + marketplace' clearly and concisely summarizes the main change: shipping Codex plugin support with manifest and marketplace files. It directly matches the core objectives and changes across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/codex-plugin-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

.codex-plugin/marketplace.json (1)

13-13: ⚡ Quick win

Pin source.ref to an immutable tag/commit for reproducible installs.

Using main on Line [13] can make plugin installs drift over time. Prefer a release tag (or commit SHA).

Proposed change

-        "ref": "main"
+        "ref": "v0.9.10"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.codex-plugin/marketplace.json at line 13, The manifest currently pins
source.ref to the mutable branch "main" in .codex-plugin/marketplace.json;
change the "ref" value used by the plugin's source (the source.ref / "ref" key)
to a fixed release tag or commit SHA (e.g., vX.Y.Z or a full commit hash) so
installs are reproducible and won't drift over time, and update any
documentation or release workflow that previously relied on "main" to reference
the chosen immutable tag or SHA.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugin/.codex-plugin/plugin.json`:
- Line 4: Update the "description" field in plugin.json to reflect the actual
registered hook count (replace "12 hooks" with "6 hooks" or remove the numeric
reference) so the manifest text matches the registered hooks; edit the value of
the "description" key in plugin.json to say "6 hooks, 51 MCP tools, 4 skills,
real-time viewer." (target the "description" property in plugin.json).

In `@test/codex-plugin.test.ts`:
- Around line 66-71: The test in test/codex-plugin.test.ts currently asserts
five lifecycle events on the events array (SessionStart, UserPromptSubmit,
PreToolUse, PostToolUse, Stop) but omits the required "PreCompact" event; update
the assertions that check the events collection (the existing
expect(events).toContain(...) lines) to also include
expect(events).toContain("PreCompact") so the test enforces the full six-hook
contract and will fail if PreCompact is removed.

---

Nitpick comments:
In @.codex-plugin/marketplace.json:
- Line 13: The manifest currently pins source.ref to the mutable branch "main"
in .codex-plugin/marketplace.json; change the "ref" value used by the plugin's
source (the source.ref / "ref" key) to a fixed release tag or commit SHA (e.g.,
vX.Y.Z or a full commit hash) so installs are reproducible and won't drift over
time, and update any documentation or release workflow that previously relied on
"main" to reference the chosen immutable tag or SHA.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a4d6ad5d-9c72-468c-a654-b32f17a0a884

📥 Commits

Reviewing files that changed from the base of the PR and between 292e9f6 and 59c1ea7.

📒 Files selected for processing (5)

• .codex-plugin/marketplace.json
• README.md
• plugin/.codex-plugin/plugin.json
• plugin/hooks/hooks.codex.json
• test/codex-plugin.test.ts