# Humanize: A Claude Code Plugin That Adds Independent Codex Review to Iterative Development Loops

> Humanize is an MIT-licensed Claude Code plugin that runs the RLCR (Ralph-Loop with Codex Review) pattern: Claude implements, an independent Codex instance reviews, and the loop continues until all acceptance criteria in a plan file are met.

**PolyArch/humanize** — From Automated Idea Factory to Realization

- Repository: https://github.com/PolyArch/humanize
- Stars: 1,463 · Forks: 130
- Language: Shell
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/polyarch-humanize

## What RLCR Solves: Independent Review in a Development Loop

AI-assisted coding with a single model has a known weakness: the same model that wrote the code tends to approve it. When Claude generates a function and is then asked to review it, it applies the same reasoning patterns it used to create it, which means systematic blind spots carry through to the review.

Humanize breaks this by introducing an independent reviewer. Claude implements, and then a separate Codex instance reviews the output without seeing how it was generated. The reviews include severity markers, and the implementation phase uses those findings as input for the next iteration. The loop continues until the plan's acceptance criteria are met or no further issues are found.

The project derives this idea from what its README calls the ralph-loop plugin pattern. RLCR extends that pattern by replacing a simple loop with a two-phase cycle: an Implementation phase where Claude works and Codex reviews summaries, and a Code Review phase where Codex examines code quality with severity markers. The README also reads RLCR as "Reinforcement Learning with Code Review," describing the iterative cycle where AI-generated code is continuously refined through external review feedback.

The README also emphasizes the "Begin with the End in Mind" principle: before the loop starts, Humanize verifies that the developer understands the plan they are about to execute. The plugin requires human sign-off on the plan, keeping the developer as the architect while the AI handles implementation.

## Installation from the PolyArch Marketplace

Humanize is installed as a Claude Code plugin from the PolyArch marketplace. The installation requires Claude Code to be running.

First, add the PolyArch marketplace:

```bash
/plugin marketplace add PolyArch/humanize
```

Then install the plugin:

```bash
/plugin install humanize@PolyArch
```

To use the experimental development branch instead of the stable version:

```bash
/plugin marketplace add PolyArch/humanize#dev
```

Humanize requires the codex CLI to be installed and accessible. The README links to openai/codex for setup instructions. Without the codex CLI, the review phase cannot run.

The plugin is at version 1.16.0 as stated in the README. The top-level repository structure includes `.claude-plugin/` and `.claude/` directories, which contain the Claude Code plugin configuration and skill definitions. The `commands/` directory holds the slash commands the plugin registers.

## Running the RLCR Loop: Four Commands from Idea to Implementation

The workflow has four main steps.

First, generate an idea draft from a loose description (this step is optional if you already have a detailed plan):

```bash
/humanize:gen-idea "add undo/redo to the editor"
```

The output goes to `.humanize/ideas/<slug>-<timestamp>.md` by default. The `--n` flag controls how many parallel directions the idea generation explores; the default is 6.

Second, generate a structured plan from the draft:

```bash
/humanize:gen-plan --input draft.md --output docs/plan.md
```

Third, if reviewers have annotated the plan with comments in the `CMT:` or `<comment>` format, refine it:

```bash
/humanize:refine-plan --input docs/plan.md
```

Fourth, run the loop against the plan:

```bash
/humanize:start-rlcr-loop docs/plan.md
```

The loop runs until all acceptance criteria in the plan are met. The Gemini CLI integration provides a deep web research capability for lookup-heavy tasks:

```bash
/humanize:ask-gemini What are the latest best practices for X?
```

This requires the Gemini CLI to be installed separately.

## Monitoring the Loop in Real Time

Because the RLCR loop runs inside Claude Code but invokes Codex as a separate process, monitoring output accumulates in separate streams. Humanize provides a shell monitoring tool for watching these streams in another terminal.

First, source the monitoring script:

```bash
source <path/to/humanize>/scripts/humanize.sh
```

Then monitor the stream of interest:

```bash
humanize monitor rlcr
```

Other monitor targets include `skill` for all skill invocations, `codex` for Codex calls only, and `gemini` for Gemini calls only. The README explicitly notes that the monitoring command should be run in a separate terminal, not inside the active Claude Code session.

The monitor dashboard gives real-time visibility into what phase the loop is in, which acceptance criteria remain unresolved, and what the last Codex review found. This is particularly useful for long-running plans where the loop may run for many iterations before completing.

