Library Overview

simple-codex

simple-codex standardizes Codex CLI usage in this repository for predictable and reproducible AI-assisted development workflows.

It bundles shared configuration, role-based prompts, reusable agent skills, and environment validation into one practical flow.

Project Intro and Purpose

What it is

A lightweight orchestration layer around Codex CLI that keeps team usage consistent per project scope.

Why it exists

It separates planning, implementation, and review responsibilities so outputs are easier to validate and reuse.

Core value

One command, fixed role order, and explicit handoff data reduce drift in collaborative coding sessions.

Installation by Package Manager

Copy and run one command below. The package name is simple-codex.

pnpm

pnpm add -D simple-codex

npm

npm install --save-dev simple-codex

yarn

yarn add -D simple-codex

bun

bun add -d simple-codex

Usage

Use setup and doctor first, then run workflow with mode options. You can also add or list custom prompts with the prompt commands.

1. Setup project files

Creates the shared project directories, prompt templates, skill templates, and AGENTS.md for the selected scope.

scodex setup --scope project

2. Check installation status

Verifies that required folders, prompt files, skills, config, and AGENTS.md are present and ready to use.

scodex doctor --scope project

3. Run the workflow

Use mode new/resume/replay to control execution. If run-id is omitted in resume/replay, it defaults to LATEST.

scodex workflow --scope project --mode new --task "<task>"

4. Resume or replay a run

Resume continues a stopped run, replay creates a new run from a previous run's task.

scodex workflow --scope project --mode resume --run-id <run-id>
scodex workflow --scope project --mode replay

5. Check persisted state files

Run states are saved under .myx/workflow-runs with a per-run state.json and a LATEST pointer.

.myx/workflow-runs/
  LATEST
  <run-id>/state.json

6. Add a prompt

Creates a new prompt markdown file in the project prompt directory so you can define an additional reusable role.

scodex prompt add demo --scope project

7. List prompts

Shows the prompt files currently installed for the selected scope so you can inspect available roles.

scodex prompt list --scope project
1

architect

Analyzes requirements and proposes an implementation-ready plan without editing files.

2

executor

Implements changes from the architect output, validates results, and reports concise diffs.

3

review

Checks coverage and quality using both architect and executor outputs with severity-ranked issues.

Example

Sample task input

Update README and index.html to document workflow mode and run-id.

Expected flow

new: run workflow with task, then save state to .myx/workflow-runs/<run-id>/state.json.
resume: continue the same run from the first non-succeeded step by run-id or LATEST.
replay: start a fresh run from a previous run with the same or overridden task.