Skip to content

usage.md

Latest commit

 

History

History
186 lines (141 loc) · 6.96 KB

usage.md

File metadata and controls

186 lines (141 loc) · 6.96 KB

Humanize Usage Guide

Detailed usage documentation for the Humanize plugin. For installation, see Install for Claude Code.

How It Works

Humanize creates an iterative feedback loop with two phases:

  1. Implementation Phase: Claude works on your plan, Codex reviews summaries until COMPLETE
  2. Review Phase: codex review --base <branch> checks code quality with [P0-9] severity markers

The loop continues until all acceptance criteria are met or no issues remain.

Commands

Command Purpose
/start-rlcr-loop <plan.md> Start iterative development with Codex review
/cancel-rlcr-loop Cancel active loop
/gen-plan --input <draft.md> --output <plan.md> Generate structured plan from draft
/start-pr-loop --claude|--codex Start PR review loop with bot monitoring
/cancel-pr-loop Cancel active PR loop
/ask-codex [question] One-shot consultation with Codex

Command Reference

start-rlcr-loop

/humanize:start-rlcr-loop [path/to/plan.md | --plan-file path/to/plan.md] [OPTIONS]

OPTIONS:
  --plan-file <path>     Explicit plan file path (alternative to positional arg)
  --max <N>              Maximum iterations before auto-stop (default: 42)
  --codex-model <MODEL:EFFORT>
                         Codex model and reasoning effort (default: gpt-5.4:xhigh)
  --codex-timeout <SECONDS>
                         Timeout for each Codex review in seconds (default: 5400)
  --track-plan-file      Indicate plan file should be tracked in git (must be clean)
  --push-every-round     Require git push after each round (default: commits stay local)
  --base-branch <BRANCH> Base branch for code review phase (default: auto-detect)
                         Priority: user input > remote default > main > master
  --full-review-round <N>
                         Interval for Full Alignment Check rounds (default: 5, min: 2)
                         Full Alignment Checks occur at rounds N-1, 2N-1, 3N-1, etc.
  --skip-impl            Skip implementation phase, go directly to code review
                         Plan file is optional when using this flag
  --claude-answer-codex  When Codex finds Open Questions, let Claude answer them
                         directly instead of asking user via AskUserQuestion
  --agent-teams          Enable Claude Code Agent Teams mode for parallel development.
                         Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable.
                         Claude acts as team leader, splitting tasks among team members.
  -h, --help             Show help message

gen-plan

/humanize:gen-plan --input <path/to/draft.md> --output <path/to/plan.md>

OPTIONS:
  --input   Path to the input draft file (required)
  --output  Path to the output plan file (required)
  -h, --help             Show help message

The gen-plan command transforms rough draft documents into structured implementation plans.

Workflow:
1. Validates input/output paths
2. Checks if draft is relevant to the repository
3. Analyzes draft for clarity, consistency, completeness, and functionality
4. Engages user to resolve any issues found
5. Generates a structured plan.md with acceptance criteria

start-pr-loop

/humanize:start-pr-loop --claude|--codex [OPTIONS]

BOT FLAGS (at least one required):
  --claude   Monitor reviews from claude[bot] (trigger with @claude)
  --codex    Monitor reviews from chatgpt-codex-connector[bot] (trigger with @codex)

OPTIONS:
  --max <N>              Maximum iterations before auto-stop (default: 42)
  --codex-model <MODEL:EFFORT>
                         Codex model and reasoning effort (default: gpt-5.4:medium)
  --codex-timeout <SECONDS>
                         Timeout for each Codex review in seconds (default: 900)
  -h, --help             Show help message

The PR loop automates the process of handling GitHub PR reviews from remote bots:

  1. Detects the PR associated with the current branch
  2. Fetches review comments from the specified bot(s)
  3. Claude analyzes and fixes issues identified by the bot(s)
  4. Pushes changes and triggers re-review by commenting @bot
  5. Stop Hook polls for new bot reviews (every 30s, 15min timeout per bot)
  6. Local Codex validates if remote concerns are approved or have issues
  7. Loop continues until all bots approve or max iterations reached

Prerequisites:

  • GitHub CLI (gh) must be installed and authenticated
  • Codex CLI must be installed
  • Current branch must have an associated open PR

ask-codex

/humanize:ask-codex [OPTIONS] <question or task>

OPTIONS:
  --codex-model <MODEL:EFFORT>
                         Codex model and reasoning effort (default: gpt-5.4:xhigh)
  --codex-timeout <SECONDS>
                         Timeout for the Codex query in seconds (default: 3600)
  -h, --help             Show help message

The ask-codex skill sends a one-shot question or task to Codex and returns the response inline. Unlike the RLCR loop, this is a single consultation without iteration -- useful for getting a second opinion, reviewing a design, or asking domain-specific questions.

Responses are saved to .humanize/skill/<timestamp>/ with input.md, output.md, and metadata.md for reference.

Monitoring

Set up the monitoring helper for real-time progress tracking:

# Add to your .bashrc or .zshrc
source ~/.claude/plugins/cache/humania/humanize/<LATEST.VERSION>/scripts/humanize.sh

# Monitor RLCR loop progress
humanize monitor rlcr

# Monitor PR loop progress
humanize monitor pr

Progress data is stored in .humanize/rlcr/<timestamp>/ for each loop session.

Cancellation

  • RLCR loop: /humanize:cancel-rlcr-loop
  • PR loop: /humanize:cancel-pr-loop

Environment Variables

HUMANIZE_CODEX_BYPASS_SANDBOX

WARNING: This is a dangerous option that disables security protections. Use only if you understand the implications.

  • Purpose: Controls whether Codex runs with sandbox protection
  • Default: Not set (uses --full-auto with sandbox protection)
  • Values:
    • true or 1: Bypasses Codex sandbox and approvals (uses --dangerously-bypass-approvals-and-sandbox)
    • Any other value or unset: Uses safe mode with sandbox

When to use this:

  • Linux servers without landlock kernel support (where Codex sandbox fails)
  • Automated CI/CD pipelines in trusted environments
  • Development environments where you have full control

When NOT to use this:

  • Public or shared development servers
  • When reviewing untrusted code or pull requests
  • Production systems
  • Any environment where unauthorized system access could cause damage

Security implications:

  • Codex will have unrestricted access to your filesystem
  • Codex can execute arbitrary commands without approval prompts
  • Review all code changes carefully when using this mode

Usage example:

# Export before starting Claude Code
export HUMANIZE_CODEX_BYPASS_SANDBOX=true

# Or set for a single session
HUMANIZE_CODEX_BYPASS_SANDBOX=true claude --plugin-dir /path/to/humanize