ralph-codex 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,8 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] - 2026-01-22
+- Improved README with setup, defaults, Docker guidance, and troubleshooting.
+
 ## [0.1.1] - 2026-01-22
-- Added shell completion command with bash/zsh/fish support and dynamic suggestions.
+- Added shell completion command (bash/zsh/fish) with dynamic suggestions.
 
 ## [0.1.0] - 2026-01-21
 - Initial release.

package/README.md

@@ -1,5 +1,7 @@
 # ralph-codex
 
+![ralph-codex](docs/ralph-codex.jpg)
+
 Codex-first Ralph-style planning and run loops.
 
 ## What it does
@@ -9,7 +11,14 @@ Codex-first Ralph-style planning and run loops.
 - Optional Docker mode for reproducible runs.
 - Colorized Codex output in TTY for easier scanning (disable with `NO_COLOR=1`).
 
-![Ralph Codex normal workflow](docs/ralph-codex-workflow.png)
+## How it works
+
+- `plan` asks for success criteria, runs Codex, and writes `tasks.md`.
+- `run` executes tasks until `LOOP_COMPLETE`, updating `.ralph/` state and logs.
+- `revise` adds new tasks from feedback without touching existing items.
+- `view` and `reset` help you inspect and reset task status.
+
+![Ralph Codex workflow](docs/ralph-codex-workflow.png)
 
 ## Requirements
 
@@ -17,6 +26,19 @@ Codex-first Ralph-style planning and run loops.
 - Codex CLI installed and authenticated (`codex` available in PATH)
 - Docker (optional, only for Docker mode)
 
+## Codex CLI setup
+
+Install and verify:
+
+```bash
+npm install -g @openai/codex
+codex --help
+```
+
+Authenticate using the Codex CLI and/or create a profile in `~/.codex/config.toml`.
+Follow the auth guide at https://developers.openai.com/codex/auth.
+If you use profiles, pass `--profile` or set `codex.profile` in `ralph.config.yml`.
+
 ## Install
 
 ```bash
@@ -36,6 +58,45 @@ ralph-codex view
 ralph-codex reset
 ```
 
+## Demo (sample output)
+
+```text
+$ ralph-codex plan "Add screenshot flow"
+... (interactive prompts) ...
+tasks.md written
+$ ralph-codex run
+... (loop output) ...
+LOOP_COMPLETE
+```
+
+## Cookbook
+
+### Basic flow
+
+```bash
+ralph-codex init
+ralph-codex plan "Add screenshot flow for /demo" --output tasks.md
+ralph-codex run --max-iterations 10
+```
+
+### Docker flow
+
+```bash
+ralph-codex docker
+# Ensure docker.codex_install is set in ralph.config.yml
+ralph-codex plan "Add screenshot flow for /demo"
+ralph-codex run
+```
+
+### Low-touch automation (still interactive)
+
+Use a prefilled config and pass flags to minimize prompts. This CLI still expects a TTY.
+
+```bash
+ralph-codex plan "Add screenshot flow" --full-auto --reasoning low
+ralph-codex run --full-auto --reasoning low
+```
+
 ## Command reference
 
 Use `--help` with any command to see its available options.
@@ -174,6 +235,7 @@ run:
   max_iterations: 15
   max_iteration_seconds: null
   max_total_seconds: null
