@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 router, preserves local organization and adaptations, and routes conditional knowledge through selectively read references. Repeatable procedures may use narrowly triggered project skills. When durable product context warrants it, PLANS.md becomes a concise index of global decisions and feature status, with substantial feature detail kept in selectively loaded feature plans.

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 the codex-kit-reconcile-agents and explicit-only codex-kit-audit-agents skills 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, both skills, 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 references or repeatable-procedure skills. It maintains PLANS.md as a durable product index and extracts substantial feature detail only when a reliable owner and route exist. Its final report includes actual UTF-8 byte measurements, moved ownership, reference and routing checks, preserved content, idempotence, and unresolved ambiguity. 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 review of project instructions, skill/workflow validation scope, and clearly redundant or speculative tests (monthly or biweekly is a reasonable optional cadence). The audit applies the same conservative AGENTS.md/PLANS.md ownership and routing optimization without synchronizing templates. It preserves justified regression and costly-risk coverage and reports ambiguous reductions. The CLI itself only validates the target directory and prints a marked prompt invoking the explicit-only $codex-kit-audit-agents skill; it does not contact npm, require project initialization, inspect or modify state, register the project, or write files. Codex may edit project guidance when the user runs that prompt. The existing audit workflow is the optimization entry point; there is no separate project optimize command.

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