Spec for Codex

A VS Code extension that brings spec-driven development to Codex CLI. Manage your specs, steering documents, and custom prompts visually while leveraging Codex CLI's powerful AI capabilities.

Not affiliated with Amazon, AWS, or OpenAI. Spec for Codex is an independent project. It is compatible with Kiro but is not sponsored by, affiliated with, or endorsed by Amazon.com, Inc. or Amazon Web Services, Inc. "Kiro" is a trademark of Amazon Technologies, Inc.; it is used here only to describe compatibility. "Codex" and "OpenAI" are trademarks of OpenAI. All other trademarks belong to their respective owners.

💡 Announcement:
In the original spec-for-codex, interacting with Codex required sending prompts through the terminal, which unfortunately reduced usability. To address this, I’ve been developing spec-for-codex-ide, which passes the necessary prompts (such as those for spec creation) directly into the context of Codex - OpenAI’s coding agent.

This approach makes working with Codex much smoother, so moving forward I plan to focus development on spec-for-codex-ide as the main project.

Features

⚙️ Configuration

Approval Modes: The specCodex.codex.defaultApprovalMode setting now supports two modes:
- full-auto: (Default) Executes non-destructive commands automatically and asks for approval on failure.
- yolo: Executes all commands without approval. Use with caution.

📝 SPEC Management

Create Specs: generate requirements, design, and task documents with Codex CLI
Visual Explorer: browse and manage specs in the sidebar
Spec Workflow: Requirements -> Design -> Tasks with a review at each step
CodeLens for Tasks: execute an individual task from tasks.md via Codex and auto-check it off

🎯 STEERING Management

Steering Documents: browse and edit global/project-specific guidelines
Generated Docs: product, tech, and structure steering documents

🧩 PROMPTS

Create Prompts: scaffold .codex/prompts/<name>.md from the Prompts view
Click to Open: clicking a prompt opens the Markdown for review
Inline Run Button: use the ▶ action on the right to execute with Codex CLI
Organize & Refresh: manage a workspace prompt library with quick refresh
Markdown Simplicity: no front-matter required; write plain Markdown instructions

💬 CHAT

Sidebar Chat (webview): start quick conversations with Codex inside VS Code
Run once or stream: send a one-off message or stream via a dedicated Codex terminal session
Stop anytime: terminate the active session from the Chat view

🚫 Temporarily Disabled Views/Flows

AGENTS, HOOKS, MCP views: hidden in this build
"New Spec with Agents" flow: disabled

Screenshot

Spec for Codex Extension

The extension provides an organized sidebar for OVERVIEW, SPEC, STEERING, PROMPTS, and CHAT. Other views are hidden in this build.

Installation

Prerequisites

Codex CLI v0.28.0 or later installed and available on PATH
VS Code 1.84.0 or later

Compatibility:

Platform	Support	Notes	Status
macOS	Yes	Fully supported	released
Linux	Yes	Fully supported	released
Windows (WSL)	Yes	Supported with conditional path conversion	released
Windows (PowerShell)	Yes	Recommended on Windows	beta

From Extension Marketplace

VS Code users:

Open VS Code
Go to Extensions (Cmd/Ctrl+Shift+X)
Search for "Spec for Codex"
Click Install

Or via command line:

code --install-extension atman-33.spec-for-codex

From VSIX file

Download the latest .vsix from GitHub Releases, then:

# VS Code
code --install-extension spec-for-codex-{latest-version}.vsix

Replace {latest-version} with the actual version number, e.g., 0.2.4.

Usage

Creating a Spec

Recommended flow:

Click the Spec for Codex icon in the activity bar
In the SPEC view, click + Create New Spec
A webview editor opens; describe your feature/request
The extension generates the requirements document with Codex CLI
Review and approve before proceeding to design
Generate tasks after design is complete

Tip: From tasks.md, use the inline CodeLens action to execute a single task and auto-check it off.

Spec Workflow

Requirements: define what you want to build
Design: create technical design after requirements approval
Tasks: generate implementation tasks after design approval
Implementation: execute tasks one by one

Steering Documents

Create project-specific guidance:

Click the sparkle icon to create custom steering
Generate initial docs (product, tech, structure)
Documents are stored under .codex/steering/

Prompts

Create and run project prompts:

Open the Prompts view in the activity bar
Click + Create Prompt to scaffold .codex/prompts/<name>.md
Write instructions in Markdown (no front-matter required)
Click the prompt item to open the file and review the content
Press the inline ▶ Run button to execute the prompt with Codex CLI (split view)

Chat

Use the Chat view to quickly iterate with Codex:

Open the Chat view under the Spec for Codex activity container
Type a message and choose run mode (send once or stream)
For streaming, the conversation continues in a dedicated Codex terminal session
Use Stop to end the active session

Overview

The Overview view provides quick access to settings, availability checks, and helpful entry points.

Commands (Quick Reference)

