feat: Add Codex CLI support by honjo-hiroaki-gtt · Pull Request #14 · github/spec-kit

honjo-hiroaki-gtt · 2025-09-04T08:04:53Z

Description

Summary: Adds Codex CLI as a first‑class AI agent option (--ai codex). The init flow verifies Codex, ensures a commands/ directory, and bootstraps minimal command files when packaged templates are unavailable. Agent context updates now target AGENTS.md for Codex.
Why: Parity with existing agents and a smoother first‑run experience for Codex users.
UX notes: Post‑init “Next steps” include Codex slash commands. No breaking changes.

How To Test

uv sync
uv run specify init demo-codex --ai codex --ignore-agent-tools --no-git
- commands/ exists with specify.md, plan.md, tasks.md
- Post‑init shows Codex /specify, /plan, /tasks and AGENTS.md
Optional: If Codex CLI is installed, run codex /specify → /plan → /tasks
Note: uv run specify check only prints warnings for missing tools; it won’t list installed AI tools.

Screenshots

Init — choose Codex CLI

Post‑init — next steps and project tree

Codex — /specify boot and repo scan

/specify — prompt for feature description

/specify — spec drafted with branch + path

Project tree — specs/001‑i‑want‑to/spec.md created

Checklist

Local smoke test passes
Documentation updated where applicable
No breaking changes
Tests: none added; verified manually per steps above (happy to add if a preferred test harness exists)

adam-paterson · 2025-09-04T08:40:04Z

for those wanting to try this before PR approval:

uvx --from git+https://github.com/honjo-hiroaki-gtt/spec-kit.git@feat/add-codex-support specify init --here

adam-paterson · 2025-09-05T22:16:06Z

Okay, I've been testing this on production software for the past two days. It works.

The problem is, because codex-cli doesn't natively support custom commands yet, you have to remind the LLM it should be using the commands defined in the 'commands' directory.

I'm not saying this shouldn't go into release, but if it does it needs a caveat.

A lot of people are finding this repo and thinking it's a new vibe coding tool. It's not, it's a methodology and orchestration framework for software engineering with LLM agents. It works really well, but it's not going to fit into every SWE agent right now.

tabtablabs-dev · 2025-09-06T16:04:08Z

@adam-paterson

Looks like codex has reusable prompts now.

https://github.com/openai/codex/blob/main/docs/prompts.md

benjaminmodayil · 2025-09-06T16:51:05Z

@tabtablabs-dev I'm just starting to take a look at this repo, but I'm assuming the issue with codex is that it doesn't support passing arguments to prompts.

adam-paterson · 2025-09-06T18:40:14Z

@adam-paterson

Looks like codex has reusable prompts now.

https://github.com/openai/codex/blob/main/docs/prompts.md

Oh yeah! These are global prompts though rather than project specific. We have the same issue with codex MCP too. Can't be configured on a project / directory level

Poggen · 2025-09-07T12:23:01Z

I guess we need openai/codex#1548 and openai/codex#3164 to land. Go upvote them!

zvictor · 2025-09-13T15:10:20Z

+    if matching_assets:
+        asset = matching_assets[0]
+    elif ai_assistant == "codex":
+        # Fallback to copilot template if codex-specific template is not published yet


# Fallback to copilot template if codex-specific template is not published yet

Shouldn't this then be to all assistants, including future ones been added?
Why would codex be the only one counting with a fallback system?

zvictor · 2025-09-13T18:07:14Z

