Codex Practical Kit

Codex Practical Kit installs a small working agreement for personal repositories. It favors direct code, clear documentation, and bounded review.

The managed AGENTS.md is a small skill router. Skill descriptions keep unrelated rules out of task context.

Included components

The kit installs the official Ponytail plugin. It also installs these task skills:

• simple-english
• neuroarxiv
• design-preflight
• delivery-lifecycle
• repository-knowledge
• research-first
• docs-maintainer
• roadmap-maintainer
• adversarial-review
• defect-diagnostic
• publication
• toolkit-maintainer
• plan-history

Each lifecycle skill contains its focused rule owners or links to the one skill that owns a shared rule.

Install

Install Node.js and a Codex CLI that supports codex plugin before running the installer.

On macOS or Linux, run:

./run-tests.sh
./install.sh
./doctor.sh

On Windows, install PowerShell 7 and Python 3.11 or later. Then run:

pwsh -File .\run-tests.ps1
pwsh -File .\install.ps1
pwsh -File .\doctor.ps1

The installer copies managed skills to ~/.agents/skills/. Do not edit installed copies. Codex manages Ponytail as a native plugin.

The installer writes a managed block in ~/.codex/AGENTS.md. It renders the absolute PLANS path and names installed skills.

The installer also writes $CODEX_HOME/PLANS.md and managed Codex hooks. Session Start announces the AGENTS router.

Check and apply managed component updates

On macOS or Linux, run this read-only command from the source checkout:

./check-updates.sh

On Windows, run:

pwsh -File .\check-updates.ps1

The command reads authoritative upstream sources for all managed runtime tools and bundled skills. It excludes optional tools and does not change installations, plugins, pins, or configuration.

The report compares toolkit pins with upstream identities. Native plugins have no toolkit pin. The report identifies their upstream release and Codex-owned lifecycle.

A complete report returns status 0, including when upstream differs. A request error returns status 2 and prints no partial report.

To apply all managed updates on macOS or Linux, run:

./apply-updates.sh

On Windows, run:

pwsh -File .\apply-updates.ps1

The apply command updates upstream.lock.json and the selected toolkit installation. It also refreshes each installed managed plugin by its marketplace name.

The command refuses an untracked source lock or an independent source edit. A prior successful apply remains valid when its source lock matches the selected installation. The command validates upstream data before mutation. It writes the source lock only after installation succeeds.

If an operation fails, the command stops and returns status 2. Correct the reported cause, then run the command again.

Global and repository instructions

The installer manages ~/.codex/AGENTS.md and $CODEX_HOME/PLANS.md. These files apply to every repository unless a nearer repository file overrides them.

A repository AGENTS.md can add or replace instructions for its directory tree. A repository .agent/PLANS.md replaces the global ExecPlan contract for that repository.

The installer does not update repository-owned instruction files. setup-repo only removes its obsolete managed RepoWise block from AGENTS.md.

Do not copy the global files into a repository.

A copied file stops receiving toolkit updates. It can conflict with newer rules.

If a repository needs an override, keep only the project-specific rule in the nearest AGENTS.md. Remove a generic .agent/PLANS.md copy to use the current global contract.

Keep a repository .agent/PLANS.md only when the project needs a different ExecPlan contract. You must maintain that file manually.

Prompt submission adds a Plan history reminder to Plan-mode prompts. Managed hooks save a completed Plan before the next prompt continues and at session lifecycle boundaries.

The edit hooks update <primary-checkout>/.codex/roadmap-view.md after an agent changes docs/roadmap.md. Keep this generated file open to follow worktree progress. Edit only docs/roadmap.md.

The Plan history skill captures pending decisions in .agent/plan-history/ and resumes bounded reads after context compaction. Current decisions stay in their authoritative documents or one maintained topic summary. Git retains retired records, so the working tree does not accumulate old captures or summary revisions.

An unrecorded destination skill is a conflict. The installer stops before it changes that directory.

Open a new Codex session after installation. Use /hooks to review and trust the toolkit and plugin commands.

Ponytail