## How the Two-Phase Review Cycle Works

The loop has two alternating phases. In the Implementation phase, Claude receives the plan and any existing Codex review findings. It writes or revises code. Codex receives summaries of what Claude implemented and flags issues at a high level.

In the Code Review phase, Codex inspects the actual code files with severity markers. Issues classified above a configured severity threshold feed back into the next Implementation phase as requirements.

The README describes this as "One Build + One Review: Claude implements, Codex independently reviews. No blind spots." The independence is the key design property: Codex has no access to Claude's reasoning during the Implementation phase, which means it applies its own evaluation criteria rather than reasoning backward from how the code was generated.

The README mentions an optional Agent Teams mode that parallelizes multiple implementation workers using Claude Code's swarm capability. This mode is described as experimental under the Swarm Mode heading.

## Bitter Lesson Workflow and Gemini Integration

The `docs/bitlesson.md` file documents a workflow called Bitter Lesson, which covers project memory, selector routing, and delta validation. The README describes it as a project memory system distinct from the basic RLCR loop. It appears to be a more advanced workflow for projects that accumulate context over time.

The Gemini CLI integration allows the RLCR loop to consult Gemini for web research tasks. The `/humanize:ask-gemini` command sends a query to the Gemini CLI and returns results that can be incorporated into plan refinement or implementation. This is documented as a separate step rather than as part of the automatic loop, meaning the developer chooses when to invoke deep research.

The `skills/` directory in the repository holds skill definitions for Codex, Gemini, and Kimi (another LLM provider). The README links to separate installation guides for each: `docs/install-for-codex.md`, `docs/install-for-gemini.md` (actually `docs/install-for-kimi.md` in the README), and `docs/install-for-claude.md`.

The top-level `agents/` directory suggests that Humanize also supports defining and running specialized sub-agents for particular task types within the loop.

## Limitations, Dependencies, and Humanize2

Humanize has two hard external dependencies beyond Claude Code: the codex CLI for the review phase, and optionally the Gemini CLI for research tasks. The codex CLI dependency means that the core RLCR review mechanism requires access to an OpenAI Codex model or a compatible endpoint. If that access is unavailable or too expensive for frequent use, the review phase effectively becomes inactive.

The README mentions that Humanize2 is under active development at a separate repository (humanfia/humanize2) and is seeking user feedback. This suggests that the current 1.16.0 codebase is not the long-term maintained version. Teams adopting Humanize should monitor the Humanize2 development timeline and plan for a migration when it stabilizes.

The last push to the PolyArch/humanize repository was on 2026-08-28. The project is licensed under MIT. The `tests/` directory appears in the top-level structure, indicating some test coverage exists, though the README does not document the test suite.

## Conclusion

Humanize is the right tool for Claude Code users who find that single-pass code generation produces output that passes their own review but misses structural issues that an independent reviewer would catch. The dependency on the codex CLI is a hard requirement: without it, the review phase does not run and the plugin falls back to implementation-only loops. Before adopting it for team use, check whether Codex review latency is acceptable for your typical plan size, since each iteration involves two separate AI calls and monitoring output accumulates in the `.humanize/` directory.

## FAQ

### What does Humanize require beyond Claude Code?

Humanize requires the codex CLI for the Codex review phase. Without it, the review step in the RLCR loop cannot run. The Gemini CLI is optional and enables the /humanize:ask-gemini deep research command. The plugin is installed through Claude Code's plugin system using the PolyArch marketplace.

### What is the difference between Humanize and using Claude Code alone?

Claude Code alone generates code in a single pass. Humanize adds an iterative loop where an independent Codex instance reviews the generated code with severity markers, and those findings feed back into the next implementation round. The loop continues until the plan's acceptance criteria are satisfied.

### Where does Humanize store its generated ideas and plans?

Idea drafts generated by /humanize:gen-idea go to .humanize/ideas/ with a slug and timestamp in the filename by default. Plan files are specified by the user with the --output flag in /humanize:gen-plan. The documentation states that the path can be overridden from the default.

## Sources

- [Issues](https://github.com/PolyArch/humanize/issues)
- [PolyArch/humanize on GitHub](https://github.com/PolyArch/humanize)
- [README](https://github.com/PolyArch/humanize/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/polyarch-humanize