codex-starterkit

Bootstrap package for the OpenAI Codex Agent — installs curated skills, custom agents, prompt aliases, hooks, and MCP tools using Codex's supported extension surfaces.

npx codex-starterkit

The global installer also provisions checksum-verified, pinned rg and srcwalk binaries in a user-scoped bin directory and discovers a working grep (including Git for Windows locations outside PATH). Then, inside any project, invoke $setup (recommended) or /prompts:setup. The setup agent repairs the host PATH/system grep when needed, live-probes the complete toolchain, materializes the .codex/ overlay, and initializes hybrid memory. Codex reserves root slash commands; plugins cannot register a custom /setup command.

What you get

Three plugins are installed globally under ~/.codex via the Codex plugin marketplace system. Custom agents and compatibility prompts are installed in their native Codex home directories:

| Plugin | Contents | |---|---| | core | Curated skills + workflow runbooks exposed as native skills + project templates | | mcp-tools | MCP server (24 tools: search, hybrid memory, temporal graph, sessions, srcwalk, skill-scoped MCP bridge) | | hooks | 7 runtime hooks (guard, rtk, prompt router, intent→skill mapping, memory capture) |

The installer also writes custom-agent TOML files to ~/.codex/agents/ and managed compatibility prompts to ~/.codex/prompts/.

The starterkit registers only codex-starterkit-tools as its global MCP. Context7, Codebase-Memory, WebClaw, and Obsidian are reached through the skill_mcp broker only for a request and closed afterward; local integrations are provisioned and health-checked first. During upgrades, the installer removes only proven starterkit-owned legacy entries after the replacement passes. User-managed, skipped, or unhealthy entries are preserved and reported as conflicts. The bridge discovers 20 MCP configurations shipped with individual skills, supports stdio and Streamable HTTP, expands environment placeholders, and avoids duplicating specialized servers in every Codex task.

Skills (139)

Covers the full development lifecycle: plan → build → verify → ship.

| Domain | Key skills | |---|---| | Planning | planning-and-task-breakdown, prd, prd-task, spec-driven-development | | Building | incremental-implementation, frontend-design, react-best-practices, api-and-interface-design | | Verifying | debugging-and-error-recovery, code-review-and-quality, verification-gates, testing-anti-patterns | | Shipping | shipping-and-launch, vercel-deploy-claimable, ci-cd-and-automation, gh-fix-ci | | UI/UX | ui-ux-pro-max, mockup-to-code, web-design-guidelines, accessibility-audit, anti-ai-slop | | Research | deep-research, opensrc, source-code-research, agent-reach | | Security | security-and-hardening, skillspector, security-threat-model, defense-in-depth | | Platform | cloudflare, supabase, swift-concurrency, swiftui-expert-skill, v0, v1-run | | Advanced | desktop-commander, pencil, code-cleanup, deep-module-design, development-lifecycle |

Workflows (33)

All workflow runbooks are native skills and remain routable via the prompt auto-router. Invoke them explicitly with $research, $plan, $create, $ship, $setup, and so on. Deprecated compatibility aliases are available as /prompts:research, /prompts:plan, /prompts:setup, etc.

Agents (11)

Codex custom agents installed as standalone TOML profiles under ~/.codex/agents/:

| Agent | Role | |---|---| | build | Primary developer — full codebase access | | plan | Architecture & decomposition | | explore | Read-only codebase search | | scout | External research (docs, packages, patterns) | | review | Read-only code review & security audit | | general | Small, well-defined implementation tasks | | runner | Shell/git/filesystem operations | | painter | Image generation & editing | | vision | Visual analysis (UI/UX, accessibility, design) | | god | GODMODE jailbreak orchestrator (authorized security testing only) | | prompt-curator | Prompt-library wiki maintenance |

How it works

Hybrid install (copy + Codex CLI)

codex-starterkit install runs in three phases:

