burn-in-cceverywhere-codex

KO | EN

gitlite — search

#python #react #llm #go #golang #rust #deep-learning #nodejs #awesome #cli #pytorch #mcp #openai #ios

burn-in-cceverywhere-codex

(★ 12)

Autonomous agent loop for Codex CLI powered by gpt-5.2. Port of burn-in-cceverywhere-ralph with enhancements for Codex.

burn-in-cceverywhere-codex Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# burn-in-cceverywhere-codex

> **English** | [中文](#中文版本)

Autonomous agent loop for [Codex CLI](https://github.com/openai/codex) powered by gpt-5.2. Port of [burn-in-cceverywhere-ralph](https://github.com/denen99/burn-in-cceverywhere-ralph) with enhancements for Codex.

## Version

**Current: V2 (Stable)**

This is the **main** branch with V2 features (corrected migration based on Codex source code analysis). V2 replaces V1 with proper Codex-compatible implementation.

| Version | Branch | Status | Key Features |
|---------|--------|--------|--------------|
| V1 | [v1-deprecated](https://github.com/hellangleZ/burn-in-cceverywhere-codex/tree/v1-deprecated) | ⚠️ Deprecated | Had non-functional agents/rules |
| V2 | [main](https://github.com/hellangleZ/burn-in-cceverywhere-codex) | ✅ Stable | Corrected version with 7 working skills |

## Features

- **📋 Autonomous PRD Execution** - Reads prd.json and implements user stories iteratively
- **🚀 Background Mode** - Run Ralph in background with `--bg` flag and PID management
- **📊 Iteration Logging** - Detailed logs with conversation (`-c`) and summary (`-s`) views
- **💰 Token Tracking** - Automatic token usage and cost estimation with cache awareness
- **🗂️ Branch-Aware Archiving** - Automatically archives logs when switching branches
- **🤝 Multi-agents Support** - Spawn multiple AI agents for parallel task execution
- **⚡ 7 Working Skills** - Coding standards, TDD, backend/frontend patterns, security, code review
- **📖 Project Guidance** - AGENTS.md provides project-specific best practices

> **Note**: V2 is based on Codex source code analysis, removing non-functional agents/rules and providing only features that actually work in Codex.

## Installation

```bash
git clone https://github.com/hellangleZ/burn-in-cceverywhere-codex.git
cd burn-in-cceverywhere-codex
./install.sh
```

This will install:
- Ralph scripts to `~/.codex/ralph/`
- 7 skills to `~/.codex/skills/`

See [AGENTS.md](AGENTS.md) for project guidance and [TESTING_GUIDE.md](TESTING_GUIDE.md) for testing skills.

## Prerequisites

To use Multi-agents features, enable in `~/.codex/config.toml`:

```toml
[features]
multi-agents = true
```

See [docs/multi-agents.md](docs/multi-agents.md) for complete setup guide.

## Switching Between Versions

V2 is now the stable version on main branch. V1 has been deprecated due to non-functional agents/rules that don't work in Codex.

### Uninstall

```bash
rm -rf ~/.codex/ralph
rm -rf ~/.codex/skills
```

> **Note**: Uninstalling will remove all Ralph files and skills. Make sure to backup any custom modifications.

## Quick Start

1. **Create a PRD** (`prd.json`) in your project:
   ```json
   {
     "branchName": "main",
     "stories": [
       {
         "id": "STORY-001",
         "title": "Add user authentication",
         "passes": false
       }
     ]
   }
   ```

2. **Run Ralph**:
   ```bash
   ~/.codex/ralph/ralph.sh --tool codex 10
   ```

3. **Or run in background**:
   ```bash
   ~/.codex/ralph/ralph.sh --tool codex --bg 10
   ```

## Usage

### Basic Commands

```bash
# Run Ralph for N iterations
~/.codex/ralph/ralph.sh --tool codex <N>

# Run in background
~/.codex/ralph/ralph.sh --tool codex --bg <N>

# View all iteration logs
~/.codex/ralph/view-logs.sh

# View specific iteration (conversation mode)
~/.codex/ralph/view-logs.sh <N> -c

# View specific iteration (summary mode)
~/.codex/ralph/view-logs.sh <N> -s

# Stop background Ralph
kill $(cat .ralph.pid)
```

### View Logs Options

- **No arguments** - List all iterations with timestamps and token counts
- **`<N>`** - View basic summary of iteration N
- **`<N> -c`** - Conversation view (chat-like format with tool calls)
- **`<N> -s`** - Summary view (key metrics, files modified, token usage)
- **`<N> --raw`** - Raw JSONL output
- **`<N> --tools`** - Show only tool calls
- **`<N> --text`** - Show only Codex text output
- **`--search <keyword>`** - Search all logs for keyword

### Files Created

- `.ralph.pid` - Process ID for background mode
- `ralph.log` - Combined output log
- `.ralph-stats.json` - Token usage and cost statistics
- `progress.txt` - Progress log with learnings
- `logs/iteration-<N>.jsonl` - Individual iteration logs
- `logs/index.txt` - Log index with summaries
- `archive/` - Archived runs when switching branches

## Project Structure

```
burn-in-cceverywhere-codex/
├── ralph/
│   ├── ralph.sh           # Main autonomous loop script
│   ├── view-logs.sh       # Log viewer with multiple modes
│   └── AGENTS.md          # Agent instructions template
├── skills/                # Codex skills (7 total)
│   ├── backend-patterns/
│   ├── code-review-checklist/
│   ├── coding-standards/
│   ├── frontend-patterns/
│   ├── ralph/
│   ├── security-checklist/
│   └── tdd-workflow/
├── docs/                  # Documentation
├── install.sh             # Installation script
└── README.md              # This file
```

## Configuration

Ralph uses Codex CLI's standard configuration at `~/.codex/config.toml`. The skills in `~/.codex/skills/` are automatically available to Codex.

## Model

This port uses **gpt-5.2** as the primary model for all operations. Unlike the Claude Code version which has multiple model tiers (Haiku, Sonnet, Opus), Codex CLI uses gpt-5.2 as the unified model.

## Acknowledgements

### [burn-in-cceverywhere-ralph](https://github.com/denen99/burn-in-cceverywhere-ralph)
**By [@denen99](https://github.com/denen99)**

The enhanced Claude Code version combining Ralph's autonomous loop with comprehensive coding standards, background mode, and detailed iteration logging.

### [ralph](https://github.com/snarktank/ralph)
**By [@snarktank](https://github.com/snarktank)**, based on [Geoffrey Huntley's](https://ghuntley.com/) autonomous agent pattern

The original autonomous agent loop for Claude Code that reads PRDs and implements user stories iteratively, pioneering the "burn-in" approach to AI-assisted development.

### [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
**By [@affaanmustafa](https://github.com/affaan-m)**

A comprehensive collection of agents, skills, commands, and rules for Claude Code. Provides battle-tested patterns for code quality, testing, security, git workflows, and more. An invaluable resource for structuring AI-powered development workflows.

### Key Innovations

This Codex port brings together:
- Ralph's autonomous iteration model
- everything-claude-code's comprehensive ruleset
- Enhanced logging with conversation and summary modes
- Background execution with proper PID management
- Adaptation for Codex CLI architecture (AGENTS.md, gpt-5.2, ~/.codex structure)

## License

MIT

---

# 中文版本

> [English](#burn-in-cceverywhere-codex) | **中文**

基于 gpt-5.2 的 [Codex CLI](https://github.com/openai/codex) 自主代理循环。从 [burn-in-cceverywhere-ralph](https://github.com/denen99/burn-in-cceverywhere-ralph) 移植并为 Codex 增强。

## 版本

**当前版本：V2（稳定版）**

这是 **main** 分支，包含基于 Codex 源代码分析修正的 V2 版本。V2 替代了 V1，提供了正确的 Codex 兼容实现。

| 版本 | 分支 | 状态 | 主要特性 |
|------|------|------|----------|
| V1 | [v1-deprecated](https://github.com/hellangleZ/burn-in-cceverywhere-codex/tree/v1-deprecated) | ⚠️ 已弃用 | 包含不可用的agents/rules |
| V2 | [main](https://github.com/hellangleZ/burn-in-cceverywhere-codex) | ✅ 稳定 | 修正版本，7个可用skills |

## 功能特性

- **📋 自主执行 PRD** - 读取 prd.json 并迭代实现用户故事
- **🚀 后台模式** - 使用 `--bg` 标志后台运行 Ralph，支持 PID 管理
- **📊 迭代日志** - 详细日志，支持对话模式（`-c`）和摘要模式（`-s`）
- **💰 Token 追踪** - 自动统计 token 使用量和成本估算
- **🗂️ 分支感知归档** - 切换分支时自动归档日志
- **🤝 Multi-agents 支持** - 生成多个 AI 代理并行执行任务
- **⚡ 7个可用Skills** - 编码标准、TDD、后端/前端模式、安全、代码审查
- **📖 项目指导** - AGENTS.md 提供项目特定的最佳实践

> **注意**：V2 基于 Codex 源代码分析，删除了不可用的 agents/rules，仅提供在 Codex 中实际可用的功能。

## 安装

```bash
git clone https://github.com/hellangleZ/burn-in-cceverywhere-codex.git
cd burn-in-cceverywhere-codex
./install.sh
```

这将安装：
- Ralph 脚本到 `~/.codex/ralph/`
- 7个 skills 到 `~/.codex/skills/`

查看 [AGENTS.md](AGENTS.md) 了解项目指导，[TESTING_GUIDE.md](TESTING_GUIDE.md) 了解如何测试 skills。

## 前置条件

要使用 Multi-agents 功能，需在 `~/.codex/config.toml` 中启用：

```toml
[features]
multi-agents = true
```

完整设置指南请查看 [docs/multi-agents.md](docs/multi-agents.md)。

## 版本切换

V2 现在是 main 分支上的稳定版本。V1 已被弃用，因为其中的 agents/rules 在 Codex 中不可用。

### 卸载

```bash
rm -rf ~/.codex/ralph
rm -rf ~/.codex/skills
```

> **注意**：卸载将删除所有 Ralph 文件和技能。请确保备份任何自定义修改。

## 快速开始

1. **在项目中创建 PRD** (`prd.json`):
   ```json
   {
     "branchName": "main",
     "stories": [
       {
         "id": "STORY-001",
         "title": "添加用户认证",
         "passes": false
       }
     ]
   }
   ```

2. **运行 Ralph**:
   ```bash
   ~/.codex/ralph/ralph.sh --tool codex 10
   ```

3. **或在后台运行**:
   ```bash
   ~/.codex/ralph/ralph.sh --tool codex --bg 10
   ```

## 使用方法

### 基本命令

```bash
# 运行 Ralph N 次迭代
~/.codex/ralph/ralph.sh --tool codex <N>

# 后台运行
~/.codex/ralph/ralph.sh --tool codex --bg <N>

# 查看所有迭代日志
~/.codex/ralph/view-logs.sh

# 查看特定迭代（对话模式）
~/.codex/ralph/view-logs.sh <N> -c

# 查看特定迭代（摘要模式）
~/.codex/ralph/view-logs.sh <N> -s

# 停止后台 Ralph
kill $(cat .ralph.pid)
```

### 日志查看选项

- **无参数** - 列出所有迭代及时间戳和 token 统计
- **`<N>`** - 查看迭代 N 的基本摘要
- **`<N> -c`** - 对话视图（类似聊天格式，包含工具调用）
- **`<N> -s`** - 摘要视图（关键指标、修改的文件、token 使用量）
- **`<N> --raw`** - 原始 JSONL 输出
- **`<N> --tools`** - 仅显示工具调用
- **`<N> --text`** - 仅显示 Codex 文本输出
- **`--search <keyword>`** - 在所有日志中搜索关键词

### 生成的文件

- `.ralph.pid` - 后台模式的进程 ID
- `ralph.log` - 合并的输出日志
- `.ralph-stats.json` - Token 使用量和成本统计
- `progress.txt` - 进度日志及学习记录
- `logs/iteration-<N>.jsonl` - 单次迭代日志
- `logs/index.txt` - 日志索引及摘要
- `archive/` - 切换分支时的归档运行记录

## 项目结构

```
burn-in-cceverywhere-codex/
├── ralph/
│   ├── ralph.sh           # 主自主循环脚本
│   ├── view-logs.sh       # 多模式日志查看器
│   └── AGENTS.md          # 代理指令模板
├── skills/                # Codex技能（共7个）
│   ├── backend-patterns/
│   ├── code-review-checklist/
│   ├── coding-standards/
│   ├── frontend-patterns/
│   ├── ralph/
│   ├── security-checklist/
│   └── tdd-workflow/
├── docs/                  # 文档
├── install.sh             # 安装脚本
└── README.md              # 本文件
```

## 配置

Ralph 使用 Codex CLI 的标准配置文件 `~/.codex/config.toml`。`~/.codex/skills/` 中的技能会自动供 Codex 使用。

## 模型

本移植版本使用 **gpt-5.2** 作为所有操作的主要模型。与 Claude Code 版本不同（有 Haiku、Sonnet、Opus 多个模型层级），Codex CLI 使用 gpt-5.2 作为统一模型。

## 致谢

### [burn-in-cceverywhere-ralph](https://github.com/denen99/burn-in-cceverywhere-ralph)
**作者：[@denen99](https://github.com/denen99)**

增强的 Claude Code 版本，将 Ralph 的自主循环与全面的编码标准、后台模式和详细的迭代日志结合在一起。

### [ralph](https://github.com/snarktank/ralph)
**作者：[@snarktank](https://github.com/snarktank)**，基于 [Geoffrey Huntley](https://ghuntley.com/) 的自主代理模式

Claude Code 的原始自主代理循环，读取 PRD 并迭代实现用户故事，开创了 AI 辅助开发的"burn-in"方法。

### [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
**作者：[@affaanmustafa](https://github.com/affaan-m)**

Claude Code 的全面代理、技能、命令和规则集合。为代码质量、测试、安全、git 工作流等提供经过实战检验的模式。是构建 AI 驱动开发工作流的宝贵资源。

### 关键创新

本 Codex 移植版本汇集了：
- Ralph 的自主迭代模型
- everything-claude-code 的全面规则集
- 增强的日志记录（对话和摘要模式）
- 后台执行及正确的 PID 管理
- 针对 Codex CLI 架构的适配（AGENTS.md、gpt-5.2、~/.codex 结构）

## 许可证

MIT

burn-in-cceverywhere-codex

burn-in-cceverywhere-codex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

burn-in-cceverywhere-codex

burn-in-cceverywhere-codex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README