https://github.com/forsonny/codex-os
Codex CLI development framework that transforms product ideas into production-ready software through structured workflows and seamless Codex CLI integration.
https://github.com/forsonny/codex-os
ai-assistant ai-development code-generation codex-cli codexcli development-framework openai vibe-coding vibecoding
Last synced: about 1 month ago
JSON representation
Codex CLI development framework that transforms product ideas into production-ready software through structured workflows and seamless Codex CLI integration.
- Host: GitHub
- URL: https://github.com/forsonny/codex-os
- Owner: forsonny
- Created: 2025-08-23T18:46:09.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-08-24T02:06:55.000Z (about 1 month ago)
- Last Synced: 2025-08-24T10:26:28.435Z (about 1 month ago)
- Topics: ai-assistant, ai-development, code-generation, codex-cli, codexcli, development-framework, openai, vibe-coding, vibecoding
- Language: Shell
- Homepage: https://ko-fi.com/forsonny
- Size: 185 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: docs/readme.md
Awesome Lists containing this project
README
# Codex-OS
**An AI-powered development framework that transforms product ideas into production-ready software through intelligent workflows, consistent standards, and seamless AI assistant integration.**
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://www.python.org/)---
## π― Why Codex-OS?
**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## π Quick Start
### Installation
#### Option 1: Automated Installation (Recommended)
1. **Clone the repository**:
```bash
git clone https://github.com/forsonny/codex-os
cd codex-os
```2. **Run the installation script**:
```bash
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 installation3. **Make helper scripts executable**:
```bash
chmod +x bin/co-*
```4. **Install dependencies** (if using the TypeScript/JavaScript stack):
```bash
npm install # or pnpm install
```#### Option 2: Manual Installation
1. **Clone the repository**:
```bash
git clone https://github.com/forsonny/codex-os
cd codex-os
```2. **Move global files to your home directory**:
```bash
# 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
```3. **Clean up placeholder directories**:
```bash
# 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"
```4. **Make helper scripts executable**:
```bash
chmod +x bin/co-*
```5. **Install dependencies** (if using the TypeScript/JavaScript stack):
```bash
npm install # or pnpm install
```### Your First Project
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-spec` to 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!
## ποΈ How It Works
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
```### 1. **`/co-plan`** π
*Transform raw product requirements into structured documentation*
- Mission and success metrics
- Technology stack decisions
- Roadmap with milestones
- Architecture decision records (ADRs)### 2. **`/co-create-spec`** π
*Convert plans into actionable technical specifications*
- Software Requirements Document (SRD)
- Technical architecture and APIs
- Prioritized task breakdown with acceptance criteria### 3. **`/co-exec-tasks`** β‘
*Implement features safely with automated quality gates*
- Test-driven development
- Small, atomic commits
- Continuous integration
- Documentation updates### 4. **`/co-analyze`** π
*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.
## π οΈ Core Features
### π€ **AI-Powered Commands**
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.*
### π **Intelligent Project Structure**
```
.codex-os/
βββ product/ # Mission, roadmap, decisions, stack
βββ specs/ # Feature specifications with tasks
βββ standards/ # Coding standards and best practices
```### π¨ **Opinionated but Flexible Standards**
- **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### π§ **Optional CLI Tools**
For users who prefer direct command-line access, helper scripts are available:
```bash
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
```## ποΈ Technology Stack
### **Default Full-Stack Web**
- **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### **Supported Languages**
- **TypeScript/JavaScript** (primary)
- **Python 3.11+** (services, data workflows)
- **Bash** (automation scripts)## π Real-World Example
Let's say you have a PRD for a "Snake Game in 3D". Here's how Codex-OS guides you through your AI assistant:
### 1. Planning Phase
```
/co-plan
```
**AI Creates:**
- `product/mission.md` β Problem statement and success metrics
- `product/stack.md` β Three.js + HTML5 + TypeScript decisions
- `product/roadmap.md` β MVP β v1 β v1.x milestones### 2. Specification Phase
```
/co-create-spec 3D Snake Game
```
**AI Creates:**
- `specs/2025-08-23-3d-snake-game/srd.md` β User requirements
- `specs/2025-08-23-3d-snake-game/tech-spec.md` β 3D architecture, controls, rendering
- `specs/2025-08-23-3d-snake-game/tasks.md` β 12 atomic, testable tasks### 3. Execution Phase
```
/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### 4. Analysis Phase
```
/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!
## π Documentation
### **Getting Started**
- [Installation Guide](#installation) β Automated and manual setup
- [First Project](#your-first-project) β Walk through the complete workflow
- [CLI Reference](#powerful-cli-tools) β All available commands### **Advanced Usage**
- [Custom Standards](/.codex-os/standards/) β Override global defaults
- [Workflow Customization](/.codex-os/instructions/) β Adapt processes to your needs
- [AI Integration](/move%20to%20HOME/.codex/AGENTS.md) β Enhance with Claude, GPT, etc.## π€ Contributing
We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
### **Ways to Contribute**
- π Report bugs and suggest improvements
- π Improve documentation and examples
- π§ Add support for new languages/frameworks
- π¨ Create new workflow templates## π License
MIT License - see the [LICENSE](LICENSE) file for details.
---
## Support Codex-OS
If you find Codex-OS helpful, consider supporting the project:
[](https://ko-fi.com/A0A11JWH8S)
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](https://github.com/forsonny/codex-os) if you find it useful!