{"id":30656022,"url":"https://github.com/forsonny/codex-os","last_synced_at":"2025-08-31T10:04:29.345Z","repository":{"id":311358386,"uuid":"1043389765","full_name":"forsonny/Codex-OS","owner":"forsonny","description":"Codex CLI development framework that transforms product ideas into production-ready software through structured workflows and seamless Codex CLI integration.","archived":false,"fork":false,"pushed_at":"2025-08-24T02:06:55.000Z","size":189,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T10:26:28.435Z","etag":null,"topics":["ai-assistant","ai-development","code-generation","codex-cli","codexcli","development-framework","openai","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"https://ko-fi.com/forsonny","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forsonny.png","metadata":{"files":{"readme":"docs/readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-23T18:46:09.000Z","updated_at":"2025-08-24T10:11:11.000Z","dependencies_parsed_at":"2025-08-24T10:37:13.271Z","dependency_job_id":"7c14d5df-62bf-404a-8575-b0c2bdebc011","html_url":"https://github.com/forsonny/Codex-OS","commit_stats":null,"previous_names":["forsonny/codex-os"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/forsonny/Codex-OS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forsonny%2FCodex-OS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forsonny%2FCodex-OS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forsonny%2FCodex-OS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forsonny%2FCodex-OS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forsonny","download_url":"https://codeload.github.com/forsonny/Codex-OS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forsonny%2FCodex-OS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272965497,"owners_count":25023071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","ai-development","code-generation","codex-cli","codexcli","development-framework","openai","vibe-coding","vibecoding"],"created_at":"2025-08-31T10:03:34.412Z","updated_at":"2025-08-31T10:04:29.339Z","avatar_url":"https://github.com/forsonny.png","language":"Shell","funding_links":["https://ko-fi.com/A0A11JWH8S"],"categories":[],"sub_categories":[],"readme":"# Codex-OS\n\n**An AI-powered development framework that transforms product ideas into production-ready software through intelligent workflows, consistent standards, and seamless AI assistant integration.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n\n---\n\n## 🎯 Why Codex-OS?\n\n**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.\n\n**The Solution:** Codex-OS provides an **AI-powered development framework** that guides you from initial product requirements to production deployment with:\n\n- 🤖 **AI-First Workflows** — Work naturally with AI assistants using simple commands\n- 📋 **Structured Planning** — Turn PRDs into actionable technical specs\n- 🔄 **Consistent Processes** — Repeatable workflows for every development phase  \n- 🛡️ **Safety by Default** — Built-in quality gates and rollback strategies\n- 📚 **Living Documentation** — Auto-updating specs and decision records\n\n## 🚀 Quick Start\n\n### Installation\n\n#### Option 1: Automated Installation (Recommended)\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/forsonny/codex-os\n   cd codex-os\n   ```\n\n2. **Run the installation script**:\n   ```bash\n   chmod +x scripts/install-global.sh\n   ./scripts/install-global.sh\n   ```\n   \n   This script will:\n   - Move global files to `~/.codex-os/`\n   - Backup and install AGENTS.md to `~/.codex/`\n   - Clean up placeholder directories\n   - Verify the installation\n\n3. **Make helper scripts executable**:\n   ```bash\n   chmod +x bin/co-*\n   ```\n\n4. **Install dependencies** (if using the TypeScript/JavaScript stack):\n   ```bash\n   npm install  # or pnpm install\n   ```\n\n#### Option 2: Manual Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/forsonny/codex-os\n   cd codex-os\n   ```\n\n2. **Move global files to your home directory**:\n   ```bash\n   # Create the target directories\n   mkdir -p ~/.codex-os\n   mkdir -p ~/.codex\n   \n   # Move the CONTENTS of the global Codex-OS folder\n   mv \"move to HOME/.codex-os\"/* ~/.codex-os/\n   \n   # Backup existing AGENTS.md if it exists\n   if [ -f ~/.codex/AGENTS.md ]; then\n     cp ~/.codex/AGENTS.md ~/.codex/AGENTS.md.backup.$(date +%Y%m%d_%H%M%S)\n     echo \"Backed up existing AGENTS.md to ~/.codex/AGENTS.md.backup.$(date +%Y%m%d_%H%M%S)\"\n   fi\n   \n   # Move new AGENTS.md to ~/.codex directory\n   mv \"move to HOME/.codex/AGENTS.md\" ~/.codex/AGENTS.md\n   ```\n\n3. **Clean up placeholder directories**:\n   ```bash\n   # Remove the now-empty placeholder directories\n   rmdir \"move to HOME/.codex-os/instructions/core\"\n   rmdir \"move to HOME/.codex-os/instructions\"\n   rmdir \"move to HOME/.codex-os/standards/code-style\"\n   rmdir \"move to HOME/.codex-os/standards\"\n   rmdir \"move to HOME/.codex-os/product\"\n   rmdir \"move to HOME/.codex-os\"\n   rmdir \"move to HOME/.codex\"\n   rmdir \"move to HOME\"\n   ```\n\n4. **Make helper scripts executable**:\n   ```bash\n   chmod +x bin/co-*\n   ```\n\n5. **Install dependencies** (if using the TypeScript/JavaScript stack):\n   ```bash\n   npm install  # or pnpm install\n   ```\n\n### Your First Project\n\nYou 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.\n\n**Work with your AI assistant using these commands:**\n\n```\n/co-plan\n```\n*Plan your product from requirements*\n\n```\n/co-create-spec User Authentication System\n```\n\u003e **💡 Pro Tip:** Use `/co-create-spec` to create a spec for the full project based on srd.md\n\n*Create a technical specification*\n\n```\n/co-exec-tasks .codex-os/specs/2025-08-23-user-authentication-system\n```\n*Execute the implementation*\n\n```\n/co-exec-task [TASK-ID]\n```\n*Execute excate task*\n\n```\n/co-analyze\n```\n*Analyze your codebase health*\n\n\u003e **💡 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!\n\n## 🏗️ How It Works\n\nCodex-OS is an **AI-powered development framework** that guides you through a proven workflow:\n\n```\nPRD/Idea → /co-plan → /co-create-spec → /co-exec-tasks → /co-analyze → Deploy\n    ↓          ↓           ↓              ↓            ↓          ↓\n  Goals → Roadmap → Specification → Implementation → Health → Production\n```\n\n### 1. **`/co-plan`** 📋\n*Transform raw product requirements into structured documentation*\n- Mission and success metrics\n- Technology stack decisions  \n- Roadmap with milestones\n- Architecture decision records (ADRs)\n\n### 2. **`/co-create-spec`** 📝\n*Convert plans into actionable technical specifications*\n- Software Requirements Document (SRD)\n- Technical architecture and APIs\n- Prioritized task breakdown with acceptance criteria\n\n### 3. **`/co-exec-tasks`** ⚡\n*Implement features safely with automated quality gates*\n- Test-driven development\n- Small, atomic commits\n- Continuous integration\n- Documentation updates\n\n### 4. **`/co-analyze`** 🔍\n*Monitor codebase health and identify improvements*\n- Architecture analysis\n- Risk assessment\n- Performance bottlenecks\n- Actionable recommendations\n\n\u003e **🤖 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.\n\n## 🛠️ Core Features\n\n### 🤖 **AI-Powered Commands**\nThe primary way to interact with Codex-OS is through AI assistant commands:\n\n| Command | Purpose |\n|---------|---------|\n| `/co-plan` | Update product documentation from requirements |\n| `/co-create-spec [title]` | Generate new feature specifications |\n| `/co-exec-tasks [spec-path]` | Execute all tasks in a specification |\n| `/co-exec-task [task-id]` | Execute a single task with minimal changes |\n| `/co-analyze` | Analyze codebase health and generate reports |\n\n*These commands integrate seamlessly with Claude, GPT, and other AI assistants through the global `AGENTS.md` configuration.*\n\n### 📁 **Intelligent Project Structure**\n```\n.codex-os/\n├── product/         # Mission, roadmap, decisions, stack\n├── specs/          # Feature specifications with tasks\n└── standards/      # Coding standards and best practices\n```\n\n### 🎨 **Opinionated but Flexible Standards**\n- **TypeScript/JavaScript**: Prettier + ESLint with strict mode\n- **Python**: Black + Ruff with comprehensive type hints  \n- **Testing**: Unit → Integration → E2E pyramid\n- **Git**: Conventional Commits with semantic versioning\n- **Security**: Secret scanning, dependency auditing, safe defaults\n\n### 🔧 **Optional CLI Tools**\nFor users who prefer direct command-line access, helper scripts are available:\n```bash\nbin/co-plan              # Alternative to /co-plan\nbin/co-create-spec       # Alternative to /co-create-spec\nbin/co-exec-tasks        # Alternative to /co-exec-tasks\n# ... etc\n```\n\n## 🏗️ Technology Stack\n\n### **Default Full-Stack Web**\n- **Frontend**: React 18 + Next.js 14+ (App Router)\n- **Backend**: FastAPI (Python) or NestJS (TypeScript)\n- **Database**: PostgreSQL 15+ with Redis caching\n- **Testing**: Vitest/Jest + pytest + Playwright\n- **DevOps**: Docker + GitHub Actions\n\n### **Supported Languages**\n- **TypeScript/JavaScript** (primary)\n- **Python 3.11+** (services, data workflows)  \n- **Bash** (automation scripts)\n\n## 📖 Real-World Example\n\nLet's say you have a PRD for a \"Snake Game in 3D\". Here's how Codex-OS guides you through your AI assistant:\n\n### 1. Planning Phase\n```\n/co-plan\n```\n**AI Creates:**\n- `product/mission.md` — Problem statement and success metrics\n- `product/stack.md` — Three.js + HTML5 + TypeScript decisions\n- `product/roadmap.md` — MVP → v1 → v1.x milestones\n\n### 2. Specification Phase  \n```\n/co-create-spec 3D Snake Game\n```\n**AI Creates:**\n- `specs/2025-08-23-3d-snake-game/srd.md` — User requirements\n- `specs/2025-08-23-3d-snake-game/tech-spec.md` — 3D architecture, controls, rendering\n- `specs/2025-08-23-3d-snake-game/tasks.md` — 12 atomic, testable tasks\n\n### 3. Execution Phase\n```\n/co-exec-tasks .codex-os/specs/2025-08-23-3d-snake-game\n```\n**AI Implements:**\n- Task 1: Three.js scene setup with camera\n- Task 2: Snake entity with movement physics  \n- Task 3: Food generation and collision detection\n- ...and so on, with tests and documentation\n\n### 4. Analysis Phase\n```\n/co-analyze\n```\n**AI Generates:**\n- Performance analysis (60 FPS requirement met?)\n- Security review (no XSS vulnerabilities)\n- Code quality metrics (test coverage, complexity)\n- Recommendations for optimization\n\n\u003e **🎯 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!\n\n## 📚 Documentation\n\n### **Getting Started**\n- [Installation Guide](#installation) — Automated and manual setup\n- [First Project](#your-first-project) — Walk through the complete workflow\n- [CLI Reference](#powerful-cli-tools) — All available commands\n\n### **Advanced Usage**  \n- [Custom Standards](/.codex-os/standards/) — Override global defaults\n- [Workflow Customization](/.codex-os/instructions/) — Adapt processes to your needs\n- [AI Integration](/move%20to%20HOME/.codex/AGENTS.md) — Enhance with Claude, GPT, etc.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.\n\n### **Ways to Contribute**\n- 🐛 Report bugs and suggest improvements\n- 📚 Improve documentation and examples  \n- 🔧 Add support for new languages/frameworks\n- 🎨 Create new workflow templates\n\n## 📄 License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Support Codex-OS\n\nIf you find Codex-OS helpful, consider supporting the project:\n\n[![ko-fi](https://github.com/forsonny/book-os/raw/main/assets/support_me_on_kofi_badge_blue.webp)](https://ko-fi.com/A0A11JWH8S)\n\nYour support helps maintain and improve Codex-OS!\n\n---\n\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with Codex-OS** — *Turning ideas into reliable software, one spec at a time.*\n\n[⭐ Star this repo](https://github.com/forsonny/codex-os) if you find it useful!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforsonny%2Fcodex-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforsonny%2Fcodex-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforsonny%2Fcodex-os/lists"}