Skip to content

codex.md

Latest commit

 

History

History
122 lines (87 loc) · 3.24 KB

codex.md

File metadata and controls

122 lines (87 loc) · 3.24 KB
Raw

Install — Codex
Validated against Codex 0.146.0
Minimum supported 0.40.0
Plugin manifest .codex-plugin/plugin.json
Marketplace manifest .agents/plugins/marketplace.json
Official docs AGENTS.md · Config

Check your version:

codex --version

Codex resolves .agents/plugins/marketplace.json, not .codex-plugin/marketplace.json. That is the single most common reason a repo that "obviously has a Codex manifest" fails to register.

Prerequisites

  • Codex CLI 0.40.0 or newer, or the Codex app
  • Node.js ≥ 18 on your PATH

Method A — install from GitHub

codex plugin marketplace add TamirCohen28/headhunter
codex plugin add headhunter@headhunter

codex plugin marketplace add accepts an owner/repo shorthand, a full git URL, or a local path; append @<ref> to pin a branch or tag.

Confirm it registered:

codex plugin list --marketplace headhunter

Then restart Codex. You can also install interactively: open Codex, run /plugins, select the HeadHunter marketplace, and install headhunter.

Method B — AGENTS.md only (no plugin install)

AGENTS.md at the repo root is read automatically by Codex. Clone and run codex from the repo — you get HeadHunter's conventions and the CRM scripts with no registration step, but no packaged skills or commands.

git clone https://github.com/TamirCohen28/headhunter.git
cd headhunter
codex

.codex/config.toml in the repo carries the Codex-specific settings.

Method C — local development

codex plugin marketplace add /path/to/headhunter
codex plugin add headhunter@headhunter

Local-path registrations are idempotent — re-running updates rather than failing. Remove with codex plugin marketplace remove headhunter.

What you get

Component Codex
16 skills ✅
14 subagents ✅
Slash commands ✅
hooks/hooks.json ✅
Notion MCP (.mcp.json) ✅
AGENTS.md conventions ✅ auto-read

Integrations (all optional)

cp .env.example .env
node scripts/check-mcp-env.js

Restart Codex after setting env vars so the MCP server inherits them.

Verify

/headhunter:dashboard

Or host-independently:

node scripts/crud.js seed
node scripts/dashboard.js

MCP tools appear as mcp__notion__<tool>.

Update

codex plugin marketplace upgrade headhunter

Or git pull && make update for a clone. Restart Codex to pick up skill and hook changes.

Troubleshooting

Symptom Fix
marketplace root does not contain a supported manifest You're on a revision older than 1.5.0, before .agents/plugins/marketplace.json was added. Pull, or pin @main.
Plugin registers but skills don't load Restart Codex — the plugin surface is read at startup.
Notion tools missing NOTION_TOKEN unset. Run node scripts/check-mcp-env.js.
Commands find no data HEADHUNTER_DATA_DIR points somewhere empty, or you never seeded.

More: troubleshooting.md.