1. Provision — discovers grep and installs pinned official rg/srcwalk release binaries at user scope after SHA-256 verification. The bundled scanner remains a degraded fallback, not the complete environment.
2. Package — copies the baseline into a staging marketplace dir at ~/.codex/.codex-starterkit-staging/ with the Codex plugin layout (.codex-plugin/plugin.json, skills/, hooks/) plus a .agents/plugins/marketplace.json manifest. Command runbooks are converted to native skills.
3. Register — calls the Codex CLI to register plugins and the shared broker:
   • codex plugin marketplace add <stagingDir>
   • codex plugin add core@codex-starterkit (plus mcp-tools and hooks)
   • codex mcp add codex-starterkit-tools -- <absolute-node> <server.js> (MCP tools server)
   • passes verified Codebase-Memory/WebClaw binary paths into the broker environment
   • removes proven starterkit-owned legacy entries only after their on-demand replacements pass; user-managed or unhealthy entries are preserved

If the Codex CLI is not on PATH, the starterkit still packages the staging dir and prints the manual commands to run. Use --require-codex to fail instead.

After an upgrade removes starterkit-owned legacy MCP entries, fully quit and reopen Codex Desktop once. The running app server and already-open tasks retain their pre-migration MCP process set until that restart, even though codex mcp list already shows the new configuration on disk.

Codex CLI detection

The installer finds codex (or codex.exe on Windows) in this order:

1. CODEX_CLI_PATH env var
2. codex on PATH
3. Windows: %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe
4. CODEX_CLI_PATH from ~/.codex/config.toml (mcp_servers.node_repl.env)

Prompt routing (automatic)

Every user prompt goes through the prompt-leverage hook:

1. Execution framing — adds a 5-step checklist before acting
2. Auto-router — detects intent and injects the matching command runbook
3. Intent→Skill mapping — for free-form prompts, loads the right skills automatically
4. Prompt library — "act as ..." patterns trigger wiki search for playbooks

Codex requires explicit trust for non-managed hooks. After install, start a new task, review the hook prompt (or open /hooks), and trust the audited starterkit hooks. Until then Codex intentionally skips prompt routing, guard, RTK, and memory hooks.

Hooks (runtime)

| Hook | Trigger | What it does | |---|---|---| | guard | Before bash commands | Blocks dangerous operations (rm -rf, sudo, db:reset) | | rtk | Before shell/exec commands | Intercepts commands and compresses supported noisy output | | prompt-leverage | Every user prompt | Execution framing + auto-routing + intent mapping | | memory-inject | Every user prompt | Injects relevant past observations from memory DB | | memory-capture | After tool use | Captures high-value edits, verification/mutation commands, and failures; skips reads and coalesces repeats | | session-summary-track | After tool use | Tracks compact session activity | | session-summary-persist | Stop | Persists session state across turns |

Hybrid project memory

$setup initializes .codex/memory.db through memory-admin sync-files, then proves it with memory-admin status and memory-admin lint. This creates or migrates the observation, Markdown index, timeline, and temporal graph schemas without pruning, deduping, invalidating, or deleting project knowledge. Absence of the database after a successful $setup is a failed memory initialization.

| Layer | Storage | Purpose | |---|---|---| | Curated memory | .codex/memory/**/*.md | Human-readable source of truth; searchable directly and through a rebuildable FTS index | | Observations | .codex/memory.db | Deduplicated events with provenance, first/last seen, occurrence count, timeline, lint, retention, and vacuum | | Entity graph | entity_triples in the same project DB | Temporal subject-predicate-object facts with confidence and observation provenance | | Code graph | persistent Codebase-Memory index, runtime on demand | Structural code relationships, call paths, architecture, dead code; deliberately separate from decisional memory |

The bundled memory surface is observation, memory-search, memory-get, memory-read, memory-update, memory-timeline, memory-admin, and memory-graph-add/query/invalidate. Admin dedupe and prune default to dry-run, and manual observations are protected from pruning unless explicitly allowed.

Quick reference

# Install globally
npx codex-starterkit

# Sandbox test (doesn't touch real ~/.codex)
npx codex-starterkit --sandbox --skip-codebase-memory --skip-webclaw --skip-rtk --skip-context7

# Inside a project — materialize the .codex/ overlay
$setup
# Compatibility prompt form: /prompts:setup

# Skip optional provisioning and health probes for this install pass
npx codex-starterkit --skip-codebase-memory --skip-webclaw --skip-context7

# Explicitly skip preferred grep/rg/srcwalk provisioning (bundled fallback only)
npx codex-starterkit --skip-navigation-tools

# Uninstall (removes plugins, marketplace, and the starterkit broker via Codex CLI)
npx codex-starterkit uninstall

Prerequisites

• Node.js ≥ 22.5 — memory hooks and MCP tools use the built-in node:sqlite module introduced in Node 22.5.
• OpenAI Codex CLI — install the Codex desktop app or run npm install --global @openai/codex. The installer supports the NPM codex.cmd wrapper on Windows and auto-detects codex on PATH, %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe, or CODEX_CLI_PATH. If the CLI is missing, the installer still packages the staging marketplace and prints the manual registration commands.
• Git — for cloning and version control.
• Navigation toolchain — a complete setup has executable grep, rg, and srcwalk. The installer auto-discovers Git for Windows GNU grep and installs pinned ripgrep 15.2.0 plus srcwalk 1.1.0 release binaries with SHA-256 verification. $setup repairs OS packages/PATH and functionally probes all three. Skip only for constrained fallback environments with --skip-navigation-tools; enforce completeness with --require-navigation-tools.
• NPM account — publishing to NPM requires a free NPM account. Set NPM_TOKEN in your environment or CI secrets.

Optional integrations (auto-installed by default)

• Codebase-Memory — code-intelligence MCP server (call graphs, Cypher, dead-code, 158 languages). Auto-downloaded and called on demand through skill_mcp. Skip provisioning with --skip-codebase-memory.
• WebClaw — URL extraction / browser-agent MCP server. Auto-downloaded and called on demand through skill_mcp. Skip provisioning with --skip-webclaw.
• Context7 — official remote MCP endpoint for current library documentation, called on demand through skill_mcp. Skip its install-time health probe with --skip-context7.
• Skill-scoped MCPs — 20 optional integrations (including Context7, Codebase-Memory, WebClaw, Tilth, Supabase, Playwright, Figma, Stitch, and v0) start/connect only when skill_mcp is called. Credentialed integrations fail with the exact missing environment variable instead of breaking Codex startup.
• RTK — command-output compression for token efficiency. Auto-downloaded and wired through the hooks plugin. Skip with --skip-rtk.

RTK does not prefix every arbitrary CLI with rtk. The hook intercepts shell/exec commands, immediately passes safety exclusions through raw, sends the rest through rtk rewrite, and uses a verified fallback wrapper for known test runners.

For developers

Rebuild MCP tools

The baseline/mcp-tools/dist/mcp/server.js bundle is committed and ready to use. Rebuild it from TypeScript source only when you change baseline/mcp-tools/src/:

cd baseline/mcp-tools
npm install && npm run build

This produces a single self-contained dist/mcp/server.js (esbuild bundle) that the Codex plugin host runs with node — no node_modules needed at runtime.

Verify the published artifact

npm run test:package:smoke    # Pack + run the bundled server from an isolated npx cache
npm run test:package:runtime  # Also install/exercise navigation binaries, RTK, Context7, Codebase-Memory, WebClaw, and hooks
npm run test:package          # Full release gate; additionally requires and verifies the real Codex CLI

These checks create a temporary HOME/CODEX_HOME, confirm that no integration binary exists before installation, execute the generated .tgz through npx, and verify the resulting plugin/MCP state. Successful runs remove the temporary home; failed runs retain it for diagnosis.

