CodexForge CLI Tools

Shared developer tools and scripts for CodexForge team.

Installation

# Clone the repo
git clone https://github.com/CodexForgeBR/cli-tools.git ~/source/cli-tools
cd ~/source/cli-tools

# Build the ralph-loop Go binary
go build -o bin/ralph-loop ./cmd/ralph-loop

# Add to PATH in ~/.zshrc
echo 'export PATH="$HOME/source/cli-tools/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Set up global Claude Code configuration (optional but recommended)
mkdir -p ~/.claude
ln -s ~/source/cli-tools/CLAUDE.md ~/.claude/CLAUDE.md

What does the global CLAUDE.md do?

• Provides instructions to Claude Code across ALL projects
• Automatically tells Claude about available CLI tools
• Makes Claude use these scripts instead of reinventing solutions
• Syncs via Git when you update the repository

Available Scripts

get-coderabbit-comments.sh

Fetches CodeRabbit review comments from a GitHub Pull Request.

Usage:

get-coderabbit-comments.sh <PR_NUMBER>

Example:

get-coderabbit-comments.sh 72

Output: Displays all inline CodeRabbit comments with file path, line number, and comment body.

rm (Wrapper Script)

⚠️ IMPORTANT: This is a protective wrapper around the system rm command that backs up files instead of deleting them when called from automated CLI tools (Claude Code, Codex CLI).

How It Works:

• Analyzes process tree to detect if called from automated CLI tools
• Non-whitelisted files: Moved to ~/.rm-backup/ with full path structure preserved
• Whitelisted files: Actually deleted (temp files, build artifacts, hidden files)
• Transparent passthrough for normal terminal usage
• Claude Code thinks the deletion succeeded (exit code 0)

Whitelisted Patterns (Actually Deleted):

