Codex Plugin

Axiom is available as a native plugin for OpenAI Codex, bringing its iOS development skills directly into the Codex CLI, web app, and IDE extensions.

What You Get

The native Codex plugin includes router suites, auditor workflows, and supporting reference and diagnostic guides covering:

• SwiftUI – layout, navigation, animations, performance, architecture, debugging
• Data – SwiftData, Core Data, GRDB, CloudKit, migrations, Codable
• Concurrency – Swift 6, actors, Sendable, async/await, synchronization
• Performance – memory leaks, profiling, energy, Instruments workflows
• Networking – URLSession, Network.framework, connection diagnostics
• Build – Xcode debugging, code signing, build optimization, SPM
• Integration – StoreKit, widgets, push notifications, camera, contacts, haptics
• Apple Intelligence – Foundation Models, on-device AI, CoreML
• Accessibility – VoiceOver, Dynamic Type, WCAG compliance

Prerequisites

• Codex CLI or Codex web app
• Node.js 18+ (for npx)

Installation

npx skills (recommended)

npx skills add CharlesWiltgen/Axiom -a codex -g

This installs all 276 skills globally using npx skills. The -g flag makes skills available across all projects.

To install for the current project only (omit -g):

npx skills add CharlesWiltgen/Axiom -a codex

Verifying Installation

Run npx skills list -g (or npx skills list for project-scoped) to see installed skills. You can also use /plugins in Codex to check.

Codex plugin marketplace (full plugin, including hooks)

npx skills installs the skill content. To install the full Codex plugin — skills, bundled helpers, an installation check, and Axiom's lifecycle hooks (compact session onboarding, automatic skill routing, terminal diagnostic hints, and the @State write-time guardrail) — add Axiom as a native Codex plugin from its bundled marketplace:

codex plugin marketplace add CharlesWiltgen/Axiom
codex plugin add axiom@axiom-marketplace

Hooks are gated behind a Codex feature flag and a one-time trust review. Enable the feature in ~/.codex/config.toml:

[features]
hooks = true

On first run after enabling, Codex asks you to trust the plugin's hooks (they ship in the plugin's hooks/ directory). Approve to activate them.

Check the native plugin installation

The plugin root is the installed directory that contains .codex-plugin/plugin.json. With hooks enabled, Codex is given this path when a session starts, so you can ask Codex where Axiom is installed. Run the read-only installation check from any working directory:

node "<plugin-root>/scripts/doctor.mjs"

The report checks packaged skills, hooks and their dependencies, bundled helper availability, and the MCP startup configuration. The plugin starts the latest published axiom-mcp, the same as every other MCP install path, so the report shows it as unpinned. Host trust, server connectivity, and optional Xcode availability show as unknown unless you pass an optional --host-metadata file, described in the plugin's scripts/README.md.

The full plugin bundles xclog, xcsym, xcui, xcprof, and xcproject under <plugin-root>/bin/. Use those absolute paths unless the helper is already on PATH. xcproject reads both project.pbxproj and JSON5 project.xcproj; it is also packaged as an npm CLI with the MCP server, without an MCP wrapper. The npx skills installation contains skill content only.

Hook diagnostics are off by default. To investigate a hook failure, set AXIOM_HOOK_DIAGNOSTICS_DIR for the Codex process to a private directory you own. Diagnostics record which Axiom hook ran, how long it took, and whether it finished, never your prompts, tool output, credentials, or error messages.

Known issue Codex sometimes reports "hook exited without a status code". Its cause has not been found, and Axiom has not been identified as the source. If you see it, turn on diagnostics as described above and include the resulting journal when you report it.

Manual Marketplace (alternative)

If you prefer not to use npx skills, you can configure the plugin manually.

Clone the repo somewhere under your home directory:

cd ~
git clone https://github.com/CharlesWiltgen/Axiom.git

Add to your personal marketplace at ~/.agents/plugins/marketplace.json:

{
  "name": "axiom-local",
  "interface": { "displayName": "Axiom (Local)" },
  "plugins": [
    {
      "name": "axiom",
      "source": { "source": "local", "path": "./Axiom/axiom-codex" },
      "policy": { "installation": "INSTALLED_BY_DEFAULT" },
      "category": "Development"
    }
  ]
}

The path must start with ./ and is relative to your home directory (the grandparent of ~/.agents/plugins/). Absolute paths are not supported.

Team Installation (Repo-Scoped)

To share Axiom across your team, install at the project level:

npx skills add CharlesWiltgen/Axiom -a codex

This creates skills in .agents/skills/ which you can commit to your repo. Team members get Axiom automatically.

Usage

Skills activate automatically based on your questions. Just ask:

"I'm getting BUILD FAILED in Xcode"
"How do I fix Swift 6 concurrency errors?"
"My app has memory leaks"
"I need to add a database column safely"

Updating

npx skills update

If you installed the native plugin, refresh its marketplace:

codex plugin marketplace upgrade axiom-marketplace

If Codex still runs the older version afterwards, remove the plugin and add it again. If using the manual marketplace method, run cd ~/Axiom && git pull instead.

Removing

npx skills remove -a codex -g

To remove the native plugin instead:

codex plugin remove axiom@axiom-marketplace

Differences from Claude Code

The Codex plugin includes the same skill content as the Claude Code plugin, with a few differences:

Feature	Claude Code	Codex
Skills	Router suites and supporting guides	Same routers and references; auditor procedures are exposed as skills
Agents	42 autonomous auditors	All 42, converted to skills you invoke by name (axiom-audit-memory, axiom-fix-build, …)
Commands	17 /axiom:* commands	Not supported in Codex plugins — use the equivalent agent-skill above
Hooks	Lifecycle hooks (skill routing, @State guardrail, version ground-truth)	Supported via the native plugin install — set features.hooks = true
Installation	/plugin marketplace add	npx skills add, native codex plugin, or manual marketplace

The 31 specialized skills Codex doesn't get as files. Thirty are auditor procedures that each router carries inline for spec-only harnesses; Codex receives every one as a first-class skill instead, so shipping the file too would duplicate the same procedure under two names. The last is getting-started, which drives a Claude Code tool (AskUserQuestion) and cites /axiom:* commands that don't exist in Codex. Nothing else is withheld — every router and every reference ships.

Troubleshooting

Skills not appearing in Codex

• Run npx skills list -g to verify skills are installed
• If using manual marketplace, verify the path points to the axiom-codex/ directory (not the repo root) and starts with ./

Hooks not firing

• Hooks only run with the native plugin install (codex plugin add axiom@axiom-marketplace), not the npx skills skills-only install
• Confirm features.hooks = true is set in ~/.codex/config.toml, and that you approved the hook trust prompt on first run
• Codex runs hook commands through sh -lc, which sources your login profile — make sure your profile writes nothing to stdout (send any echoes to stderr or guard them behind a TTY check), or it can corrupt a hook's output
• Hooks stay silent outside an Apple project by design. If your Apple project uses a layout the detector misses, set AXIOM_SESSION_CONTEXT=always in the environment you launch Codex from — see Non-Apple Projects

Also Available

• Claude Code – Full Axiom experience with 42 autonomous agents and 17 commands
• Pi Coding Agent – Native skills for the Pi terminal coding agent
• MCP Server – Skills in VS Code, Cursor, Gemini CLI, and any MCP-compatible tool
• Xcode Integration – Direct Xcode MCP bridge for in-editor assistance