Cut a release

# 1. Bump version in both files:
#    package.json (version)
#    src/constants.mjs (PLUGIN_VERSION)
# 2. Commit + push
# 3. Tag + push tag
git tag vX.Y.Z
git push origin vX.Y.Z

The release GitHub Action runs unit tests and the isolated packed-install gate on Linux and Windows, rebuilds MCP tools, verifies that the rebuilt bundle matches the tested bundle, and publishes to NPM. The tag must match package.json version.

Publish to NPM (public)

This package uses an unscoped name (codex-starterkit) and publishes as a public package on NPM. The CI workflow uses --access public explicitly.

Important: Do NOT set "private": true in package.json — NPM rejects publishing any package with that flag (error EPRIVATE).

One-time setup:

# Log in to your NPM account
npm login

# Verify you are authenticated
npm whoami

Publish manually:

# Rebuild the mcp-tools bundle so the published dist is always fresh
cd baseline/mcp-tools && npm install --ignore-scripts && npm run build && cd ../..

# Publish as a public unscoped package
npm publish --access public

Publish via CI (recommended):

1. Add NPM_TOKEN to the repo secrets: Settings → Secrets and variables → Actions → Repository secrets (NOT Variables).
2. Push a matching version tag, for example: git tag v0.1.9 && git push origin v0.1.9
3. The release workflow runs tests on Linux + Windows, rebuilds the mcp-tools bundle, and publishes to NPM using NPM_TOKEN with --access public.

Install from the public registry:

npm install codex-starterkit
npx codex-starterkit

Troubleshooting

Codex CLI not found

The installer searches for codex in this order:

1. CODEX_CLI_PATH env var (set it to the absolute path of your codex.exe)
2. codex on PATH
3. Windows: %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe (auto-scan)
4. CODEX_CLI_PATH from ~/.codex/config.toml (mcp_servers.node_repl.env)

If it cannot find the CLI, the installer still packages the staging marketplace at ~/.codex/.codex-starterkit-staging/ and prints the manual commands. Use --require-codex to fail instead of warning.

Manual registration (if Codex CLI is missing during install)

codex plugin marketplace add "~/.codex/.codex-starterkit-staging"
codex plugin add core@codex-starterkit
codex plugin add mcp-tools@codex-starterkit
codex plugin add hooks@codex-starterkit
codex mcp add codex-starterkit-tools -- node "~/.codex/.codex-starterkit-staging/plugins/mcp-tools/dist/mcp/server.js"
codex mcp get context7 --json
codex mcp get codebase-memory-mcp --json
codex mcp get webclaw --json

Prefer rerunning the installer after Codex becomes available because it performs ownership checks, bridge probes, post-checks, and rollback. Add --env CODEBASE_MEMORY_MCP_PATH="<verified-absolute-file>", --env WEBCLAW_MCP_PATH="<verified-absolute-file>", or --env OBSIDIAN_VAULT_PATH="<verified-absolute-directory>" only when that local runtime exists. Never remove a same-name MCP from codex mcp get output by name alone. Remove it only when it is confirmed starterkit-owned and the matching skill_mcp replacement has passed.

Uninstall

codex-starterkit uninstall
# or manually:
codex plugin remove hooks@codex-starterkit
codex plugin remove mcp-tools@codex-starterkit
codex plugin remove core@codex-starterkit
codex plugin marketplace remove codex-starterkit
codex mcp remove codex-starterkit-tools

Uninstall intentionally preserves specialized same-name registrations because they may be user-managed.

Sandbox test (safe — never touches real ~/.codex)

node ./bin/codex-starterkit.mjs --sandbox --skip-codebase-memory --skip-webclaw --skip-rtk --skip-context7

This stages the marketplace into <repo>/.sandbox/.codex/ instead of the real ~/.codex, and skips all auto-installs.

Navigation environment incomplete

