Codex

Vendor: OpenAI Install name: codex Status: Beta Native config: ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.codex/hooks/, ~/.codex/agents/*.toml, and ~/.agents/skills/

InstallationCopy Anchor Link

apothem install --harness codex

The adapter installs Codex-native instructions and hooks, converts Apothem agents to Codex TOML agents, and wraps reusable command prompts as Codex skills.

Files written: ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.codex/hooks/, ~/.codex/agents/*.toml, ~/.agents/skills/*/SKILL.md, ~/.agents/skills/*/agents/openai.yaml for user-invoked skills, and support files under ~/.config/apothem/{rules,templates}/.

Hook interpreter. Before it writes anything, the install resolves a CPython 3.10+ interpreter. On Windows, each hook's commandWindows entry in hooks.json runs that interpreter's absolute path instead of the py -3 launcher; the POSIX command entries keep python3. Re-run apothem update --harness codex after the interpreter moves or is removed. If no CPython 3.10+ is found, the install stops before it writes any file.

The Apothem block in AGENTS.md ends with an Apothem support files section that names the absolute directory each repository-style citation in the installed skills and rules resolves against: rules/<name>.md and templates/... under ~/.config/apothem/, and hooks/... under ~/.codex/hooks/. The Codex install ships no schemas/ or conformity/ tree, so the section lists neither.

User-invoked skills. Codex ignores the disable-model-invocation key. For every skill or command whose source sets disable-model-invocation: true, the adapter writes agents/openai.yaml beside its SKILL.md with policy.allow_implicit_invocation: false, so Codex does not pick the skill on its own; you can still run it explicitly with $skill-name. See the Codex skills documentation.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared cohorts and installs each into the correct Codex surface: instructions to AGENTS.md, hooks to hooks.json and hooks/, agents to TOML, skills to ~/.agents/skills/, and non-native Markdown rules/templates to ~/.config/apothem/ as support material.

Each converted helper sets name, description, and developer_instructions, which carries the helper's body. No model or reasoning effort is set, so each helper inherits the session's choices. Codex has no per-helper tool list or turn limit, so a helper's tools and maxTurns do not carry over.

The read-only helpers (see the agents reference) say in their instructions that they edit nothing. Read-only is enforced by the parent session's sandbox, not by the helper's TOML file: every helper runs under the sandbox and approval settings of the session that started it. A helper file cannot override the session's sandbox mode, approval policy, model provider, or MCP servers, so the adapter writes none of them, and a helper's instructions can ask it to avoid edits without creating a separate read-only sandbox. To make a read-only limit binding, set the sandbox and approval controls on the Codex session itself. A Codex build older than the release that added this restriction may still honour sandbox_mode in a helper file; Apothem has not established which release that is, and it writes no sandbox_mode either way.

Compatibility notesCopy Anchor Link

~/.agents/skills/ is a shared root that Codex owns: nine other supported tools load it too (the harness registry lists them), so the Apothem skills a Codex install writes there appear in those tools as well. Four of those tools also write the folder themselves when you install them (the registry lists them as co-installers), with the same files a Codex install writes, so the skills are there on a machine that has no Codex install. The same holds for the rules and templates in ~/.config/apothem/, which seven project-scope adapters write too. The folder is always in your user home, whatever CODEX_HOME is: Codex reads $HOME/.agents/skills, so a CODEX_HOME other than ~/.codex moves the Codex files but not the skills. Every Apothem install that uses the folder writes the same files there, and the install records which installs use it, so the order you install in does not matter. A Codex uninstall removes the skills only when no other Apothem install still uses them; otherwise it keeps them and says which installs do (see Uninstalling). The registered owner is the tool the vendor documents the path for. The install that placed the files is whichever one still uses them, and the install note names it. A skill folder that Apothem did not write and that has the same name as an Apothem skill is left alone, with a warning that names it. The install prints a note that names those tools. ~/.codex/agents/ is a second shared root: another supported tool lists that folder as a compatibility location (the registry names it), and its docs do not say whether it reads the TOML files a Codex install writes there.

Codex reserves ~/.codex/rules/ for .rules execution policies. Apothem does not place Markdown behavioral rules there; it keeps them in ~/.config/apothem/ and references them from AGENTS.md and installed skills.

Codex pluginCopy Anchor Link

Apothem also ships a Codex plugin, added from the repository's plugin marketplace (the install guide lists the commands under channel 7). The plugin is a bootstrap: it bundles one entry skill that runs the engine, and apothem install --harness codex writes everything listed above.

The plugin lives in plugins/apothem/. Its manifest is a root plugin.json, the location Codex documents for a new package. The manifest names no skills path, because Codex discovers a plugin's skills/ directory from the plugin root. A .codex-plugin/plugin.json file stays beside it as a compatibility fallback for Codex builds that read only that older location; Codex still supports it and treats the root manifest as canonical for the plugin's identity. Both files carry the release version, and a test holds them to the engine's version.

The plugin bundles no agents, hooks, or MCP servers. Codex documents no custom-agents component for plugins, so the engine keeps writing agents to ~/.codex/agents/*.toml. Hooks bundled in a plugin are limited to plugins installed manually in Codex desktop and are not trusted automatically, so the engine keeps writing them to ~/.codex/hooks.json.

The marketplace entry sets the policy block Codex tells authors to always include: policy.installation is AVAILABLE and policy.authentication is ON_INSTALL, the defaults Codex documents for a new entry.

VerificationCopy Anchor Link

apothem verify --harness codex

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile.
3. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness codex

Refreshes the Codex bootstrap, converted agents, skills, and support cohorts.

The skill folders in ~/.agents/skills/ are written in one form that every Apothem install of that folder shares: the SKILL.md header keys version, updated, archetype, and portability sit under a metadata map, and userInvocable is written user-invocable. The first update after upgrading rewrites the folders a Codex install wrote earlier into that form, and backs up each folder it changes. apothem rollback --harness codex restores them.

UninstallingCopy Anchor Link

apothem uninstall --harness codex

Removes the Apothem block from ~/.codex/AGENTS.md and keeps any text outside it, and removes Apothem's entries from ~/.codex/hooks.json and keeps yours. Also removes the Apothem files in ~/.codex/hooks/, ~/.codex/agents/, ~/.agents/skills/, and ~/.config/apothem/{rules,templates}/, unless another Apothem install still uses them (the uninstall keeps those and lists them); other files in those folders stay. Skills removed from ~/.agents/skills/ disappear from the other tools that load it too (see Compatibility notes). If you set CODEX_HOME to a folder other than ~/.codex and installed with an earlier release, copies that release wrote beside that folder (<CODEX_HOME>/../.agents/skills/ and <CODEX_HOME>/../.config/apothem/) are not removed; delete them by hand. Each file is backed up under ~/.apothem/backups/ before it is changed or removed. The shared profile YAML and Apothem engine are unaffected.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI