Kiro for Codex IDE

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

Feature Overview

📝 Spec Management

• Run Kiro for Codex IDE: Create New Spec (kiro-codex-ide.spec.create) to launch the guided prompt. This will pass the context to the VS Code Codex extension's chat, where you can interact to create the spec.
• Browse generated specs in the Specs view; each spec exposes Requirements, Design, and Tasks nodes with quick-open commands.
• Execute individual checklist items from tasks.md via the "Start Task" CodeLens, which marks the checklist and passes the task context to the VS Code Codex extension's chat. You can then interact with the chat to execute the task.

🎯 Steering Management

• The Steering view surfaces global (~/.codex/AGENTS.md) and project-level (AGENTS.md) rules and lets you open them instantly.
• Use the built-in commands to create global or project rules, initialize steering documents, refine existing files, or delete outdated guidance. These actions will pass the relevant context to the VS Code Codex extension's chat, allowing you to interact and manage your steering documents.

🧩 Prompts

• Maintain Markdown prompts under .codex/prompts (default paths configurable).
• Create prompts from the tree view; the extension scaffolds the file and opens it for editing.
• Run prompts from the inline action or the command palette, which passes the document as context to the Codex Chat provided by the VS Code Codex extension.

Installation

Prerequisites

• Codex CLI 0.28.0 or later available on PATH.
• Visual Studio Code 1.84.0 or newer.
• Node.js 16+ for local builds.
• VS Code Codex extension must be installed. This extension utilizes the Codex Chat functionality provided by the ChatGPT extension to pass prompt contexts.

Marketplace (when published)

Search for "Kiro for Codex IDE" in the VS Code Marketplace and install the extension.

From Local VSIX

1. Build the package with npm run package (produces kiro-for-codex-ide-ide-<version>.vsix).
2. Install via code --install-extension kiro-for-codex-ide-ide-<version>.vsix.

Usage

Create a Spec

1. Open the Kiro for Codex IDE activity bar container.
2. Choose Specs → Create New Spec.
3. Describe the feature in the VS Code Codex extension's chat. The extension will then generate requirements, design, and tasks under .codex/specs/<spec-name>/.
4. Review each document before moving to the next step.

Execute Tasks from tasks.md

1. Open the generated tasks.md file.
2. Click the "Start Task" CodeLens next to a checklist item.
3. The extension checks off the task locally and passes the task context to the VS Code Codex extension's chat. You can then interact with the chat to execute the task.

Manage Steering Documents

1. Open the Steering view to inspect global and project AGENTS.md files.
2. Use Init Steering to generate product, tech, and structure documents, or Create Custom Steering for ad-hoc guidance. These actions will pass the relevant context to the VS Code Codex extension's chat, allowing you to interact and manage your steering documents.
3. Refine or delete documents from the context menu; the extension keeps AGENTS.md synchronized.

Work with Prompts

1. Open the Prompts view and press Create Prompt to scaffold a Markdown prompt.
2. Edit the file; Markdown frontmatter is optional.
3. Use Run Prompt to push the file into the Codex Chat (provided by the VS Code Codex extension). You can then interact with the chat to utilize the prompt.

Configuration

All settings live under the kiro-codex-ide namespace.

Paths accept custom locations inside the workspace; the extension mirrors watchers to match custom directories.

Workspace Layout

.codex/
├── prompts/                # Markdown prompts consumed by Codex CLI
├── specs/
│   └── <spec>/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── steering/
│   └── *.md                # Product / tech / structure guidance
├── settings/
│   └── kiroCodex-settings.json
LICENSE
src/
├── extension.ts            # Activation, command registration, tree providers
├── features/               # Spec and steering managers
├── providers/              # TreeDataProviders, CodeLens, webviews
├── services/               # Prompt loader (Handlebars templates)
├── utils/                  # Config manager, Codex chat helpers
└── prompts/                # Prompt source markdown and generated TypeScript
webview-ui/                 # React + Vite webview bundle
scripts/
└── build-prompts.js        # Markdown → TypeScript prompt compiler

Development

1. Install dependencies for both the extension and webview UI:
   • npm run install:all
2. Build prompts and bundle the extension:
   • npm run build (runs prompt compilation, extension bundle, and webview build)
3. Launch the development host:
   • Press F5 inside VS Code or run the Extension launch configuration.
4. Live development:
   • npm run watch (TypeScript watch + webview dev server)
   • npm --prefix webview-ui run dev (webview in isolation)
5. Generate prompt modules when editing markdown under src/prompts:
   • npm run build-prompts

Testing and Quality

• Unit tests: npm test, npm run test:watch, or npm run test:coverage (Vitest).
• Linting, formatting, and static checks: npm run lint, npm run format, npm run check (Ultracite toolchain).

Packaging

• Produce a VSIX with npm run package (requires vsce).
• The output bundle lives in dist/extension.js; webview assets emit to dist/webview/app/.

License

MIT License. See LICENSE.

Credits

Inspired by the original Kiro project for Claude Code by @notdp, adapted here for Codex CLI workflows.

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