The installer records grep, rg, and srcwalk paths, versions, functional health, binariesReady, and pathReady under codex-starterkit-state/starterkit-state.json. binariesReady means all three binaries execute by verified absolute paths. complete becomes true only when bare commands also pass their functional probes on the current PATH. rg and srcwalk are downloaded only from their official GitHub releases and verified against pinned SHA-256 digests. On Windows, grep.exe may live under Git/usr/bin without being on shell PATH; $setup safely adds verified directories to the user environment and re-probes bare commands. A bundled srcwalk_*/csearch result or absolute-path-only state keeps work possible during repair but is reported as incomplete, not healthy.

Architecture

codex-starterkit is a self-contained bootstrap package for the OpenAI Codex Agent. It packages native skills, custom agent profiles, prompt aliases, hooks, and MCP tools, then registers supported plugin surfaces via the Codex CLI.

How it fits together

~/.codex/                                   ← Codex home (CODEX_HOME)
├── config.toml                              ← Codex runtime config (TOML, managed by codex CLI)
├── .codex-starterkit-staging/               ← staging marketplace (written by the installer)
│   ├── .agents/plugins/marketplace.json     ← Codex marketplace manifest
│   └── plugins/
│       ├── core/         (native skills + workflow skills + templates/workflows/plans/...)
│       ├── mcp-tools/    (prebuilt MCP server, registered via Codex CLI)
│       └── hooks/        (guard, rtk, prompt routing, memory capture/inject)
├── agents/                                   ← starterkit-*.toml custom agent profiles
├── prompts/                                  ← managed /prompts:<name> compatibility aliases
├── codex-starterkit-state/                  ← install logs, backups, integration state
├── ../.local/bin or platform user bin        ← pinned rg/srcwalk binaries (SHA-256 verified)
└── skills/  rules/  memories/  ...          ← existing Codex dirs (untouched)

Key design decisions

| Aspect | Choice | Why | |---|---|---| | Config format | ~/.codex/config.toml (TOML) | Codex's native config — registered via codex CLI, never edited by hand | | Plugin manifest | .codex-plugin/plugin.json with interface block | Codex plugin format — declares supported skills and hooks surfaces | | Marketplace | .agents/plugins/marketplace.json | Codex marketplace format — registered via codex plugin marketplace add | | MCP servers | One global broker plus per-skill mcp.json | Specialized MCPs connect only through skill_mcp when requested | | Model providers | None registered | Codex ships with an OpenAI provider by default; the starterkit does not add custom providers | | Install strategy | Hybrid (copy + CLI) | Packages the staging dir, then calls codex plugin marketplace add + codex plugin add to register and enable | | Sandbox | CODEX_HOME=<repo>/.sandbox/.codex | Safe testing without touching the real ~/.codex |

Registration flow (install)

1. Provision navigation — discover grep; install and verify pinned rg/srcwalk release binaries
2. Package — copy the baseline into a staging marketplace dir with the Codex plugin layout
3. Register marketplace — codex plugin marketplace add <stagingDir>
4. Enable plugins — codex plugin add core@codex-starterkit, mcp-tools, and hooks
5. Probe MCP servers — require successful initialize + tools/list for the broker, Context7 endpoint, and provisioned local integrations
6. Register the broker — add only codex-starterkit-tools, pass verified local binary paths as environment, and remove only starterkit-owned legacy entries whose replacements passed
7. Wire hooks — write rtk.json, then ask the user to review/trust the plugin hooks through Codex's hook trust flow

If the Codex CLI is absent, the installer still packages the staging dir and prints the manual commands.

What the installer never touches

• MCP/plugin entries are modified through the Codex CLI. ensureCodexDefaults() is the narrow exception: it backs up config.toml and only adds missing model/provider/feature defaults because Codex has no config set command.
• Existing Codex plugins, skills, rules, and memories are preserved.
• The OpenAI provider and model settings in config.toml are left as-is.

See AGENTS.md for the shipped global rules and the full Intent→Skill mapping table.