Portable Codex subagents, automatic task routing, and reusable project guidance.
- Routes work automatically while keeping small tasks with the root agent.
- Includes four subagents for exploration, implementation, review, and quick edits.
- Provides a stack-neutral
AGENTS.mdstarting point. - Reconciles template updates semantically instead of replacing project guidance.
- Preserves user-owned configuration and modified managed files.
- Runs as a dependency-free Node.js CLI.
Install the CLI and global Codex assets:
pnpm add --global @iamdevlinph/codex-kit@latest codex-kit global install
Initialize a project from its root:
codex-kit project init
Restart Codex after global installation. Codex may ask you to trust the installed
hook at ${CODEX_HOME:-~/.codex}/codex-kit/routing-hook.js.
npm install --global @iamdevlinph/codex-kit@latest is also supported. For
one-off use, prefix commands with pnpm dlx @iamdevlinph/codex-kit@latest.
| Subagent | Routing | Model and effort | Purpose |
|---|---|---|---|
code-explorer | Automatic | gpt-5.6-terra, medium | Broad read-only discovery and contract tracing |
implementer | Automatic | gpt-5.6-luna, high | Large changes, debugging, migrations, and substantial tests |
code-reviewer | Automatic | gpt-5.6-sol, high | Feature structure and high-risk review |
quick-implementer | Manual | gpt-5.6-luna, medium | Small mechanical changes in one or two files |
The root orchestrator plans, routes, integrates, and validates. It handles clear
small changes directly and delegates broader discovery, implementation, or review
according to the installed SUBAGENT_ROUTING.md policy.
The canonical project guidance template provides reusable defaults for coding agents across these themes:
- instruction scope, local adaptation, and specialized project skills;
- minimal changes that follow the repository's existing architecture and conventions;
- repository discovery plus consistent, accessible user-facing design;
- semantic structure, readable naming, purposeful comments, and named domain constants;
- focused testing, conservative dependency management, and meaningful validation;
- durable planning, repository safety, and concise completion reporting.
project init installs the template as a reference, not as a replacement for
existing active guidance. During reconciliation, Codex merges only applicable
rules into the project's AGENTS.md and preserves its local organization and
adaptations.
| Action | Command |
|---|---|
| Show help | codex-kit -h or codex-kit --help |
| Print version | codex-kit -v or codex-kit --version |
| Install or update global assets | codex-kit global install |
| Configure model defaults | codex-kit global configure |
| Inspect global setup | codex-kit global list |
| Remove package-managed global files | codex-kit global uninstall |
| Initialize project guidance | codex-kit project init |
| Refresh the project template | codex-kit project sync |
| Check reconciliation status | codex-kit project status |
| Record completed reconciliation | codex-kit project mark-applied |
| Check for a package update | codex-kit version check |
Use codex-kit --help for exhaustive command details.
global install copies the agents, routing assets, hooks, and
codex-kit-reconcile-agents skill into ${CODEX_HOME:-~/.codex}. It adds only
codex-kit's hook handlers and preserves unrelated settings and hooks.
The default root configuration is:
model = "gpt-5.6-sol"model_reasoning_effort = "low"plan_mode_reasoning_effort = "high"Override it explicitly when needed:
codex-kit global configure \
--orchestrator gpt-5.6-sol \
--reasoning-effort low \
--plan-reasoning-effort high--model is an alias for --orchestrator. Before changing managed values,
codex-kit creates a timestamped config.toml backup and records the previous
values. global uninstall restores them without replacing unrelated later edits.
Modified managed files are preserved.
Use codex-kit global list to inspect model settings, routing and hook status,
the reconciliation skill, and installed agents. Use codex-kit global uninstall
to remove package-managed global files.
Run codex-kit project init after the project has enough code, dependencies,
configuration, and scripts for Codex to derive reliable guidance. It creates:
AGENTS.mdonly when missing; existing guidance is preserved;TEMPLATE_AGENTS.mdas the local template reference;.codex-kit-state.jsonfor reconciliation bookkeeping.
Initialization includes the first template sync. When the CLI prints an initialization or reconciliation prompt, copy the complete marked block into a Codex task opened at the project root.
After installing a newer package version, refresh the reference template:
codex-kit project syncproject sync never edits AGENTS.md or project skills. The reconciliation skill
compares the refreshed template with the project's guidance and merges only
applicable rules while preserving local organization and adaptations. If
TEMPLATE_AGENTS.md was modified locally, sync preserves it for review instead
of overwriting it.
After reconciliation and validation, Codex runs:
codex-kit project mark-appliedmark-applied only updates .codex-kit-state.json; it does not validate or
modify AGENTS.md. Use codex-kit project status to check whether the current
template still needs reconciliation.
--codex-home PATHselects a Codex home for global commands instead ofCODEX_HOMEor~/.codex.--cwd PATHselects a project directory for project commands instead of the current directory.--forceletsglobal install,global configure,project init, orproject syncreplace modified files they manage. Use it only when you intend to discard those local changes.
Examples:
codex-kit global install --codex-home /path/to/.codex
codex-kit project sync --cwd /path/to/project- Node.js 20 or newer
- Codex with custom subagent and lifecycle-hook support
The published package contains no credentials or runtime dependencies. Version
checks contact the public npm registry only when codex-kit version check runs.
See SECURITY.md for supported versions and private vulnerability reporting. This repository and package use the ISC License.