gm-codex for Codex

Installation

One-liner (recommended)

bun x gm-codex@latest

Installs the plugin to ~/.codex/plugins/gm-codex AND wires ~/.codex/config.toml so Codex auto-loads hooks, MCP servers, and skills on next start. No manual TOML editing required. Idempotent — re-run to upgrade.

What gets registered in config.toml

Inside a managed block fenced by # >>> gm-codex managed / # <<< gm-codex managed sentinels:

• [features].codex_hooks = true
• [[hooks.<Event>]] blocks for PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop — pointing at the bundled plugkit and node hook scripts under the install dir
• [mcp_servers.<id>] for any MCP servers declared in bundled .mcp.json
• [[skills.config]] entries for every bundled skill folder

Content outside the managed block is preserved verbatim. The installer never edits user-authored sections.

Repository Installation (Project-Specific)

cd /path/to/your/project
npm install gm-codex
npx gm-codex-install

Copies plugin assets into <project>/.codex/plugins/gm-codex and writes the same managed block into <project>/.codex/config.toml (project-trusted layer).

Uninstall

npx gm-codex-uninstall

Removes the plugin directory and strips the managed block from config.toml, leaving any user-authored content untouched.

Manual Installation

Windows and Unix:

git clone https://github.com/AnEntrypoint/gm-codex ~/.codex/plugins/gm-codex

Windows PowerShell:

git clone https://github.com/AnEntrypoint/gm-codex "\$env:APPDATA\codex\plugins\gm-codex"

Installed Layout

After install, the Codex plugin directory contains:

plugins/gm-codex/
├── .codex-plugin/plugin.json
├── .agents/plugins/marketplace.json
├── agents/
├── hooks/
├── scripts/
├── skills/
├── .mcp.json
├── gm.json
└── plugin.json

Runtime Behavior

• Hooks call bin/plugkit through ${CODEX_PLUGIN_ROOT}.
• plugkit binaries are bundled in bin/ for every supported platform; the plugin ships ready-to-run.
• plugkit uses:
  • rs-exec for execution/runtime process management
  • rs-codeinsight for AST/project analysis
  • rs-search for search/MCP search behavior

Environment

• CODEX_PLUGIN_ROOT: plugin root used by hooks
• CODEX_PROJECT_DIR: project root for hook/runtime operations

Features

• Stateful agent policy via agents/gm.md
• Hook enforcement for session lifecycle
• Rust-backed execution and background task control
• Rust-backed code insight and search integrations
• Generated Codex plugin metadata and marketplace manifests

Update Procedures

User-wide install

bun x gm-codex@latest

Project-level install

npm update gm-codex
npx gm-codex-install

Troubleshooting

Hooks run but plugkit is missing

• Reinstall the plugin; plugkit binaries are shipped in bin/ via CI and should not need to be downloaded.

Hook path issues

• Verify CODEX_PLUGIN_ROOT points to the installed plugin root.
• Confirm hooks/hooks.json commands resolve to ${CODEX_PLUGIN_ROOT}/bin/plugkit.

Plugin loaded but behavior is incomplete

• Check skills/, scripts/, and agents/ were copied by installer.
• Re-run installer and restart Codex.

License

MIT