Codex

Run the same home from OpenAI Codex. Per-home hooks and MCP registration, a permission profile generated from the home's settings, and the limits that remain.

Since 0.4.1 the agent-kevin checkout is also a Codex plugin. The skills are the same files. What differs is the wiring: Codex plugins cannot yet carry hooks or a bundled MCP server that knows which home it serves, so both are generated per home into .codex/.


Launch	`codex` from the home
Skills	`$<skill>`
Manual	`AGENTS.md`, read natively
Hooks and MCP server	Generated per home into `.codex/`
Settings	The home's `.claude/settings.json` and `settings.local.json`, projected into `.codex/config.toml` and `.codex/rules/`
Reload after a plugin update	Remove and re-add the plugin, then `$upgrade`

Setting up a home

Install the plugin as on the Install page. Then, from a home that already exists:

cd ~/Documents/Agents/Kevin
codex

Run $upgrade there (or /agent-kevin:upgrade from Claude Code, which asks whether the home also runs Codex). Either writes the wiring below. Trust the folder and the hook entries once via /hooks.

Create the home from Claude Code for now

A brand-new home created with $init under Codex is not exercised yet. Scaffold it from Claude Code, then open it from Codex.

What gets wired

<HOME>/.codex/
├── hooks.json          # SessionStart context · SessionEnd + PreCompact capture · PreToolUse guard
├── config.toml         # [mcp_servers.kevin] with AGENT_HOME · [permissions.kevin] profile · shell env policy · [tui] status line
└── rules/kevin.rules   # one prefix_rule per Bash(…) entry in the Claude settings' ask list

Piece	What it does
`SessionStart` hook	Delivers the whole static stack (identity files, indexes, task board) plus the same dynamic lane Claude gets, as one payload. Registered with `additionalContextLimit: 0`, since Codex otherwise truncates a hook at about 2,500 tokens
`SessionEnd` + `PreCompact`	Capture from Codex's rollout JSONL: user and assistant turns only, with injected `AGENTS.md`, environment block, and `$skill` expansions dropped
`PreToolUse`	The same cwd-drift guard; Codex presents shell commands to hooks as `Bash`, the same contract
`[mcp_servers.kevin]`	The plugin's MCP server registered per home with `--home=` pinned, so an inherited override cannot outrank it
`[permissions.kevin]`	A profile generated from the home's settings: denies every read of `.kevin/secrets/` and any `.env`, keeps `.git` writable so commits stay routine, lists the code path and `additionalDirectories` as workspace roots
`rules/kevin.rules`	Every `Bash(…)` pattern in `permissions.ask` becomes a prompt, with `approvals_reviewer = "user"` so a human answers
`[shell_environment_policy]`	Hands the model's shell the home variables and the home's `AGENT_*` settings, never a key or token

The generator merges into existing files, replaces only Kevin's own entries, and validates the TOML before writing. Codex reads the home's AGENTS.md natively, so the manual needs no bridge file.

User-level settings

Some keys belong in ~/.codex/config.toml rather than a home: telemetry and provider keys, which Codex ignores in a project config, plus analytics, feedback, terminal animation, and update checks, which describe your machine rather than an agent, and the model context window, a cost choice for every session on the machine (the note asks for the cap Codex's model catalog serves, since a larger request is silently clamped to it). The home's own footer status line (model, directory, branch, approval mode, context used) is written into its .codex/config.toml by init and upgrade; a status line you already set there is kept. The plugin never writes a user-level file. Init and upgrade generate a paste-ready note at .kevin/updates/codex-user-config.md built from your Claude Code user-level settings, and until you paste it, the home's own profile carries the user-level denies too. Nothing in the note names an agent.

Sessions are shared

A session ended in Codex is in Claude Code's context next time, and the other way round. Session blocks record which harness and model produced them.

Updating

Codex installs a copy of the checkout into its plugin cache, so after pulling new code:

codex plugin remove agent-kevin@agentdev-kevin && codex plugin add agent-kevin@agentdev-kevin

Then $upgrade from the home. Hook commands rarely change; the report says hooks.changed: true when you need to re-trust.

Current limits

Skills that name ${CLAUDE_PLUGIN_ROOT} resolve it through the plugin-root line in the SessionStart header, an instruction rather than a shell variable.
The session radar (where-am-i, find-session) reads Claude transcripts only.
The profile enables the network inside the sandbox, since an approved escalation does not lift a profile; the outbound gate is the rules file alone. Domain allowlists need Codex's experimental network proxy.
The reviewer model (auto_review) stays opt-in; on this plugin's tests it denied a named push and a local commit.
Native Windows under Codex is unverified: the wiring is shaped to parse under PowerShell, but the skills are bash.