Ralph-Claude-Code Gap Analysis Report

Analysis Date: January 25, 2026 Source Repository: frankbria/ralph-claude-code Analyzed Against: ADR-108 through ADR-111 Recommendation: Hybrid Approach - Use as reference/inspiration, develop CODITECT-native implementation

---

Executive Summary

The ralph-claude-code repository provides a production-quality bash implementation of the Ralph Wiggum autonomous agent loop technique. After deep code analysis, this report identifies significant gaps between the external implementation and CODITECT's ADR requirements, leading to the recommendation to develop our own implementation while potentially extracting patterns from ralph-claude-code.

Overall Assessment

Category	ralph-claude-code	CODITECT ADR Requirements	Gap Severity
Checkpoint Protocol	Partial (file-based)	FoundationDB-backed, ACID	CRITICAL
Browser Automation	None	Playwright MCP integration	CRITICAL
Health Monitoring	Good (circuit breaker)	Full 5-state model, heartbeat	MODERATE
Token Economics	Basic (call counting)	Full hierarchical budgets	HIGH

Verdict: Ralph-claude-code is a well-engineered bash implementation but does not meet CODITECT's enterprise requirements. Develop CODITECT-native Python/TypeScript implementation.

---

Repository Analysis

Structure Overview

ralph-claude-code/
├── ralph_loop.sh           # Main loop execution (~1400 lines)
├── lib/
│   ├── circuit_breaker.sh  # Circuit breaker pattern
│   ├── response_analyzer.sh # JSON/text response parsing
│   ├── date_utils.sh       # Cross-platform date handling
│   └── timeout_utils.sh    # Timeout handling
├── ralph_setup.sh          # Project scaffolding
├── ralph_migrate.sh        # Migration tools
├── ralph_monitor.sh        # tmux monitoring
└── tests/                  # BATS test suite

Strengths Identified

1. Well-tested: Comprehensive BATS test suite
2. Cross-platform: macOS/Linux compatible
3. Modern CLI: Supports --output-format json, --allowed-tools, --continue
4. Circuit breaker: Stagnation detection with graduated response
5. Session management: Session expiry, session history tracking
6. Response analysis: Multi-format parsing (JSON + text fallback)
7. Documentation: Detailed README, CLAUDE.md, implementation status

Limitations Identified

1. Language: Bash - not suitable for enterprise integration
2. State persistence: File-based only, no database support
3. No browser automation: Not in scope
4. Basic cost tracking: Call count only, no cost calculation
5. No multi-tenant: Single-user design
6. No compliance: No audit trails, signatures, retention
7. No FoundationDB: Git-file persistence only

---

Gap Analysis by ADR

ADR-108: Agent Checkpoint and Handoff Protocol

Requirement	ralph-claude-code	CODITECT ADR-108	Gap
Checkpoint storage	File-based (.ralph/)	FoundationDB ACID	CRITICAL
Checkpoint schema	JSON (status.json, progress.json)	Full schema with 6 sections	MODERATE
Handoff protocol	Implicit (loop continuation)	Explicit 10-step protocol	HIGH
Recovery protocol	Session reset on failure	Full checkpoint chain recovery	HIGH
Compliance evidence	None	Hash, signature, retention	CRITICAL
Context handoff	--continue flag	continuation_prompt generation	MODERATE
Cost attribution	None	Per-checkpoint token metrics	HIGH
Multi-tenant	None	Organization/project hierarchy	CRITICAL

Gap Summary: Ralph-claude-code has basic state persistence but lacks the database-backed, compliance-ready checkpoint system required by ADR-108.

Key Missing Features:

• FoundationDB key structure (/coditect/checkpoints/{task_id}/{checkpoint_id})
• SHA-256 integrity verification
• Cryptographic signing for FDA 21 CFR Part 11
• Checkpoint linking (parent/child relationships)
• Handoff triggers (context > 70%, phase complete, error threshold)

---

ADR-109: QA Agent Browser Automation

Requirement	ralph-claude-code	CODITECT ADR-109	Gap
Browser automation	None	Playwright MCP integration	CRITICAL
Page verification	None	verify_page_loads tool	CRITICAL
User flow testing	None	verify_user_flow tool	CRITICAL
Visual regression	None	capture/compare_visual_baseline	CRITICAL
Console error analysis	None	analyze_console_errors tool	CRITICAL
Screenshot evidence	None	Compliance-ready artifacts	CRITICAL

Gap Summary: Ralph-claude-code has zero browser automation capability. ADR-109 is entirely unaddressed.

Key Missing Features:

• MCP server integration (playwright-mcp)
• All 6 browser tools defined in ADR-109
• FlowStep schema for user journey testing
• Visual regression with baseline management
• Test result integration with checkpoints

---

ADR-110: Agent Health Monitoring

Requirement	ralph-claude-code	CODITECT ADR-110	Gap
Health state model	2 states (running, circuit-open)	5 states (HEALTHY → TERMINATED)	MODERATE
Circuit breaker	✅ Yes (3-state)	✅ Matches requirement	ALIGNED
Stuck detection	✅ detect_stuck_loop()	✅ Similar approach	ALIGNED
Heartbeat protocol	None	5-minute interval, payload spec	HIGH
Graduated intervention	Basic (nudge concept exists)	Full nudge → escalate → terminate	MODERATE
Self-healing	Session reset only	Full checkpoint recovery chain	HIGH
Event definitions	None	TypeScript event types	MODERATE
Alerting	None	Slack, PagerDuty integration	HIGH

Gap Summary: Ralph-claude-code has a solid foundation for health monitoring. The circuit breaker implementation is production-quality and could serve as a reference.

Aligned Features:

• Circuit breaker (CLOSED → OPEN → HALF_OPEN)
• Stuck detection via output analysis
• Error threshold triggering
• Manual reset capability

Missing Features:

• 5-state health model (HEALTHY, DEGRADED, STUCK, FAILING, TERMINATED)
• Heartbeat emission from agent
• Formal intervention protocol with timing
• Checkpoint-based recovery
• Configuration schema

---

ADR-111: Token Economics Instrumentation

Requirement	ralph-claude-code	CODITECT ADR-111	Gap
Token tracking	Call count only	Full token record schema	HIGH
Cost calculation	None	Per-model pricing calculation	HIGH
Budget hierarchy	Hourly call limit	Org → Project → Task → Agent	HIGH
Budget enforcement	Hard stop at limit	Throttle, pause, alert_only	MODERATE
Forecasting	None	Short/medium/long-term forecast	HIGH
Aggregations	None	Real-time + periodic rollups	HIGH
FoundationDB keys	None	Full key structure	CRITICAL
Events	None	TypeScript event types	MODERATE
Multi-tenant billing	None	Organization-level chargeback	CRITICAL

Gap Summary: Ralph-claude-code has basic rate limiting (calls/hour) but lacks the comprehensive token economics required for enterprise.

Partial Coverage:

• MAX_CALLS_PER_HOUR limit (default 100)
• Hourly reset logic
• Wait-for-reset behavior

Missing Features:

• Actual token counting (not just API calls)
• Cost calculation with model-specific pricing
• Hierarchical budget enforcement
• Throttling with exponential backoff
• Consumption spike detection
• Budget forecasting

---

Patterns Worth Extracting

Despite the gaps, ralph-claude-code contains valuable patterns:

1. Response Analyzer Pattern

# Multi-format response parsing
detect_output_format()     # JSON vs text detection
parse_json_response()      # Normalize various JSON formats
analyze_response()         # Extract signals

Reuse: Port the signal extraction logic (completion detection, stuck detection) to Python.

2. Circuit Breaker Implementation

# 3-state circuit breaker
circuit_breaker.sh:
  - CLOSED → OPEN on failure threshold
  - OPEN → HALF_OPEN on recovery timeout
  - HALF_OPEN → CLOSED/OPEN based on test request

Reuse: The state machine logic matches ADR-110 exactly. Adapt to Python/TypeScript.

3. Session Management

# Session lifecycle with expiration
init_session_tracking()
update_session_last_used()
log_session_transition()

Reuse: The session lifecycle tracking pattern is well-designed.

4. Stuck Detection Heuristics

# Multi-signal stuck detection
- No checkpoint update > 30 min
- Repeated identical operations
- Context exhaustion without handoff

Reuse: The detection signals align with ADR-110 requirements.

---

Recommendation

Primary Path: Develop CODITECT-Native Implementation

Factor	Reasoning
Language	Python/TypeScript required for FoundationDB, MCP, and enterprise integration
Architecture	CODITECT's event-driven, database-backed architecture differs fundamentally
Compliance	FDA 21 CFR Part 11, HIPAA, SOC2 require audit trails not supported by file-based state
Multi-tenant	Enterprise features require organization/project hierarchy
Browser automation	ADR-109 requires MCP integration not feasible in bash

Secondary Path: Extract and Adapt Patterns

From ralph-claude-code, extract:

1. Response analysis heuristics → Port to Python
2. Circuit breaker state machine → Adapt existing scripts/core/circuit_breaker.py
3. Stuck detection signals → Incorporate into health monitoring
4. Session lifecycle → Reference for session management

Implementation Priority

Based on gap severity:

Priority	ADR	Reasoning
1	ADR-109	Zero coverage - must build from scratch
2	ADR-108	Critical for compliance - FoundationDB required
3	ADR-111	High gaps - token economics essential for enterprise
4	ADR-110	Moderate gaps - some patterns reusable