• Temporary files: /tmp/*, *.tmp
• Hidden files: .* (dotfiles)
• Build artifacts: bin/, obj/, node_modules/, target/, dist/, build/

Examples:

# From normal terminal - works as usual (actually deletes)
rm myfile.txt  # ✅ Deleted

# From Claude Code - backs up non-whitelisted files
rm important.json  # ✅ Moved to ~/.rm-backup/path/to/important.json.2025_11_04_17_00_00

# From Claude Code - actually deletes whitelisted patterns
rm /tmp/test.txt   # ✅ Actually deleted (temporary file)
rm .cache          # ✅ Actually deleted (hidden file)
rm -rf bin/        # ✅ Actually deleted (build artifact)

Backup Location: Files are moved to ~/.rm-backup/ preserving the original path structure with timestamp:

# Original: /Users/you/project/important.json
# Backup:   ~/.rm-backup/Users/you/project/important.json.2025_11_04_17_00_00

Restoring Files:

# Check what was backed up
ls -la ~/.rm-backup/

# Restore a file
cp ~/.rm-backup/path/to/file.txt.2025_11_04_17_00_00 /original/path/file.txt

Cleanup Old Backups:

# Remove all backups (use with caution)
/bin/rm -rf ~/.rm-backup

Installation Note: The wrapper works automatically once ~/source/cli-tools/bin is added to PATH (it appears before /bin in the PATH, creating an override).

git (Wrapper Script)

⚠️ IMPORTANT: This is a protective wrapper around git that blocks destructive commands when called from automated CLI tools (Claude Code, Codex CLI, Gemini CLI).

Key Difference from rm/rmdir Wrappers:

• rm/rmdir: Pretend to succeed (exit 0) + backup files
• git: Fail fast (exit 1) + display stern error message

How It Works:

• Analyzes process tree to detect if called from automated CLI tools
• Checks git command for destructive patterns
• Blocks with error if destructive command detected
• Transparent passthrough for safe git commands and normal terminal usage

Blocked Commands:

• git commit --no-verify or -n - Bypasses pre-commit hooks
• git reset --hard - Destroys uncommitted changes
• git clean -f/-d/-x - Deletes untracked/ignored files
• git push --force or -f - Rewrites remote history
• git push --force-with-lease - Still rewrites history

Examples:

# From normal terminal - works as usual
git commit --no-verify -m "emergency"  # ✅ Executes

# From Claude Code - blocked with error
git commit --no-verify -m "test"  # ❌ BLOCKED: Bypasses pre-commit hooks
git reset --hard HEAD             # ❌ BLOCKED: Destroys uncommitted changes
git push --force origin main      # ❌ BLOCKED: Rewrites remote history

# From Claude Code - safe commands work normally
git status                        # ✅ Works
git commit -m "normal commit"     # ✅ Works
git push origin feature-branch    # ✅ Works

Error Message Example:

========================================
GIT WRAPPER: DESTRUCTIVE COMMAND BLOCKED
========================================

BLOCKED: git commit --no-verify bypasses pre-commit hooks (Husky.Net validation)

Detected automated CLI tool: claude

To bypass this protection (if absolutely necessary):
  1. Run the command from your regular terminal (not from Claude)
  2. Or use the real git binary: /opt/homebrew/bin/git commit --no-verify

See ~/.git-wrapper-debug.log for details
========================================

Bypass Options:

# Use absolute path to real git binary
/opt/homebrew/bin/git commit --no-verify -m "emergency"

# Or run from regular terminal instead of Claude Code

Debug Log: Commands are logged to ~/.git-wrapper-debug.log with process tree analysis and block/allow decisions.

Installation Note: The wrapper works automatically once ~/source/cli-tools/bin is added to PATH (it appears before /opt/homebrew/bin, creating an override).

ralph-loop

Dual-Model Validation Loop for Spec-Driven Development based on the Ralph Wiggum technique by Geoffrey Huntley (May 2025).

What It Does:

• Implements tasks from a tasks.md specification file using one AI model
• Validates the work using a different AI model to catch "lies" and incomplete work
• Loops until all tasks are completed or max iterations reached
• Supports intelligent session resumption if interrupted
• Validates tasks against original plan to ensure proper decomposition
• Rate-limit detection halts the loop to avoid wasted iterations

Installation:

# Build from source
cd ~/source/cli-tools
go build -o bin/ralph-loop ./cmd/ralph-loop

# The binary is now available in PATH
ralph-loop --help

Basic Usage:

# Auto-detect tasks.md and run with defaults
ralph-loop

# Specify tasks file
ralph-loop --tasks-file specs/feature/tasks.md

# Use different models
ralph-loop --implementation-model opus --validation-model sonnet

# Use Codex CLI
ralph-loop --ai codex

# Limit iterations
ralph-loop --max-iterations 10

Codex Models (Validated):

• gpt-5.2-codex
• gpt-5.1-codex-mini
• gpt-5.1-codex-max
• gpt-5.2
• gpt-5.1
• gpt-5.1-codex
• gpt-5-codex
• gpt-5-codex-mini
• gpt-5

Omit --implementation-model/--validation-model with --ai codex to use the Codex CLI default. Use --allow-unknown-models to bypass validation for custom providers.

Plan File Support:

You can validate that your tasks properly implement an original plan from Claude Code:

# Use explicit plan file path
ralph-loop --original-plan-file ~/.claude/plans/my-feature-plan.md

# Use @latest to automatically select the most recent plan
ralph-loop --original-plan-file @latest
# 📋 Resolved @latest to: /Users/you/.claude/plans/cheerful-greeting-platypus.md

# Or use a GitHub issue URL
ralph-loop --github-issue https://github.com/owner/repo/issues/123
ralph-loop --github-issue 123  # Short form if gh CLI is configured

Session Management:

When interrupted (Ctrl+C), ralph-loop automatically saves its state. Running the tool again will detect the interrupted session:

# After interrupting with Ctrl+C, run again:
ralph-loop

# Output:
╔═══════════════════════════════════════════════════════════════╗
║              PREVIOUS SESSION DETECTED                        ║
╚═══════════════════════════════════════════════════════════════╝

A previous Ralph Loop session was interrupted.
  Status:    INTERRUPTED
  Iteration: 3
  Phase:     validation

Options:
  ralph-loop --resume        Resume from where you left off
  ralph-loop --clean         Start fresh (discards previous state)
  ralph-loop --status        View detailed session status

Resume Options:

# Resume from last saved state
ralph-loop --resume

# Resume even if tasks.md was modified
ralph-loop --resume-force

# Start fresh, discarding previous state
ralph-loop --clean

# View session status without running
ralph-loop --status

# Cancel an active session
ralph-loop --cancel

All Options:

ralph-loop [OPTIONS]

AI Provider & Models:
  --ai <claude|codex>                    AI CLI to use (default: claude)
  --implementation-model <model>         Model for implementation phase (default: opus/auto)
  --validation-model <model>             Model for validation phase (default: opus/auto)
  --cross-validation-ai <claude|codex>   AI CLI for cross-validation (default: auto-opposite)
  --cross-model <model>                  Model for cross-validation
  --final-plan-validation-ai <ai>        AI CLI for final plan validation
  --final-plan-validation-model <model>  Model for final plan validation
  --tasks-validation-ai <ai>             AI CLI for tasks validation
  --tasks-validation-model <model>       Model for tasks validation
  --allow-unknown-models                 Allow model names outside the official Codex list

Iteration Limits:
  --max-iterations <int>                 Maximum loop iterations (default: 20)
  --max-inadmissible <int>               Max inadmissible verdicts before exit 6 (default: 5)
  --max-claude-retry <int>               Max retries per AI invocation (default: 10)
  --max-turns <int>                      Max agent turns per AI invocation (default: 100)
  --inactivity-timeout <int>             Seconds of inactivity before kill (default: 1800)

Input Files:
  --tasks-file <path>                    Path to tasks.md (default: auto-detect)
  --original-plan-file <path|@latest>    Path to original plan or @latest for most recent
                                         ~/.claude/plans/*.md (mutually exclusive with --github-issue)
  --github-issue <url|number>            GitHub issue URL or number
  --learnings-file <path>                Path to learnings file (default: .ralph-loop/learnings.md)
  --config <path>                        Path to additional config file

Feature Toggles:
  -v, --verbose                          Pass verbose flag to AI CLI
  --no-learnings                         Disable learnings persistence
  --no-cross-validate                    Disable cross-validation phase

Scheduling:
  --start-at <time>                      Schedule start time (ISO 8601, HH:MM, YYYY-MM-DD HH:MM)
  --at <time>                            Alias for --start-at

Notifications:
  --notify-chat-id <id>                  Recipient chat ID (enables notifications)

Session Management:
  --resume                               Resume from last interrupted session
  --resume-force                         Resume even if tasks.md changed
  --clean                                Delete state directory and start fresh
  --status                               Show session status and exit
  --cancel                               Cancel active session and exit

Help & Version:
  -h, --help                             Show this help text
  --version                              Show version, commit, build date

Exit Codes:

• 0 - All tasks completed successfully and validated
• 1 - Error (invalid arguments, file not found, misconfiguration)
• 2 - Max iterations reached without completion
• 3 - Validation requested human intervention (escalate)
• 4 - All tasks blocked on external dependencies
• 5 - Tasks don't properly implement original plan
• 6 - Inadmissible violation threshold exceeded
• 7 - Rate limit detected; run halted
• 130 - Interrupted by SIGINT or SIGTERM

State Management:

The tool saves state to .ralph-loop/ directory including:

• Current iteration and phase (implementation/validation/cross-validation)
• Circuit breaker counters (no-progress detection)
• Last validation feedback
• Tasks file hash (for detecting modifications)
• Iteration snapshots with output logs
• Learnings accumulated from validation feedback

Phase-Aware Resumption:

If interrupted during:

• Implementation phase: Resumes by re-running implementation with previous feedback
• Validation phase: Skips to validation using existing implementation output
• Cross-validation phase: Skips to cross-validation using existing outputs

Tasks File Change Detection:

If you modify tasks.md after interrupting a session:

ralph-loop --resume

# Output:
╔═══════════════════════════════════════════════════════════════╗
║              TASKS FILE MODIFIED                              ║
╚═══════════════════════════════════════════════════════════════╝

The tasks.md file has changed since the session was interrupted.

Options:
  ralph-loop --resume-force   Resume with modified file
  ralph-loop --clean          Start fresh with new file

Examples:

# Standard usage with auto-detection
ralph-loop

# Verbose mode
ralph-loop -v

# Use most recent Claude Code plan
ralph-loop --original-plan-file @latest

# Custom models and iterations
ralph-loop --implementation-model opus --validation-model haiku --max-iterations 15

# Use Codex CLI for implementation, Claude for validation
ralph-loop --ai codex --cross-validation-ai claude

# Disable cross-validation
ralph-loop --no-cross-validate

# Resume after Ctrl+C
ralph-loop --resume

# Check status without running
ralph-loop --status

# Start fresh after modifying tasks
ralph-loop --clean

# Schedule to run later
ralph-loop --start-at "14:30"
ralph-loop --at "2025-02-03 09:00"

Claude Code Skills & Agents

This repository includes custom Claude Code skills and sub-agents that can be shared across machines and team members.

What's Included

Skills (workflow automation):

Skill	Description
run-tests	Clean, build, and test workflow for .NET solutions
coderabbit-workflow	Auto-fix CodeRabbit PR review feedback
pre-pr-review	Run local CodeRabbit scan before creating PR
post-merge-cleanup	Safe branch deletion after merge
qodana-local-review	Local Qodana static code analysis
calculate-coverage	Code coverage metrics for .NET projects
performance-testing	Performance regression detection

Sub-agents (specialized task handlers):

Agent	Description
test-runner	Executes clean-build-test workflow
coderabbit-fixer	Addresses CodeRabbit review feedback
local-coderabbit-reviewer	Runs local CodeRabbit scans
branch-cleanup	Safely cleans up merged branches
local-qodana-reviewer	Runs local Qodana analysis
perf-test-runner	Runs performance tests with regression detection

Installing Skills & Agents

# Install all skills and agents via symlinks
./install-claude.sh

# Preview what would be installed (dry run)
./install-claude.sh --dry-run

# Overwrite existing files (creates backups)
./install-claude.sh --force

# Uninstall (remove symlinks)
./install-claude.sh --remove

How it works:

• Creates symlinks from ~/.claude/skills/ and ~/.claude/agents/ to this repository
• Updates to the repo automatically propagate to Claude Code
• Existing files are backed up when using --force

Using Skills

Skills auto-activate based on your requests:

• "run tests" → triggers run-tests skill
• "address coderabbit feedback" → triggers coderabbit-workflow skill
• "clean up this branch" → triggers post-merge-cleanup skill

You can also invoke skills directly:

• /pre-pr-review - Run local CodeRabbit scan
• /qodana-local-review - Run local Qodana scan

Adding New Scripts

1. Add your script to the bin/ directory
2. Make it executable: chmod +x bin/your-script.sh
3. Update this README with usage instructions
4. Commit and push

On a New Machine

Simply clone the repository, build the Go binary, add to PATH, and set up global config:

# Clone the repository
git clone https://github.com/CodexForgeBR/cli-tools.git ~/source/cli-tools
cd ~/source/cli-tools

# Build the ralph-loop Go binary
go build -o bin/ralph-loop ./cmd/ralph-loop

# Add to PATH
echo 'export PATH="$HOME/source/cli-tools/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Set up global Claude Code configuration
mkdir -p ~/.claude
ln -s ~/source/cli-tools/CLAUDE.md ~/.claude/CLAUDE.md

# Install Claude Code skills and agents
./install-claude.sh

Done! All scripts and the ralph-loop binary are now available, and Claude Code will know about them across all projects. Skills and agents are ready to use.

Contributing

All CodexForge team members can contribute scripts that improve developer workflow and productivity.