AgentKrew

Codex runtime

The Codex adapter renders canonical artifacts into Codex-native project files: agent TOML files under .codex/ and skills under .agents/.

Install

bash
npx @agentkrew/cli init --runtime codex --kit engineer --yes

Verified against codex-cli 0.147.0.

What init generates

text
.agentkrew.json                          installation manifest
AGENTKREW.md                             project context (create-only)
.codex/agents/<name>.toml                one custom agent per kit agent
.agents/skills/<name>/SKILL.md           kit skills
.agents/skills/cmd-<name>/SKILL.md       one per kit command
.agents/skills/workflow-<name>/SKILL.md  one per kit workflow

For the Engineer Kit that is 15 agents, 18 skills, 7 cmd- skills, and 3 workflow- skills.

Codex has no custom-slash-command facility, so AgentKrew commands are rendered as skills with a cmd- prefix — the content is identical to what other runtimes get as commands, only the invocation differs. Workflows use the separate workflow- prefix, so a command and a workflow of the same name never collide.

Rendered agents carry name, description, and developer_instructions (the kit's prompt.md plus a pointer to AGENTKREW.md).

How you use it

Commands are cmd- skills. In a Codex session, mention the skill by name, pick it from the /skills picker, or just describe the task — Codex matches skills by their activation description:

text
$cmd-create-feature Add a user profile page
$cmd-fix-bug CSV import fails on empty rows
$cmd-ship

Workflows work the same way under their own names:

text
$workflow-feature-development Add a user profile page

Agents are custom subagents. Codex spawns them by description (delegation is enabled by default), and parallel groups in a workflow plan become "spawn one agent per step" instructions.

Skills activate implicitly by description match, or explicitly via the /skills picker or a $name mention.

Project context

agentkrew init creates AGENTKREW.md at the project root and never overwrites it. Every generated agent's developer_instructions points to it, so all agents read one shared context file.

Repo-root AGENTS.md is user-owned: AgentKrew never writes it. Codex concatenates AGENTS.md per directory for its own instructions; you can point it at AGENTKREW.md from there if you want session-wide visibility, but the per-agent pointer already guarantees access.

What init never touches

  • Repo-root AGENTS.md
  • ~/.codex/config.toml and .codex/config.toml
  • Anything outside .codex/, .agents/, .agentkrew.json, and AGENTKREW.md

agentkrew update refreshes only generated files; your edits to AGENTKREW.md survive every update. See customization and updates.

Verify

bash
npx @agentkrew/cli doctor
text
✓ Codex detected (0.147.0)
✓ Runtime version compatible
✓ AgentKrew manifest valid
✓ 15 agents
...
AgentKrew is healthy.

Notes and limits

  • Trust caveat: Codex loads the project .codex/ layer only for trusted projects; an untrusted checkout silently ignores generated agents. Skills under .agents/ are unaffected. Mark the project trusted if your agents do not appear.
  • Invocation differs from other runtimes: commands are skills ($cmd-…), not slash commands, because Codex has no custom command facility. The content is the same.
  • No runtime APIs involved: everything is plain files; doctor and validate verify presence and TOML/frontmatter shape locally.
  • Design notes and version-specific research: codex-research.md.