Recommendation for Submodule

Do NOT add as submodule. Instead:

1. Reference repository - Keep as external reference (not submodule)
2. Extract patterns - Document useful patterns in this gap analysis
3. Build native - Implement in scripts/core/ralph_wiggum/ (already created)
4. Test alignment - Ensure our implementation achieves feature parity where appropriate

---

Comparison Matrix

Feature	ralph-claude-code	CODITECT Implementation	Winner
Language	Bash	Python/TypeScript	CODITECT
Persistence	File-based	FoundationDB	CODITECT
Compliance	None	FDA/HIPAA/SOC2 ready	CODITECT
Multi-tenant	No	Yes	CODITECT
Browser automation	No	Playwright MCP	CODITECT
Circuit breaker	Production-quality	Similar	TIE
Test coverage	BATS suite	pytest/vitest	TIE
Setup simplicity	Better	More complex	ralph-claude-code
Portability	macOS/Linux	Cross-platform	CODITECT

---

Conclusion

Ralph-claude-code is a well-engineered reference implementation that validates the Ralph Wiggum technique for autonomous agent loops. However, it does not meet CODITECT's enterprise requirements:

• Critical gap in compliance features (no audit trail, no signatures)
• Critical gap in persistence (no database, no multi-tenant)
• Critical gap in browser automation (not supported)
• High gaps in token economics and health monitoring depth

Final Recommendation: Continue with CODITECT-native implementation in scripts/core/ralph_wiggum/. Do not add ralph-claude-code as a submodule. Use this analysis as the definitive comparison document.

---

Database Architecture Reconciliation

FoundationDB vs PostgreSQL Decision

The original ADRs 108, 109, and 111 reference FoundationDB for state persistence. However, ADR-002 (PostgreSQL as Primary Database) establishes PostgreSQL as the accepted cloud database choice, explicitly rejecting FoundationDB due to:

"Operational complexity... No managed service... must run our own cluster"

Architecture Resolution

Layer	Database	Purpose	ADR Reference
Local (Developer)	SQLite	context.db, platform.db, projects.db	ADR-089, ADR-103
Cloud (Production)	PostgreSQL	Multi-tenant with RLS	ADR-002
Session Storage	FoundationDB (legacy v5)	Real-time collaboration	Mentioned in ADR-002

Impact on ADRs 108-111

ADR-108 (Checkpoint Protocol):

• Replace FoundationDB key structure with PostgreSQL tables
• Use checkpoints table with organization_id for multi-tenant RLS
• ACID guarantees via PostgreSQL transactions

ADR-109 (Browser Automation):

• No database impact (MCP-based)

ADR-110 (Health Monitoring):

• Health events stored in PostgreSQL agent_health_events table
• Use PostgreSQL time-series queries for heartbeat analysis

ADR-111 (Token Economics):

• Replace FoundationDB key structure with PostgreSQL tables
• Token records in token_consumption table
• Budget hierarchy in budgets table with foreign key relationships
• Aggregations via PostgreSQL materialized views

Local-to-Cloud Sync Architecture

LOCAL (SQLite)                      CLOUD (PostgreSQL)
┌─────────────────────┐            ┌─────────────────────┐
│ context.db          │            │ Multi-Tenant DB     │
│ ├── checkpoints     │────────────│ ├── checkpoints     │
│ ├── token_records   │   sync     │ ├── token_records   │
│ └── health_events   │────────────│ └── health_events   │
│                     │            │                     │
│ (Single-tenant)     │            │ (RLS Isolation)     │
└─────────────────────┘            └─────────────────────┘

Sync Protocol:
- Cursor-based polling (ADR-053)
- Offline queue for disconnected operation
- Conflict resolution: cloud wins (last-write-wins)

Multi-Tenant Requirements Satisfied

Requirement	PostgreSQL Solution
Multi-user	Standard auth
Multi-team	Organization membership
Multi-project	Project table with org_id FK
Multi-tenant	Row-Level Security (RLS)
Compliance	Audit log with RLS

---

Related ADRs

ADR	Title	Impact
ADR-002	PostgreSQL as Primary Database	Cloud database choice
ADR-089	Two-Database Architecture	Local platform.db + context.db
ADR-103	Four-Database Separation	Extends to 4 local DBs
ADR-108	Checkpoint Protocol	Requires PostgreSQL update
ADR-109	Browser Automation	No change needed
ADR-110	Health Monitoring	Uses PostgreSQL
ADR-111	Token Economics	Requires PostgreSQL update

---

Analysis completed by: Claude (ADR Compliance Specialist) Date: January 25, 2026 Updated: January 25, 2026 - Added ADR references and database architecture reconciliation