Skip to content

CLAUDE.md

Latest commit

 

History

History
144 lines (105 loc) · 3.98 KB

CLAUDE.md

File metadata and controls

144 lines (105 loc) · 3.98 KB

ralphex

Autonomous plan execution with Claude Code - Go rewrite of ralph.py.

Build Commands

make build      # build binary to .bin/ralphex
make test       # run tests with coverage
make lint       # run golangci-lint
make fmt        # format code
make install    # install to ~/.local/bin

Project Structure

cmd/ralphex/        # main entry point, CLI parsing
pkg/config/         # configuration loading, defaults, prompts, agents
pkg/executor/       # claude and codex CLI execution
pkg/git/            # git operations using go-git library
pkg/processor/      # orchestration loop, prompts, signals
pkg/progress/       # timestamped logging with color
docs/plans/         # plan files location

Code Style

  • Use jessevdk/go-flags for CLI parsing
  • All comments lowercase except godoc
  • Table-driven tests with testify
  • 80%+ test coverage target

Key Patterns

  • Signal-based completion detection (COMPLETED, FAILED, REVIEW_DONE signals)
  • Streaming output with timestamps
  • Progress logging to files
  • Multiple execution modes: full, review-only, codex-only
  • Configuration via ~/.config/ralphex/ with embedded defaults

Configuration

  • Config location: ~/.config/ralphex/
  • Config file format: INI (using gopkg.in/ini.v1)
  • Embedded defaults in pkg/config/defaults/
  • Precedence: CLI flags > user config > embedded defaults
  • Custom prompts: ~/.config/ralphex/prompts/*.txt
  • Custom agents: ~/.config/ralphex/agents/*.txt

Agent System

5 default agents are installed on first run to ~/.config/ralphex/agents/:

  • implementation.txt - verifies code achieves stated goals
  • quality.txt - reviews for bugs, security issues, race conditions
  • documentation.txt - checks if docs need updates
  • simplification.txt - detects over-engineering
  • testing.txt - reviews test coverage and quality

Template syntax: Use {{agent:name}} in prompt files to reference agents. Each reference expands to Task tool instructions that tell Claude Code to run that agent.

Customization:

  • Edit files in ~/.config/ralphex/agents/ to modify agent prompts
  • Add new .txt files to create custom agents
  • Delete files and restart ralphex to restore defaults
  • Built-in Claude Code agents (like qa-expert, go-smells-expert) can be referenced directly in prompts

Testing

go test ./...           # run all tests
go test -cover ./...    # with coverage

End-to-End Testing

Unit tests mock external calls. After ANY code changes, run e2e test with a toy project to verify actual claude/codex integration and output streaming.

Create Toy Project

./scripts/prep-toy-test.sh

This creates /tmp/ralphex-test with a buggy Go file and a plan to fix it.

Test Full Mode

cd /tmp/ralphex-test
.bin/ralphex docs/plans/fix-issues.md

Expected behavior:

  1. Creates branch fix-issues
  2. Phase 1: executes Task 1, then Task 2
  3. Phase 2: first Claude review
  4. Phase 2.5: codex external review
  5. Phase 3: second Claude review
  6. Moves plan to docs/plans/completed/

Test Review-Only Mode

cd /tmp/ralphex-test
git checkout -b feature-test

# make some changes
echo "// comment" >> main.go
git add -A && git commit -m "add comment"

# run review-only (no plan needed)
go run ~/dev.umputun/ralphex/cmd/ralphex --review

Test Codex-Only Mode

cd /tmp/ralphex-test

# run codex-only review
go run ~/dev.umputun/ralphex/cmd/ralphex --codex-only

Monitor Progress

# live stream (use actual filename from ralphex output)
tail -f progress-fix-issues.txt

# recent activity
tail -50 progress-*.txt

Development Workflow

CRITICAL: After ANY code changes to ralphex:

  1. Run unit tests: make test
  2. Run linter: make lint
  3. MUST run end-to-end test with toy project (see above)
  4. Monitor tail -f progress-*.txt to verify output streaming works

Unit tests don't verify actual codex/claude integration or output formatting. The toy project test is the only way to verify streaming output works correctly.