Content
# Codex Loop Skill
[English](README.en.md)
Based on the [Codex app-server](https://github.com/openai/codex) MCP service (`codex-mcp-server`), comes with a distributable **Codex Loop Skill**, used for orchestrating multi-threaded development workflows in Hermes (new features, bug fixes, refactoring, PR reviews, batch issue fixes).
**Quick Start:** [Installation Process](#installation-process)
## Project Composition
| Path | Description |
|------|------|
| `src/` | Rust MCP service (`codex-mcp-server`) |
| `skills/codex-loop/` | Agent Skill source code (workflow documentation + MCP configuration template) |
## Installation Process
Complete installation in Hermes: import skill package → register bundled MCP server → verification → reload tool in session.
### Prerequisites
| Dependency | Description |
|------|------|
| Hermes | CLI and runtime installed, `hermes` in PATH |
| [codex CLI](https://github.com/openai/codex) | Host machine must be installed; MCP connects to Codex app-server via stdio |
| Corresponding platform `.skill` package | Package contains compiled binary, Release installation does not require Rust toolchain |
### Step 1: Download Skill Package
Choose the file that matches your machine from [GitHub Releases](https://github.com/xinjiyuan97/codex-skill/releases):
| Platform | Release Resource |
|------|-------------|
| macOS Apple Silicon | `codex-loop-macos-aarch64.skill` |
| macOS Intel | `codex-loop-macos-x86_64.skill` |
| Linux x86_64 | `codex-loop-linux-x86_64.skill` |
| Windows x86_64 | `codex-loop-windows-x86_64.skill` |
### Step 2: Install Skill in Hermes
Import/install `.skill` package according to Hermes documentation. Note the skill root directory path after installation, referred to as `<skill-root>` below.
The package contains:
- `SKILL.md` — Workflow orchestration
- `assets/bin/codex-mcp-server` — Platform-specific MCP binary
- `scripts/setup.sh` — MCP configuration auxiliary script
- `assets/mcp-config.example.yaml` — Configuration template
### Step 3: Configure MCP (user manual, one-time)
Agent **cannot** modify `~/.hermes/config.yaml`, please execute in the terminal:
```bash
cd <skill-root>
chmod +x scripts/setup.sh
# Verify codex CLI and bundled binary
./scripts/setup.sh --verify
```
**Method A — Hermes CLI (recommended)**
```bash
./scripts/setup.sh --install
```
Select in the interactive tool selection interface:
- Tools: `start`, `reply`, `process`, `archive`
- Resources: **Enable** (`project://`, `thread://`)
- Prompts: **Disable**
**Method B — Manual modification of config.yaml**
```bash
./scripts/setup.sh --print-config
```
Merge the output into `~/.hermes/config.yaml`'s `mcp_servers.codex`, or refer to `assets/mcp-config.example.yaml`, and change `command` to the **absolute path** of `assets/bin/codex-mcp-server`.
### Step 4: Verification
```bash
hermes mcp test codex
./scripts/setup.sh --verify
```
Confirm the following:
- [ ] `hermes mcp list` contains `codex` and is enabled
- [ ] `hermes mcp test codex` succeeds
- [ ] After completing step 5, Agent tool list contains `mcp_codex_start`, `mcp_codex_reply`, `mcp_codex_process`, `mcp_codex_archive`
See `skills/codex-loop/references/troubleshooting.md` in case of failure.
### Step 5: Reload MCP in Hermes
Execute in the current Hermes session:
```
/reload-mcp
```
Or open a new session. When `mcp_codex_*` tools appear, you can use the **Codex Loop Skill**.
### Installation from Source (development)
For contributors or local builds, not using Release packages:
```bash
git clone https://github.com/xinjiyuan97/codex-skill.git
cd codex-skill
cargo test
cargo build --release
# Package local `.skill` (select os_name by platform)
./scripts/package-skill.sh macos-aarch64 target/release/codex-mcp-server dist
# → dist/codex-loop-macos-aarch64.skill
# Install dist/*.skill in Hermes, then execute steps 3-5 above.
# Or directly link skill source code, MCP points to local compilation product:
ln -s "$(pwd)/skills/codex-loop" ~/.hermes/skills/codex-loop # Path according to your Hermes configuration
./skills/codex-loop/scripts/setup.sh --print-config
```
In development mode, `config.yaml`'s `command` should point to `target/release/codex-mcp-server` (absolute path).
## MCP Service
Expose Codex thread lifecycle management through MCP:
| Tool | Purpose |
|------|------|
| `start` | Create thread, pass in `description` + `prompt` |
| `reply` | Continue conversation on existing thread |
| `process` | View execution trajectory and status |
| `archive` | Archive and remove thread from list |
Resources:
- `project://{project_id}` — List threads by working directory
- `thread://{project_id}/{thread_id}` — Thread details (local state + remote Codex data)
Host machine needs to install `codex` CLI. MCP binary communicates with Codex app-server via stdio.
### Local Development
```bash
cargo test
cargo build --release
./target/release/codex-mcp-server
```
Manually configure Hermes MCP or use `skills/codex-loop/assets/mcp-config.example.yaml` as a template.
Environment Variables:
| Variable | Optional Values | Default Value |
|------|--------|--------|
| `CODEX_MCP_APPROVAL_POLICY` | `approve`, `session`, `deny` | `approve` |
## Workflow
**Hermes**-oriented Agent Skill, orchestrating Codex development cycle through `mcp_codex_*` tools:
1. Classify tasks → create git branch (`feature/`, `bugfix/`, `refactor/`)
2. Call `mcp_codex_start` to create Codex thread with complete markdown requirements
3. Verify results → correct with `mcp_codex_reply` on the same thread
4. Split complex tasks into multiple threads; PR review, worktree parallel repair, batch review see SKILL.md
5. Track progress with `mcp_codex_process` and MCP resources
Complete workflow see `skills/codex-loop/SKILL.md`, examples see `skills/codex-loop/examples.md`.
Installation steps see [Installation Process](#installation-process).
### Local Packaging Skill
```bash
cargo build --release
./scripts/package-skill.sh macos-aarch64 target/release/codex-mcp-server dist
# → dist/codex-loop-macos-aarch64.skill
```
## CI / Release
GitHub Actions workflow `.github/workflows/build-skill.yml`:
- Compile `codex-mcp-server` for macOS (aarch64 + x86_64), Linux, Windows
- Package platform-specific `.skill` archives
- Automatically create GitHub Release when `v*` tag is pushed
## Directory Structure
```
.
├── src/ # MCP service source code
├── skills/codex-loop/ # Skill source code
│ ├── SKILL.md
│ ├── examples.md
│ ├── scripts/setup.sh # MCP configuration auxiliary script
│ ├── references/ # MCP configuration, tool list, troubleshooting
│ └── assets/
│ ├── mcp-config.example.yaml
│ └── bin/ # Binary injected during packaging
├── scripts/package-skill.sh
└── .github/workflows/build-skill.yml
```
## License
MIT
