Codex Base combines adapted community skills with our team's workflow and environment integration for Codex. It aims to reduce repeated context gathering, drift from settled decisions, and rework caused by over-engineering during long coding tasks.
Warning
This is the agent harness—the instructions, tools, and workflows around Codex—that my team uses and shares publicly. It is not a product aimed at most users. AI and Codex evolve quickly; this repository will remain unstable and may require substantial additional configuration.
We share it so others can help improve the engineering behind the harness. We believe working together can help our teams adopt useful advances sooner, improve productivity, and build more advanced products. We warmly welcome valuable issues and PRs; please take time to understand the project's intent and respect its documented conventions.
Quick start · First workflow · Updates · Configuration reference
Our Improve workflow builds on the audit and planning foundations from shadcn's Improve. We adapt selected skills from Matt Pocock for requirements clarification, debugging, testing, design, and agent guidance. We also adapt and integrate Ponytail for over-engineering review, audits, and debt tracking; stop-slop for prose editing; and the Playwright CLI skill for browser work.
Our work focuses on adapting these foundations to Codex, extending and connecting the planning, execution, and review workflow, adding documentation and bounded public-X research support, and maintaining the plugin and Nix/Home Manager environment. In this setup:
- Formal planning resolves material choices and produces a complete plan in chat. An authorized implementation phase can then persist it and delegate bounded work.
- Implementation consults current documentation; an isolated executor verifies and simplifies each changing step. Reviews and checkpoints identify the candidate they cover so work can be resumed and assessed.
- Shared skills cover documentation lookup, debugging, testing, design, and prose review. The capability catalog lists their triggers and installation requirements.
- ADHX reads relevant public X post URLs supplied by users or found through bounded web research; it is not an X search service, and long-form Article content may be incomplete.
The credits and licenses describe the upstream contributions and our adaptations; source records identify the included paths and pinned revisions.
For bounded implementation work, the approved plan selects economy (Luna/low), standard (Sol/medium), or deep (Sol/xhigh). The coordinator does not switch models after launch; see executor routing.
Planning and review also consume usage, so small, clear edits are usually better handled directly. Codex Base does not promise fewer tokens or lower cost for every task.
Note
If setup feels daunting but you want a full Nix / Home Manager environment similar to mine (the repository owner's), hand this README to Codex and ask it to help you set things up :)
Use Codex CLI or Codex in the ChatGPT desktop app; the IDE extension does not support plugins. This repository supports Codex workflows, not general Chat or Work conversations. See the official plugin guide.
Install and configure Codex Base on the machine that executes the task:
| Client | Execution host and Codex runtime |
|---|---|
| Codex CLI | The machine running codex; it uses the CLI installation on PATH. |
| Local desktop chat | The desktop machine; the app uses its bundled Codex runtime, which can differ from the system CLI. |
| Desktop over SSH | The selected remote host; the desktop client starts Codex App Server there. The remote login shell must find codex on PATH. |
For SSH setup, follow the official connection guide. Installing on the desktop client alone does not configure the remote host.
Linux execution needs Bash, GNU coreutils, Git, GNU sed, jq, and Codex on PATH. Portable Improve execution additionally needs Python 3.11 or newer and Worktrunk (wt); the Nix closure supplies Python, Git, Codex, and Worktrunk. Windows users can use portable skills from a compatible Codex CLI environment; the complete Improve runners and Nix/Home Manager environment require Linux, such as WSL2. Keep WSL repositories in its Linux filesystem (for example ~/src, not /mnt/c). Native Windows Improve runners and Windows CI are not provided here.
Choose the plugin to add the portable workflow to an existing Codex setup, or Home Manager to manage the full Linux environment.
| Provided or configured | Codex plugin | Nix / Home Manager full environment |
|---|---|---|
| Engineering skills | Namespaced, such as $codex-base:improve |
Unnamespaced, such as $improve |
| Improve CLI | python3 -B skills/improve/scripts/codex-improve with host dependencies |
Packaged codex-improve plus wt |
| Global guidance and GitHub MCP | No | Yes |
| Mintlify / Context7 documentation services | Anonymous HTTP defaults | HTTP Mintlify, local anonymous Context7, and optional per-user authentication |
| Codex, Code Mode Host, Node, Playwright CLI | No | Default Codex package with Code Mode Host, plus pinned Node and Playwright CLI; Codex package can be replaced |
Run on the execution host:
codex plugin marketplace add https://github.com/bioinformatist/codex-base
codex plugin add codex-base@bioinformatist-codex
codex plugin list --marketplace bioinformatist-codexThe output should show codex-base@bioinformatist-codex installed and enabled. The plugin does not install Codex, host packages, or global configuration.
Add this input to your existing flake.nix:
inputs.codex-base = {
url = "github:bioinformatist/codex-base";
inputs.nixpkgs.follows = "nixpkgs";
};In your Home Manager module, with inputs in scope:
{
imports = [ inputs.codex-base.homeManagerModules.default ];
programs.codexBase.enable = true;
}Activate the consuming Home Manager or NixOS configuration using your usual deployment procedure. This route provides the skills, runners, and managed configuration; a separate plugin installation is unnecessary.
The full Nix / Home Manager environment currently pins Codex 0.158.0 and Code Mode Host. This describes the default package; to supply another CLI package, see Codex package selection.
Home Manager supplies the runtime defaults. For a plugin-only installation, follow Native Codex configuration to request the planning capabilities and configure Code Mode if its companion host is available. Then follow Reload after an update.
Both installations provide Mintlify and Context7 for public documentation lookup. The plugin uses anonymous Mintlify Index and Context7 HTTP endpoints; Home Manager uses HTTP Mintlify and local Context7. Start with these anonymous defaults. Optional user-owned authentication and its verification are covered in Context7 authentication. Native Codex configuration overrides same-name plugin defaults. Send only focused public lookup terms to these third-party services, never secrets, private code, full prompts, or non-public internal content.
On the execution host, check the registered services:
codex mcp list --jsonA plugin-only installation with no native overrides should list mintlify_index and context7, with no context7_auth. Registration does not prove that a service or credential works.
Start a new Codex task and try a harmless skill invocation:
Use $codex-base:stop-slop to tighten this sentence without changing its facts: "At this point in time, the test suite contains three tests."
With Home Manager, use $stop-slop without the plugin prefix. This checks skill discovery; formal planning has the additional requirements below.
These instructions apply to both installation methods. A Codex task means one chat: a CLI conversation or, on desktop, a Codex chat under a project in the app sidebar. Entering Plan Mode or invoking $improve within it does not create another task.
The managed default is gpt-6-sol with medium reasoning; Plan Mode uses high. Formal Improve planning requires live native context management and structured questions. Check the actual tools and server capability in the current session. A model name alone does not establish either capability. Astra is an explicit choice for difficult planning, not a prerequisite or automatic escalation. See model selection.
Before formal planning, verify the live tools: configured true values and a Plan Mode label do not prove that either capability is live. Selecting Astra does not prove that native context management is live either. If it is absent, do not repeatedly restart, rebuild, or toggle the same setting; use a session where the service actually exposes it, or ask the user to grant a temporary per-plan waiver. Structured questions and the other planning requirements still apply.
Enter built-in Plan Mode with /plan or Shift+Tab in the CLI; the desktop composer also supports /plan. Then invoke Improve using the name for your installation:
| Installation | Prompt |
|---|---|
| Plugin | $codex-base:improve plan <request> |
| Home Manager | $improve plan <request> |
Improve discovers facts, asks about material unresolved choices, and presents the complete replacement plan in chat. Planning creates no plan, questionnaire, handoff, or temporary files. Once you accept the plan, authorize implementation in Default Mode; that later writable phase can persist the plan and execute it.
Default Mode implementation, audits, and routine lifecycle bookkeeping do not require a new formal-planning workflow. Use individual skills directly when a task does not need formal planning; see the capability catalog.
First update the installed plugin or activate the consuming Nix configuration; restarting alone does not fetch new files. Wait for affected tasks to finish, then reload the runtime that executes them:
| Client | Reload procedure |
|---|---|
| CLI | Exit and relaunch Codex. |
| Local desktop | Fully quit and reopen the ChatGPT desktop app, then start a new Codex chat. Closing only the window does not quit the app. Update the app separately when needed: its bundled Codex can differ from the system CLI. |
| Desktop over SSH | After updating the remote installation, restart the host's backend through Settings → Connections → SSH, following the official connection guide, then start a new chat. |
For SSH, verify the running remote Codex App Server; codex --version only reports a newly invoked binary. Restarting the desktop client or creating a new chat does not prove that remote process restarted. Resuming an existing chat preserves its history.