An AI-powered development framework that transforms product ideas into production-ready software through intelligent workflows, consistent standards, and seamless AI assistant integration.
The Problem: Most development teams struggle with inconsistency—different coding styles, ad-hoc planning processes, incomplete documentation, and manual repetitive tasks that lead to bugs and technical debt.
The Solution: Codex-OS provides an AI-powered development framework that guides you from initial product requirements to production deployment with:
- 🤖 AI-First Workflows — Work naturally with AI assistants using simple commands
- 📋 Structured Planning — Turn PRDs into actionable technical specs
- 🔄 Consistent Processes — Repeatable workflows for every development phase
- 🛡️ Safety by Default — Built-in quality gates and rollback strategies
- 📚 Living Documentation — Auto-updating specs and decision records
-
Clone the repository:
git clone https://github.com/forsonny/codex-os cd codex-os -
Run the installation script:
chmod +x scripts/install-global.sh ./scripts/install-global.sh
This script will:
- Move global files to
~/.codex-os/ - Backup and install AGENTS.md to
~/.codex/ - Clean up placeholder directories
- Verify the installation
- Move global files to
-
Make helper scripts executable:
chmod +x bin/co-* -
Install dependencies (if using the TypeScript/JavaScript stack):
npm install # or pnpm install
-
Clone the repository:
git clone https://github.com/forsonny/codex-os cd codex-os -
Move global files to your home directory:
# Create the target directories mkdir -p ~/.codex-os mkdir -p ~/.codex # Move the CONTENTS of the global Codex-OS folder mv "move to HOME/.codex-os"/* ~/.codex-os/ # Backup existing AGENTS.md if it exists if [ -f ~/.codex/AGENTS.md ]; then cp ~/.codex/AGENTS.md ~/.codex/AGENTS.md.backup.$(date +%Y%m%d_%H%M%S) echo "Backed up existing AGENTS.md to ~/.codex/AGENTS.md.backup.$(date +%Y%m%d_%H%M%S)" fi # Move new AGENTS.md to ~/.codex directory mv "move to HOME/.codex/AGENTS.md" ~/.codex/AGENTS.md
-
Clean up placeholder directories:
# Remove the now-empty placeholder directories rmdir "move to HOME/.codex-os/instructions/core" rmdir "move to HOME/.codex-os/instructions" rmdir "move to HOME/.codex-os/standards/code-style" rmdir "move to HOME/.codex-os/standards" rmdir "move to HOME/.codex-os/product" rmdir "move to HOME/.codex-os" rmdir "move to HOME/.codex" rmdir "move to HOME"
-
Make helper scripts executable:
chmod +x bin/co-* -
Install dependencies (if using the TypeScript/JavaScript stack):
npm install # or pnpm install
You need to add/update the .codex-os/specs/srd.md. The srd.md is the file where you will place your PRD or MVP infomation in.
Work with your AI assistant using these commands:
/co-plan
Plan your product from requirements
/co-create-spec User Authentication System
💡 Pro Tip: Use
/co-create-specto create a spec for the full project based on srd.md
Create a technical specification
/co-exec-tasks .codex-os/specs/2025-08-23-user-authentication-system
Execute the implementation
/co-exec-task [TASK-ID]
Execute excate task
/co-analyze
Analyze your codebase health
💡 Pro Tip: These
/co-commands work with Claude, GPT, and other AI assistants. Just type the command and your AI will execute the corresponding workflow!
Codex-OS is an AI-powered development framework that guides you through a proven workflow:
PRD/Idea → /co-plan → /co-create-spec → /co-exec-tasks → /co-analyze → Deploy
↓ ↓ ↓ ↓ ↓ ↓
Goals → Roadmap → Specification → Implementation → Health → Production
Transform raw product requirements into structured documentation
- Mission and success metrics
- Technology stack decisions
- Roadmap with milestones
- Architecture decision records (ADRs)
Convert plans into actionable technical specifications
- Software Requirements Document (SRD)
- Technical architecture and APIs
- Prioritized task breakdown with acceptance criteria
Implement features safely with automated quality gates
- Test-driven development
- Small, atomic commits
- Continuous integration
- Documentation updates
Monitor codebase health and identify improvements
- Architecture analysis
- Risk assessment
- Performance bottlenecks
- Actionable recommendations
🤖 AI-First Approach: Simply type these commands with your AI assistant (Claude, GPT, etc.) and watch as they execute complete workflows, write code, run tests, and update documentation automatically.
The primary way to interact with Codex-OS is through AI assistant commands:
| Command | Purpose |
|---|---|
/co-plan |
Update product documentation from requirements |
/co-create-spec [title] |
Generate new feature specifications |
/co-exec-tasks [spec-path] |
Execute all tasks in a specification |
/co-exec-task [task-id] |
Execute a single task with minimal changes |
/co-analyze |
Analyze codebase health and generate reports |
These commands integrate seamlessly with Claude, GPT, and other AI assistants through the global AGENTS.md configuration.
.codex-os/
├── product/ # Mission, roadmap, decisions, stack
├── specs/ # Feature specifications with tasks
└── standards/ # Coding standards and best practices
- TypeScript/JavaScript: Prettier + ESLint with strict mode
- Python: Black + Ruff with comprehensive type hints
- Testing: Unit → Integration → E2E pyramid
- Git: Conventional Commits with semantic versioning
- Security: Secret scanning, dependency auditing, safe defaults
For users who prefer direct command-line access, helper scripts are available:
bin/co-plan # Alternative to /co-plan
bin/co-create-spec # Alternative to /co-create-spec
bin/co-exec-tasks # Alternative to /co-exec-tasks
# ... etc- Frontend: React 18 + Next.js 14+ (App Router)
- Backend: FastAPI (Python) or NestJS (TypeScript)
- Database: PostgreSQL 15+ with Redis caching
- Testing: Vitest/Jest + pytest + Playwright
- DevOps: Docker + GitHub Actions
- TypeScript/JavaScript (primary)
- Python 3.11+ (services, data workflows)
- Bash (automation scripts)
Let's say you have a PRD for a "Snake Game in 3D". Here's how Codex-OS guides you through your AI assistant:
/co-plan
AI Creates:
product/mission.md— Problem statement and success metricsproduct/stack.md— Three.js + HTML5 + TypeScript decisionsproduct/roadmap.md— MVP → v1 → v1.x milestones
/co-create-spec 3D Snake Game
AI Creates:
specs/2025-08-23-3d-snake-game/srd.md— User requirementsspecs/2025-08-23-3d-snake-game/tech-spec.md— 3D architecture, controls, renderingspecs/2025-08-23-3d-snake-game/tasks.md— 12 atomic, testable tasks
/co-exec-tasks .codex-os/specs/2025-08-23-3d-snake-game
AI Implements:
- Task 1: Three.js scene setup with camera
- Task 2: Snake entity with movement physics
- Task 3: Food generation and collision detection
- ...and so on, with tests and documentation
/co-analyze
AI Generates:
- Performance analysis (60 FPS requirement met?)
- Security review (no XSS vulnerabilities)
- Code quality metrics (test coverage, complexity)
- Recommendations for optimization
🎯 The Result: A complete, production-ready 3D Snake Game built through AI collaboration, with comprehensive tests, documentation, and quality assurance—all from a simple PRD!
- Installation Guide — Automated and manual setup
- First Project — Walk through the complete workflow
- CLI Reference — All available commands
- Custom Standards — Override global defaults
- Workflow Customization — Adapt processes to your needs
- AI Integration — Enhance with Claude, GPT, etc.
We welcome contributions! Please see our contributing guidelines for details.
- 🐛 Report bugs and suggest improvements
- 📚 Improve documentation and examples
- 🔧 Add support for new languages/frameworks
- 🎨 Create new workflow templates
MIT License - see the LICENSE file for details.
If you find Codex-OS helpful, consider supporting the project:
Your support helps maintain and improve Codex-OS!
Built with Codex-OS — Turning ideas into reliable software, one spec at a time.
⭐ Star this repo if you find it useful!