+                    if not target_cmds.exists():
+                        # Search for templates/commands within the running package/repo
+                        commands_src = None
+                        for ancestor in Path(__file__).resolve().parents:
+                            cand = ancestor / "templates" / "commands"
+                            if cand.exists() and cand.is_dir():
+                                commands_src = cand
+                                break
+                        if commands_src is not None:
+                            shutil.copytree(commands_src, target_cmds, dirs_exist_ok=True)
+                            tracker.complete("commands", "added")
+                        else:
+                            # Fallback: embed minimal commands
+                            target_cmds.mkdir(parents=True, exist_ok=True)
+                            (target_cmds / "specify.md").write_text(CODEX_CMD_SPECIFY, encoding="utf-8")
+                            (target_cmds / "plan.md").write_text(CODEX_CMD_PLAN, encoding="utf-8")
+                            (target_cmds / "tasks.md").write_text(CODEX_CMD_TASKS, encoding="utf-8")
+                            tracker.complete("commands", "bootstrapped")


This is the structure I am getting:

codex/ ├── .github │ └── prompts │ ├── plan.prompt.md │ ├── specify.prompt.md │ └── tasks.prompt.md ├── .specify │ ├── memory │ │ ├── constitution_update_checklist.md │ │ └── constitution.md │ ├── scripts │ │ └── bash │ │ ├── check-task-prerequisites.ps1 │ │ ├── common.ps1 │ │ ├── create-new-feature.ps1 │ │ ├── get-feature-paths.ps1 │ │ ├── setup-plan.ps1 │ │ └── update-agent-context.ps1 │ └── templates │ ├── agent-file-template.md │ ├── plan-template.md │ ├── spec-template.md │ └── tasks-template.md └── commands ├── plan.md ├── specify.md └── tasks.md

Wouldn't it be better to have /commands/plan.md as a symlink to /github/prompts/plan.prompt.md rather than a dumbed out version of it?

danwashusen · 2025-09-15T10:46:25Z

I've been using Codex all day. It's as simple as:

Run the `.claude/commands/specify.md` playbook with blah blah blah

It doesn't auto-expand the file path with @ (I guess they've excluded .claude?) which is a little cumbersome but otherwise works well...

rbergman · 2025-09-15T15:12:53Z

@adam-paterson
Looks like codex has reusable prompts now.
https://github.com/openai/codex/blob/main/docs/prompts.md

Oh yeah! These are global prompts though rather than project specific. We have the same issue with codex MCP too. Can't be configured on a project / directory level

FWIW, CODEX_HOME can be set to the path to the repo root which will give per-project config and prompt isolation. Not as nice as claude code, but it's possible. The most annoying part of that is having to login with the CLI for every project.

localden · 2025-09-17T19:37:55Z

@honjo-hiroaki-gtt - could you update your branch with the latest version of Specify and integrate your changes? Happy to merge after. Make sure to also rev the package version and update the changelog file.

honjo-hiroaki-gtt · 2025-09-18T01:38:31Z

@localden
I’ve rebased on the latest upstream/main, resolved the conflicts, and integrated the Codex changes. The package version is now bumped to 0.0.7 and the changelog has been updated with the Codex support details. Thanks for taking another look!

…o-upgrade generated commands.

PaoloC68 · 2025-09-18T11:11:27Z

@honjo-hiroaki-gtt
Can I ask a maybe dumb question?
I have installed using this commmand: uvx --from git+https://github.com/honjo-hiroaki-gtt/spec-kit.git@feat/add-codex-support specify init --ai codex --no-git --here
Then I see the following folder being created:

.github
   └── prompts
       ├── plan.prompt.md
       ├── specify.prompt.md
       └── tasks.prompt.md

If I copy its content this way:

.codex/prompts
├── plan.md
├── specify.md
└── tasks.md

the commands are recognized, not if they stay in the commands directory.
Am I doing something wrong? To my understanding the .codex/prompts is the right place to put this commands following codex specs

…orkflow.

…ntation accordingly.

honjo-hiroaki-gtt · 2025-09-19T16:13:23Z

Thanks again for surfacing all of these details—it really clarified the root cause for me.