+  completion_promise: LOOP_COMPLETE
 ```
 
 Codex settings quick guide:
@@ -187,6 +249,20 @@ Enable `plan.auto_detect_success_criteria` to add detected checks based on repo
 
 CLI flags always override config values.
 
+## Defaults
+
+Defaults are from the template `ralph.config.yml`.
+
+| Setting | Default | Details |
+| --- | --- | --- |
+| `plan.tasks_path` | `tasks.md` | Output path for generated tasks. |
+| `plan.auto_detect_success_criteria` | `false` | Detect and suggest checks from the repo. |
+| `run.tasks_path` | `tasks.md` | Input path for tasks during runs. |
+| `run.max_iterations` | `15` | Max loop iterations before stopping. |
+| `run.completion_promise` | `LOOP_COMPLETE` | Completion token printed by the loop. |
+| `docker.enabled` | `false` | Enable Docker execution. |
+| `docker.use_for_plan` | `false` | Run planning inside Docker too. |
+
 ## Docker mode
 
 1. Run `ralph-codex docker` to pick a base image.
@@ -194,6 +270,20 @@ CLI flags always override config values.
 3. Run `ralph-codex plan` and `ralph-codex run` as usual. Enable `docker.use_for_plan`
    if you want planning to happen inside Docker as well.
 
+Why Docker (especially with `danger-full-access`):
+- Isolation: lets you grant broad permissions inside the container without exposing your host.
+- Reproducibility: consistent OS/package stack across runs and teammates.
+- Safer cleanup: delete the container/image to reset state.
+
+Why `danger-full-access`:
+- Fewer approval prompts for tooling that needs broad filesystem or network access.
+- Works better for complex build/test flows that span many paths.
+- Faster iterations when you trust the environment (best paired with Docker).
+
+> **Warning**: Avoid `danger-full-access` on your host unless you fully trust the prompts,
+> scripts, and dependencies. It grants broad access to your machine and can write
+> outside the repo. Prefer Docker when you need this mode.
+
 `Dockerfile.ralph` is generated automatically when Docker is enabled.
 
 ## Files created
@@ -207,12 +297,24 @@ CLI flags always override config values.
 Codex output is colorized when stdout is a TTY. Plan uses spinners and run shows a task
 progress bar when interactive. Set `NO_COLOR=1` to disable color styling.
 
+## Exit codes
+
+- `0` success.
+- `1` invalid usage or runtime error.
+
 ## Troubleshooting
 
 - `codex: command not found` -> install Codex CLI and ensure it is in PATH.
+- Auth errors (401/403) -> authenticate Codex CLI or select a valid profile.
+- `Missing tasks.md` -> run `ralph-codex plan` first or pass `--tasks`.
 - Docker errors -> start Docker Desktop/Colima and retry.
-- Plan/run fail to read config -> verify `ralph.config.yml` path or pass `--config`.
+- Config read errors -> verify `ralph.config.yml` path or pass `--config`.
+
+## Changelog and license
+
+- Changelog: `CHANGELOG.md`
+- License: `LICENSE` (MIT)
 
-## License
+## Privacy
 
-MIT
+ralph-codex does not add its own telemetry. It sends prompts and context to the Codex CLI you configure; follow your Codex policies and settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-codex",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Codex-first Ralph-style planning and run loops",
   "repository": {
     "type": "git",

package/src/commands/docker.js

@@ -122,12 +122,12 @@ function runCodex(prompt, codexConfig) {
 
 function buildPrompt(nodeVersion) {
   const nodeLine = nodeVersion ? `Node version: ${nodeVersion}` : "Node 20+";
-  return `Encuentra la mejor imagen base de Docker para este proyecto.
-Considera que necesita ejecutar npm scripts, módulos nativos y evitar Alpine.
+  return `Find the best Docker base image for this project.
+Consider that it needs to run npm scripts, native modules, and should avoid Alpine.
 ${nodeLine}
 
-Responde SOLO con una línea en este formato:
-BASE_IMAGE: <imagen>`;
+Respond with a single line in this format:
+BASE_IMAGE: <image>`;
 }
 
 async function main() {

package/src/commands/plan.js

@@ -675,6 +675,7 @@ Context scan (read-only):
   pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle, Makefile,
   .nvmrc, Dockerfile, etc. Only inspect files that exist.
 - Use this context to infer file locations, tooling, and sensible commands.
+ - You may use read-only commands like ls, rg, and cat to inspect files.
 
 Requirements:
 - If there are open questions, ask them first and do not write ${tasksPath}.
@@ -693,13 +694,18 @@ Requirements:
 - Tasks must be atomic, ordered, and verifiable. Include exact file paths,
   commands to run (if any), and expected outcomes. Avoid vague verbs like "handle" or "improve".
 - Keep scope minimal: avoid refactors unless required by the idea or to unblock tasks.
+- Use this exact section order and headings in ${tasksPath}:
+  1) # Tasks
+  2) ## Assumptions (only if needed)
+  3) ## Success criteria
+  4) ## Required tools
 ${successCriteriaBlock}
 - Include a "Required tools" section using this exact format:
   - \`- apt: <comma-separated packages or none>\`
   - \`- npm: <comma-separated packages or none>\`
   - \`- pip: <comma-separated packages or none>\`
 - Do not edit any files other than ${tasksPath}.
-- Do not run commands, tests, or start dev servers during planning.
+- Do not run write commands, tests, installs, or start dev servers during planning.
 
 When done, output exactly: LOOP_COMPLETE
 `;

package/src/commands/run.js

@@ -356,6 +356,8 @@ ${result.output}
 Constraints:
 - Only edit ${dockerConfig.dockerfile}
 - Do not change other files
+- Keep the existing base image unless the error requires changing it
+- Do not add new dependencies unless required by the error
 - Do not ask questions
 - Output exactly: LOOP_COMPLETE
 `;