@iamdevlinph/codex-kit

Portable Codex subagents, automatic task routing, and reusable project guidance.

• Routes work automatically while keeping small tasks with the root agent.
• Includes five managed subagents for planning, exploration, implementation, review, and quick edits.
• Provides a stack-neutral AGENTS.md starting 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.

Quick start

1. Install the CLI and global Codex assets:

   pnpm add --global @iamdevlinph/codex-kit@latest
   codex-kit global install

2. 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.

Included subagents

Subagent	Routing	Model and effort	Purpose
planner	Automatic in formal Plan mode	gpt-6-astra, low	Read-only repository analysis and implementation planning
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 Sol root orchestrator remains visible and owns conversation, requirement clarification, plan integration, implementation, and validation. In formal Plan mode, Astra Low performs substantive read-only planning and Sol presents the result. After the user selects Implement Plan, Sol implements the approved plan directly; supporting discovery and the required review may still be delegated. Outside Plan mode, the installed SUBAGENT_ROUTING.md policy routes work by task shape.

Project guidance included

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 a concise AGENTS.md, preserves local organization and adaptations, and routes repeatable task-specific detail through narrowly triggered project skills and selectively read references.

Both project init and project sync contact the public npm registry before writing project files. If the installed CLI is stale, or npm is unreachable or returns invalid metadata, the command fails without changing the project. Rerun with pnpm dlx @iamdevlinph/codex-kit@latest after the registry is available; stale builds print the exact command.

Commands

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
Show registered project statuses	codex-kit global projects
Register an existing project	codex-kit project register
Remove registered projects	codex-kit global projects remove
Remove package-managed global files	codex-kit global uninstall
Initialize project guidance	codex-kit project init
Refresh the project template	codex-kit project sync
Print an explicit instruction-audit prompt	codex-kit project audit
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.

Device setup

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 = "low"

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.

Use codex-kit global projects to see the existing offline reconciliation status for every project registered in that Codex home. Successful project init and project sync commands register the project's canonical path; project register adds an existing directory without reading or changing its files. Stale paths remain listed as unavailable. Use global projects remove in an interactive terminal to select registry records to remove; this never deletes project files. Global install or uninstall does not remove records.

Project workflow

Run codex-kit project init after the project has enough code, dependencies, configuration, and scripts for Codex to derive reliable guidance. It creates:

• AGENTS.md only when missing; existing guidance is preserved;
• TEMPLATE_AGENTS.md as the local template reference;
• .codex-kit-state.json for reconciliation bookkeeping.

The CLI continues to create only this scaffold, template reference, and state file set. During semantic reconciliation, Codex may create or maintain PLANS.md when repository evidence supports real durable decisions, roadmap/status, or resume-worthy completed milestones. Existing PLANS.md content is preserved and semantically merged; speculative history is never invented or backfilled.

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 upgrading the package, refresh the global installation to receive the enhanced reconciliation skill, then refresh the project reference template:

pnpm dlx @iamdevlinph/codex-kit@latest global install
codex-kit project sync

project sync never edits AGENTS.md, PLANS.md, or project skills. The command stages the packaged template and prints a short prompt invoking the reconciliation skill; Codex performs the semantic restructuring. The skill classifies existing and incoming guidance by task relevance, keeps universal rules and safeguards in AGENTS.md, and routes conditional detail through focused skills and references. It also moves durable roadmap or history into PLANS.md and reports any created or changed plan content. If TEMPLATE_AGENTS.md was modified locally, sync overwrites it with the packaged template. Keep always-on local rules in AGENTS.md and durable product context in PLANS.md; recover overwritten template edits through Git history when needed.

After reconciliation and validation, Codex runs:

codex-kit project mark-applied

mark-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.

Run codex-kit project audit whenever you want a standalone instruction review (monthly or biweekly is a reasonable optional cadence). It only validates the target directory and prints a marked prompt invoking the explicit-only $codex-kit-audit-agents skill. The CLI does not contact npm, require project initialization, inspect or modify state, register the project, or write files.

Options

• --codex-home PATH selects a Codex home for global commands instead of CODEX_HOME or ~/.codex.
• --cwd PATH selects a project directory for project commands instead of the current directory.
• --force lets global commands replace 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 register --cwd /path/to/project
codex-kit project sync --cwd /path/to/project
codex-kit project audit --cwd /path/to/project

Requirements

• Node.js 20 or newer
• Codex with custom subagent and lifecycle-hook support

The published package contains no credentials or runtime dependencies. Version checks and project initialization/synchronization contact the public npm registry; project operations fail closed before writing when that check cannot verify the latest release. The CLI never auto-installs or executes downloaded code.

Security and license

See SECURITY.md for supported versions and private vulnerability reporting. This repository and package use the ISC License.

References

• Codex custom subagents
• Codex AGENTS.md discovery
• Codex hooks