The installer uses the official DietrichGebert/ponytail marketplace and installs ponytail@ponytail when absent. It preserves an existing official plugin's version, settings, and enabled or disabled state.

The complete plugin provides ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, and ponytail-help. Its lifecycle hooks control mode activation and persistence.

In Codex, use the skill picker or @ commands:

@ponytail full
@ponytail lite
@ponytail ultra
@ponytail off
@ponytail
@ponytail default off
@ponytail-review
@ponytail-help

Bare @ponytail reports the mode. @ponytail default off changes the default for later sessions. The upstream plugin controls lifecycle behavior. The toolkit does not select modes.

The upstream Codex instructions use @ commands; they do not promise a /ponytail slash-menu entry. See the official Ponytail commands.

Use Codex's plugin manager for enablement and removal. The apply command refreshes Ponytail but does not re-enable it.

Migration removes an old standalone Ponytail skill only when the toolkit manifest owns its destination and native installation succeeds. An unowned skill or conflicting marketplace source stops installation. Resolve that ownership conflict before retrying.

--codex-home selects the Codex home for installation and Doctor. Otherwise, the toolkit uses CODEX_HOME or ~/.codex. Use the same home for native plugin commands.

12UI

Install a compatible 12UI plugin through the Codex plugin directory if you want to use it. The toolkit does not install, update, or require 12UI.

The toolkit uses 12UI only for website projects. It does not use 12UI for native applications or other user-interface work.

The toolkit preserves separately installed 12UI plugins and does not copy or edit their skills.

The just-every/12ui-plugin Git package at version 0.2.108 includes a Claude Code pane. Its hook configuration contains modules, which Codex 0.160.0 rejects.

If an older toolkit installed that package, remove it and its marketplace registration:

codex plugin remove 12ui-design@12ui-plugin
codex plugin marketplace remove 12ui-plugin

These commands leave a separately installed 12ui-design@openai-curated-remote plugin intact. Later toolkit install and apply commands do not restore the Git package.

Rule owners

An applicable skill selects only the rules needed for its task:

• Rule ownership
• Coordination
• Supported model
• Scope boundaries
• Decision handoffs
• Repository knowledge
• Research First
• Delivery lifecycle
• Implementation modes
• Git isolation
• Plan history
• Full-set results
• Owner composition
• Scenario discrimination
• Review closure
• Publication
• Versioning

Skill-specific procedures remain in each skill. ExecPlan rules remain focused on executable plans.

RepoWise

The core install provides pinned uv and RepoWise when they are absent. It configures one required user-level RepoWise MCP server.

In a Git repository, the first MCP start creates the index and installs RepoWise's post-commit hook. Each MCP session catches up the index and watches working-tree edits without model calls. A completely empty folder becomes a Git repository. A non-empty, non-Git folder remains unchanged.

In a linked worktree, RepoWise keeps a separate index and uses Git's shared hook path. No extra setup is necessary.

On macOS or Linux, run eager setup when you need the index before the next Codex session:

./setup-repo.sh /path/to/repository
./doctor.sh --repo /path/to/repository

On Windows, run:

pwsh -File .\setup-repo.ps1 C:\path\to\repository
pwsh -File .\doctor.ps1 --repo C:\path\to\repository

See RepoWise notes for setup, refresh, opt-out, and trust-boundary details.

Uninstall

Uninstall removes toolkit-managed global integrations and copied skills. --purge also removes the toolkit data directory. Both retain native plugin resources, uv, RepoWise, and Plan history.

For complete removal, follow the ordered steps below. Keep the source checkout until the removal commands finish.

1. Remove repository integrations

Run remove-repo for each repository before core uninstall. Use a normal checkout; removal stops in linked worktrees because the Git hook is shared.

On macOS or Linux:

python3 kit.py remove-repo /path/to/repository --delete-index

On Windows:

python kit.py remove-repo C:\path\to\repository --delete-index

Omit --delete-index to keep that repository's .repowise index. Removal also clears the owned roadmap view and its Git exclusion. See RepoWise removal.

2. Remove toolkit files

On macOS or Linux:

./uninstall.sh --purge

On Windows:

pwsh -File .\uninstall.ps1 --purge

