Making Arness Work with Codex

I came to Arness second-hand. It surfaced in a session at CITCON:AI in Helsinki this May that Jeffrey Fredrick had put on the board, called Hands-on AI frameworks speedrun. CITCON runs as an open space, so the agenda is whatever the people in the room decide to talk about, and this one was a group sitting down to run through a handful of AI development frameworks back to back: Superpowers, BMAD-METHOD, nwave.ai, and Arness among them. Arness took more time than the session really had room for, but the group found it interesting, and Jeffrey told me about it afterwards.

On a call after the conference, he suggested I give it a proper try, so I did. Over the next few days I put it to work on several real projects, not just a throwaway demo, and it held up well enough that I kept reaching for it.

What stood out the more I used it was how Arness is put together. It is an open source plugin system for structured AI development workflows, and that structure is the interesting part. It is not just a bag of prompts.

Arness is closer to a full workflow layer: product discovery, feature planning, implementation, code review, shipping, and the infrastructure side too. It splits into three plugins (Spark, Code, and Infra), with seven main entry points sitting on top of a much larger set of skills and specialist agents. That shape is what kept me coming back to it.

After about four days of this, spread across those projects, I started running low on Claude Code tokens. That is the catch with Arness: out of the box it is a Claude Code plugin. Meanwhile I had a stack of OpenAI Codex tokens sitting idle. Rather than slow down, I wanted to extend Arness so it could run on Codex too, so I forked it to PaulJulius/arness and started experimenting. Everything I describe below currently lives in that fork rather than upstream.

There is a nice recursion to all this. Arness already dogfoods itself, in the sense that the project uses Arness to build Arness. So I followed its lead and used Arness to extend Arness. Once the Codex support was far enough along, I was using Arness from Codex to extend Arness with Codex.

The Easy Part: Plugin Packaging

The obvious first step was packaging. I added a Codex plugin manifest for each of the three plugins:

• arn-spark
• arn-code
• arn-infra

Each one now has a .codex-plugin/plugin.json holding its name, version, description, capabilities, default prompts, and a bit of interface metadata. I also added a Codex marketplace file at .agents/plugins/marketplace.json that points Codex at the three local plugin directories.

None of that was difficult. It is the sort of thing you can finish in an afternoon if you read the existing manifests carefully.

Removing Hidden Host Assumptions

The harder part came next, and it was the part I had expected to be easy. Claude Code assumptions were baked into all sorts of places: not just the code, but the docs, the command examples, the task flow, and the configuration. Most were small, and most were invisible until you tried to run the same thing under a different tool.

The clearest example is how a workflow gets invoked. In Claude Code, an Arness skill shows up as a slash command:

/arn-planning

In Codex you reach the same workflow through a prompt instead:

codex "arn-planning add rate limiting"

So the docs and the skill instructions had to stop treating the leading slash as the name of the thing. The skill name is what stays the same. The tool around it decides how you actually call it.

That turned into a fairly broad documentation pass. The README, the getting started guide, the plugin docs, the reference docs, and the walkthroughs now use plain skill names, and then explain the two ways to run them: a slash command in Claude Code, a prompt in Codex. It is a small wording change written out hundreds of times, but it matters, because the old wording quietly assumed one tool.

Workflow Mechanics and a File-Backed Fallback

Some of the workflows leaned on host features that Codex does not necessarily expose the same way, things like task APIs and Agent Teams support. So the Code plugin now has a fallback that works off plain files.

For instance, arn-code-taskify no longer needs a host task API. It reads TASKS.md, writes task reports, and can drive execution straight from files like TASKS.md and PROGRESS_TRACKER.json. You still get the structure, the dependencies, and the review gates. You just do not need one particular tool's task system sitting underneath it.

This fits how Arness already works. The files are the real product: a spec feeds a plan, the plan feeds tasks, the tasks feed execution reports, those feed review, and review feeds shipping. Supporting Codex mostly meant trusting those files a bit more and trusting host-specific features a bit less.

One decision I kept going back and forth on was CLAUDE.md. In the end I left it where it was. The name is a bit of a historical accident now, because the ## Arness section inside it is really shared configuration that both Claude Code and Codex read. Renaming it would be tidier on paper. In practice it would have meant a lot of churn across the repo for very little real gain, and it would have risked breaking compatibility for the sake of a nicer filename. So I clarified what the file is for in the docs and left the name alone. Not elegant, but it was the honest tradeoff.

Validation Turns Assumptions into Checks

The last piece was validation, which is the boring kind of work that turns out to matter.

I added a repository validation script, run through:

make validate

and wired it into GitHub Actions so it runs on pushes and pull requests.

It checks the unglamorous things: that marketplace entries line up with the actual plugin directories, that the Codex and Claude manifests agree where they are supposed to, that skill and agent frontmatter is well formed, that versions are valid semver, that the reference docs match the real list of skills and agents, that eval files point at skills that exist, that Markdown links resolve, that nobody's local absolute paths have leaked into the repo, and that CI is set up to run all of this. On the current branch it runs 2,233 checks, and they pass.

The reason I bothered is simple. Compatibility does not break in one dramatic moment, it rots slowly. Someone renames a skill, a reference table goes stale, a manifest loses a field, an instruction quietly assumes Claude Code again, and none of it shows up until the next person's first run falls over. A validation script will not catch everything, but it turns a pile of "I think this still works" into something you can actually run.

Not Betting Everything on One Tool

In the end this was not really about adding one more install command. It was about not letting the workflow depend too heavily on the tool it happened to grow up in.

The parts that should not care which tool you use are the ones doing the real work:

• the skill names
• the plugin manifests
• the plain-text files
• the project configuration
• the task and progress files
• the validation rules

What is genuinely tied to one tool is thin now: a slash command in Claude Code, a prompted skill name in Codex.

That feels like the right direction for this sort of tooling. If a workflow is any good, it should not fall apart the moment you switch the tool you run it in. These tools are moving quickly, and I would rather not pin the way I work to whichever one happens to be ahead this quarter. Getting Arness running under Codex was, more than anything, a way to check that the workflow could stand on its own.

If you want to try the Codex side yourself, it lives in my fork:

codex plugin marketplace add PaulJulius/arness
codex plugin add arn-code@arn-marketplace
codex "arn-planning add rate limiting"

From there the usual Arness flow takes over: plan the work, keep the files, run it with some structure, and review before you ship.