Core commands registered by the extension:

specCodex.spec.create: Create a new spec (requirements -> design -> tasks)
specCodex.spec.createWithAgents: Disabled in this build
specCodex.spec.navigate.requirements / specCodex.spec.navigate.design / specCodex.spec.navigate.tasks: Open spec documents
specCodex.spec.implTask: Run an individual task from tasks.md
specCodex.spec.refresh: Refresh the SPEC explorer
specCodex.steering.create: Create a custom steering document
specCodex.steering.generateInitial: Analyze the project and generate initial steering docs
specCodex.steering.refine: Refine an existing steering document
specCodex.steering.delete: Delete a steering document and update docs
specCodex.prompts.create / specCodex.prompts.run / specCodex.prompts.refresh: Manage and run prompts
specCodex.settings.open: Open workspace settings file .codex/settings/specCodex-settings.json
specCodex.menu.open: Toggle visibility of views (Specs / Steering; others when enabled)
specCodex.codex.checkAvailability: Check Codex CLI availability and version
specCodex.checkForUpdates: Manually trigger the extension update checker

Configuration

Project-local settings are stored in .codex/settings/specCodex-settings.json and only contain paths. UI visibility and Codex runtime options live in VS Code settings under the specCodex.* namespace.

Minimal settings file:

{
  "paths": {
    "specs": ".codex/specs",
    "steering": ".codex/steering"
  }
}

Notes:

Only the paths.* values are honored by the extension at runtime.
These path values are no longer exposed in VS Code's Settings UI; update .codex/settings/specCodex-settings.json directly if you need to customize them.
Changing paths.* may require a window reload to take effect.
The settings file itself always lives at .codex/settings/specCodex-settings.json; the directory cannot be relocated.
Prompts are always stored under .codex/prompts; this location is not configurable.
On Windows, override the terminal used for Codex runs by setting specCodex.codex.windowsShellPath in VS Code settings (leave blank to inherit the default).

Workspace Structure

The extension creates the following structure in your workspace:

.codex/                      # Extension data directory
specs/                       # Feature specifications
  {spec-name}/
    requirements.md          # What to build
    design.md                # How to build
    tasks.md                 # Implementation steps
prompts/                     # Project prompts (Markdown)
  <your-prompt>.md
steering/                    # AI guidance documents
  product.md                 # Product conventions
  tech.md                    # Technical standards
  structure.md               # Code organization
settings/
  specCodex-settings.json          # Extension settings

Development

Prerequisites

Node.js 16+
VS Code 1.84.0+
TypeScript 5.3.0+

Setup

# Clone the repository
git clone https://github.com/atman-33/spec-for-codex.git
cd spec-for-codex

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (auto-compile on changes)
npm run watch

Running the Extension

Open the project in VS Code
Press F5 to launch Extension Development Host
The extension will be available in the new VS Code window

Building

# Build VSIX package
npm run package

# Output: spec-for-codex-{latest-version}.vsix

Build details:

Extension bundling: esbuild (outputs dist/extension.js)
Webview UI: Vite (outputs dist/webview/app/**)

Project Structure

src/
  extension.ts                 # Extension entry point, command registration
  constants.ts                 # Configuration constants
  features/                    # Business logic (spec, steering, etc.)
  providers/                   # VS Code TreeDataProviders
  services/                    # Process/error managers and helpers
  utils/                       # Utilities
  prompts/                     # Prompt sources (generated artifacts under prompts/target)
  types/                       # Shared types
webview-ui/                    # Webview source (React + Vite)
dist/webview/app               # Built webview assets consumed by providers

Testing

Vitest
Run: npm test (watch: npm run test:watch, coverage: npm run test:coverage)
Target coverage for new code: >= 80%

Windows Notes

PowerShell is recommended on Windows (direct Codex CLI support)
WSL is supported with conditional path conversion
Need a different Windows terminal? Set specCodex.codex.windowsShellPath to the shell executable you prefer (leave empty to inherit VS Code's default).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Inspiration

Spec for Codex was inspired by the excellent "Kiro for CC" project for Claude Code by @notdp. This extension started as a port/adaptation from Claude Code's Kiro to a Codex CLI–focused workflow, carrying over the spec-driven development experience and UI while integrating tightly with Codex CLI.

Original project: https://github.com/notdp/kiro-for-cc

Spec for Codex

Atman Dev

Spec for Codex

Features

⚙️ Configuration

📝 SPEC Management

🎯 STEERING Management

🧩 PROMPTS

💬 CHAT

🚫 Temporarily Disabled Views/Flows

Screenshot

Installation

Prerequisites

From Extension Marketplace

From VSIX file

Usage

Creating a Spec

Spec Workflow

Steering Documents

Prompts

Chat

Overview

Commands (Quick Reference)

Configuration

Workspace Structure

Development

Prerequisites

Setup

Running the Extension

Building

Project Structure

Testing

Windows Notes

License

Inspiration