My current plan is to keep seeding the prompt sources under commands/, but teach specify init --ai codex to mirror them into ${CODEX_HOME:-~/.codex}/prompts (creating the folder when needed), prefix the filenames to avoid collisions, and skip re-copying unchanged prompts. I’ll also add .gitignore guidance for repo-local .codex/ setups and refresh the docs to cover the new behavior plus per-project CODEX_HOME usage.

I’m going to work through those changes next, so please give me a bit of time before I push the update.

localden · 2025-09-19T20:28:27Z

 specify init <project_name> --ai claude --ignore-agent-tools
 ```

+> [!NOTE]


@honjo-hiroaki-gtt I am still not sure how Codex CLI is different here - aren't all other agents also loading the commands from the workspace folder? That's how we use other agents as well (e.g., Claude Code, Copilot).

localden · 2025-09-20T07:09:10Z

@honjo-hiroaki-gtt - I am planning on getting the Codex CLI support ready for Monday. Let me know if this is not feasible for you, and I am happy to pick up the PR and drive it to the finish line.

incrediblezayed · 2025-09-20T08:49:27Z

Monday as in 22nd Septemer? @localden

…eration without git, and documenting clearer /specify usage.

…rf updates

honjo-hiroaki-gtt · 2025-09-20T14:52:10Z

@localden
Thanks for checking in! I just pushed the Codex updates we discussed—prompt mirroring, docs, and helper scripts should now line up with the plan.

Please take another look when you have a moment, and feel free to tweak anything that still needs polish.

crisweber2600 · 2025-09-20T15:57:35Z

I’M SO READY FOR THIS!

localden · 2025-09-20T16:10:18Z

Currently working on cleanup - the current PR adds a bit too much, and the changes for new agents should be a bit more surgical 😁

incrediblezayed · 2025-09-20T18:04:50Z

Currently working on cleanup - the current PR adds a bit too much, and the changes for new agents should be a bit more surgical 😁

So is this live now? 😲

insilications · 2025-09-20T20:22:05Z

Did this required any changes to codex?

danwashusen · 2025-09-21T06:57:30Z

@localden Testing this now, as far as I can tell it's not working... the templates/commands files need to end up in the .codex/prompts directory (not the .codex/commands directory)...

❯ ls ${CODEX_HOME:-~/.codex}/prompts
 
❯ ls ${CODEX_HOME:-~/.codex}/commands
constitution.md implement.md    plan.md    specify.md    tasks.md

❯ mv ${CODEX_HOME:-~/.codex}/commands/* ${CODEX_HOME:-~/.codex}/prompts/
❯ ls ${CODEX_HOME:-~/.codex}/prompts
constitution.md implement.md    plan.md     specify.md      tasks.md

danwashusen · 2025-09-21T07:26:51Z

Also I'd not really clear they the prompts work as intended, Codex does not appear to pass the "arguments" to the ...

As an example in Claude Code using /specify make a flappy bird app works as expected:

However using Codex the "make a flappy bird app" part is just swallowed and lost (it does not enter the context). As a result the specify instruction Given that feature description, do this: gets confused and starts search random files for the feature description...

To get Codex working I need to do something like:

Index: .codex/prompts/specify.md
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/.codex/prompts/specify.md b/.codex/prompts/specify.md
--- a/.codex/prompts/specify.md	(revision 73095fb8b7e2d2a271f340fa81ec92ceb867e4c6)
+++ b/.codex/prompts/specify.md	(date 1758440011260)
@@ -9,7 +9,7 @@
 even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it
 unless they provided an empty command.
 
-Given that feature description, do this:
+Determine the feature description based on the argument or ask for the feature description if unsure, then do this:
 
 1. Load Spec Kit configuration:
    - Check for `/.specify.yaml` at the host project root; if it exists, load

> /specify a flappy bird app
> I don’t see the feature description that follows /specify. Could you share that text so I can generate
  the spec?
>

honjo-hiroaki-gtt · 2025-09-21T08:49:02Z

@danwashusen
Looks like the run you’re seeing is still executing an older build—on the current branch sync_codex_prompts copies the markdown files into ${CODEX_HOME}/prompts. Could you try forcing UV to use the local source (and bypass the cache) with:

uvx --no-cache --from /path/to/spec-kit specify init test-codex \
  --ignore-agent-tools --no-git --ai codex

After that, the codex-prompts step should appear in the logs and the files should land in ${CODEX_HOME}/prompts.

danwashusen · 2025-09-21T12:06:41Z

@danwashusen

Looks like the run you’re seeing is still executing an older build—on the current branch sync_codex_prompts copies the markdown files into ${CODEX_HOME}/prompts. Could you try forcing UV to use the local source (and bypass the cache) with:
uvx --no-cache --from /path/to/spec-kit specify init test-codex \

  --ignore-agent-tools --no-git --ai codex
After that, the codex-prompts step should appear in the logs and the files should land in ${CODEX_HOME}/prompts.

Hmm, I was testing locally after seeing Codex support mentioned in the commit log after bringing in changes from upstream/main. I'll check again...

danwashusen · 2025-09-21T20:33:11Z

@danwashusen Looks like the run you’re seeing is still executing an older build—on the current branch sync_codex_prompts copies the markdown files into ${CODEX_HOME}/prompts. Could you try forcing UV to use the local source (and bypass the cache) with:
uvx --no-cache --from /path/to/spec-kit specify init test-codex \
  --ignore-agent-tools --no-git --ai codex
After that, the codex-prompts step should appear in the logs and the files should land in ${CODEX_HOME}/prompts.

My bad, I didn't notice the release artefacts moved to .genreleases/ so I was installing an outdated release.

danwashusen · 2025-09-22T22:38:08Z

For anyone wondering how to use these commands given that Codex doesn't support arguments (e.g. /plan specs/007-epic-2-story/), I've used the following with success:

> Define $ARGUMENTS as specs/007-epic-2-story/. Take no action, await further instructions.
> /plan
...

> Define $ARGUMENTS as "specs/007-epic-2-story/, focus on Phase 3.1". Take no action, await further instructions.
> /implement
...

sbaechler · 2025-09-24T08:28:32Z

I guess we need openai/codex#1548 and openai/codex#3164 to land. Go upvote them!

What about those open codex issues? Are they not required for spec kit to work as expected with Codex?

…pport feat: Add Codex CLI support

honjo-hiroaki-gtt requested a review from localden as a code owner September 4, 2025 08:04

DevGuyRash mentioned this pull request Sep 5, 2025

OPEN AI codex support #30

Closed

danizord mentioned this pull request Sep 5, 2025

feat: add Codex CLI support #22

Closed

localden mentioned this pull request Sep 7, 2025

feat: Implement Support for Open AI's Codex CLI #49

Closed

MDfly7 mentioned this pull request Sep 7, 2025

Generic OpenAI-compatible API support #32

Closed

lmerz1 mentioned this pull request Sep 9, 2025

Codex CLI support #110

Closed

localden self-assigned this Sep 10, 2025

localden added enhancement merge-candidate Reasonable change that is going to be merged after a review. labels Sep 10, 2025

localden mentioned this pull request Sep 12, 2025

feat: Add OpenAI Codex CLI support to spec-kit #203

Closed

zvictor reviewed Sep 13, 2025

View reviewed changes

zvictor mentioned this pull request Sep 13, 2025

Feat/add codex support #233

Closed

zvictor reviewed Sep 13, 2025

View reviewed changes

honjo-hiroaki-gtt force-pushed the feat/add-codex-support branch from 66257cd to c440ca0 Compare September 18, 2025 01:37

honjo-hiroaki-gtt added 4 commits September 18, 2025 15:39

Add Codex CLI support with AGENTS.md and commands bootstrap

95fba17

Fix remaining merge conflict markers in __init__.py

e29488d

Normalize Codex command templates to the scripts-based schema and aut…

a39185c

…o-upgrade generated commands.

Bump to 0.0.7 and document Codex support

286ad55

honjo-hiroaki-gtt force-pushed the feat/add-codex-support branch from c440ca0 to 286ad55 Compare September 18, 2025 06:39

honjo-hiroaki-gtt added 2 commits September 19, 2025 16:40

Clarify Codex-specific README note with rationale for its different w…

3127032

…orkflow.

Limit workspace command seeding to Codex init and update Codex docume…

3a0ae75

…ntation accordingly.

localden suggested changes Sep 19, 2025

View reviewed changes

honjo-hiroaki-gtt added 2 commits September 20, 2025 22:44

Enhance Codex support by auto-syncing prompt files, allowing spec gen…

65ccbb6

…eration without git, and documenting clearer /specify usage.

Resolve merge conflicts integrating Codexsupport with upstream Windsu…

5373327

…rf updates

Merge branch 'main' into feat/add-codex-support

8784f39

Remove Codex-specific logic in the initialization script

6a3ff65

localden added 5 commits September 20, 2025 09:13

Update __init__.py

dc8fdc2

Update __init__.py

caee341

Update config

d7d2c14

Update package release

2aa30cd

Update update-agent-context.ps1

60b8d8f

localden approved these changes Sep 20, 2025

View reviewed changes

localden merged commit 6f1970a into github:main Sep 20, 2025

jellydn pushed a commit to jellydn/spec-kit that referenced this pull request Sep 30, 2025

Merge pull request github#14 from honjo-hiroaki-gtt/feat/add-codex-su…

6cda9ac

…pport feat: Add Codex CLI support

Uh oh!

Conversation

honjo-hiroaki-gtt commented Sep 4, 2025

Description

How To Test

Screenshots

Checklist

Uh oh!

adam-paterson commented Sep 4, 2025

Uh oh!

adam-paterson commented Sep 5, 2025

Uh oh!

tabtablabs-dev commented Sep 6, 2025

Uh oh!

benjaminmodayil commented Sep 6, 2025

Uh oh!

adam-paterson commented Sep 6, 2025

Uh oh!

Poggen commented Sep 7, 2025

Uh oh!

zvictor Sep 13, 2025

Choose a reason for hiding this comment

Uh oh!

zvictor Sep 13, 2025

Choose a reason for hiding this comment

Uh oh!

danwashusen commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rbergman commented Sep 15, 2025

Uh oh!

localden commented Sep 17, 2025

Uh oh!

honjo-hiroaki-gtt commented Sep 18, 2025

Uh oh!

PaoloC68 commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

honjo-hiroaki-gtt commented Sep 19, 2025

Uh oh!

localden Sep 19, 2025

Choose a reason for hiding this comment

Uh oh!

localden commented Sep 20, 2025

Uh oh!

incrediblezayed commented Sep 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

honjo-hiroaki-gtt commented Sep 20, 2025

Uh oh!

crisweber2600 commented Sep 20, 2025

Uh oh!

localden commented Sep 20, 2025

Uh oh!

incrediblezayed commented Sep 20, 2025

Uh oh!

insilications commented Sep 20, 2025

Uh oh!

danwashusen commented Sep 21, 2025

Uh oh!

danwashusen commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

honjo-hiroaki-gtt commented Sep 21, 2025

Uh oh!

danwashusen commented Sep 21, 2025

Uh oh!

danwashusen commented Sep 21, 2025

Uh oh!

danwashusen commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sbaechler commented Sep 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

danwashusen commented Sep 15, 2025 •

edited

Loading

PaoloC68 commented Sep 18, 2025 •

edited

Loading

incrediblezayed commented Sep 20, 2025 •

edited

Loading

danwashusen commented Sep 21, 2025 •

edited

Loading

danwashusen commented Sep 22, 2025 •

edited

Loading