Omit --purge to keep the toolkit data directory. Use the installation's --install-root when it differs from the default.

3. Optionally remove Ponytail state

Close sessions that use Ponytail. Run any upstream cleanup script before native plugin removal, because removal deletes the plugin cache.

The upstream cleanup script removes shared Ponytail configuration and Claude state, including its status-line entry. Skip it if another client needs that state.

Use codex plugin list --marketplace ponytail --json to find the installed version. Replace VERSION below with that value.

On macOS or Linux:

cpk_codex_home="${CODEX_HOME:-$HOME/.codex}"
node "$cpk_codex_home/plugins/cache/ponytail/ponytail/VERSION/scripts/uninstall.js"
rm -rf -- "$cpk_codex_home/plugins/data/ponytail-ponytail"

On Windows:

$cpkCodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
node "$cpkCodexHome/plugins/cache/ponytail/ponytail/VERSION/scripts/uninstall.js"
Remove-Item -LiteralPath "$cpkCodexHome/plugins/data/ponytail-ponytail" -Recurse -Force -ErrorAction SilentlyContinue

If installation used --codex-home, set the variable to that directory instead. The upstream script does not remove Codex's plugin data; the second command removes it explicitly.

Shared configuration is $XDG_CONFIG_HOME/ponytail/config.json when XDG_CONFIG_HOME is set. Otherwise, it is ~/.config/ponytail/config.json on POSIX or %APPDATA%\ponytail\config.json on Windows. Remove any PONYTAIL_* environment settings from your shell profile if no client needs them.

4. Remove the native plugin and marketplace

Set CODEX_HOME to the selected directory with export CODEX_HOME="$cpk_codex_home" on POSIX or $env:CODEX_HOME = $cpkCodexHome on Windows. Then run:

codex plugin remove ponytail@ponytail
codex plugin marketplace remove ponytail

Keep the marketplace if you still use another plugin from it. Normal toolkit uninstall never runs these commands.

5. Optionally remove RepoWise and uv

If no repository or other tool needs RepoWise, run this command in either shell:

uv tool uninstall repowise

If no other tool needs uv, follow uv's uninstall procedure. Use uv cache dir, uv python dir, and uv tool dir to locate shared data before removing uv. uv cache clean clears its cache. Remove managed Python and tool directories only if you intend to remove those other installations too.

For uv installed in the default user bin directory, remove its executables on POSIX:

rm -f -- "$HOME/.local/bin/uv" "$HOME/.local/bin/uvx"

On Windows:

Remove-Item "$HOME/.local/bin/uv.exe", "$HOME/.local/bin/uvx.exe", "$HOME/.local/bin/uvw.exe" -Force -ErrorAction SilentlyContinue

For a custom or package-managed uv installation, use its actual location or package manager. The toolkit does not install Node.js or Codex.

6. Review retained files

Pending Plan history remains in repository .agent/plan-history/ directories and the $CODEX_HOME/plan-history/ fallback. Routine cleanup follows the delivery lifecycle. Retired committed records remain available through Git.

Repository-owned AGENTS.md, .agent/PLANS.md, roadmaps, and other project documentation remain. So do indexes and views in repositories that you did not remove in step 1. Core uninstall does not keep a repository list.

Remove the toolkit source checkout or downloaded archive only when you no longer need it. Leave unrelated Codex configuration and other plugins intact.

Contributing

Changes use draft pull requests and Codex review before readiness. The required toolkit-tests check runs when a PR becomes ready and after pushes to main. It runs the toolkit tests and verifies distribution checksums.

Protected main requires a pull request, passing CI, and resolved conversations. Codex review is a separate publication gate; no additional human approval is required. Follow the publication procedure.

Verification

On macOS or Linux, run:

./run-tests.sh
sh -n apply-updates.sh check-updates.sh doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh
git diff --check
sha256sum --check MANIFEST.sha256

On Windows, run:

pwsh -File .\run-tests.ps1
git diff --check

The test launchers validate syntax in memory and suppress Python bytecode output. They leave no build cache in the source tree.

MANIFEST.sha256 covers distributed files. Regenerate it after code and documentation are final.