# frankbria/ralph-claude-code architecture

> Architecture diagram of the GitHub repository frankbria/ralph-claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frankbria/ralph-claude-code
- Repository: https://github.com/frankbria/ralph-claude-code

## Overview

Ralph is a command-line autonomous development loop for Claude Code. A project owner supplies requirements and starts the loop; Ralph repeatedly invokes the coding agent, evaluates responses and progress, and stops only when its completion conditions are met. Rate limits, circuit breaking, and error detection constrain that runtime. Separate capabilities import tasks, enable projects, monitor runs, and report metrics. The README documents these capabilities, but only the E2B helper was sampled from source, so its connection to the loop is shown as unverified.

Main entry points: [`ralph_loop.sh`](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_loop.sh) (Development loop), [`lib/enable_core.sh`](https://github.com/frankbria/ralph-claude-code/blob/main/lib/enable_core.sh) (Enablement workflow), [`ralph_import.sh`](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_import.sh) (Task import), [`ralph_enable.sh`](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_enable.sh) (Project enablement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Loop runtime"]
  node_loop["Development loop<br/>[ralph_loop.sh]"]
  node_agent["Claude Code"]
end

subgraph group_safety["Runtime safeguards"]
  node_response["Response analysis"]
  node_circuit["Circuit breaker<br/>[circuit_breaker.sh]"]
  node_rate["Rate limiting<br/>[timeout_utils.sh]"]
end

subgraph group_project["Project workflows"]
  node_task_import["Task import<br/>[ralph_import.sh]"]
  node_issue_analysis["Issue analysis<br/>[issue_analyzer.sh]"]
  node_task_sources["Task sources<br/>[task_sources.sh]"]
  node_enable["Project enablement<br/>[ralph_enable.sh]"]
  node_enable_core["Enablement workflow<br/>[enable_core.sh]"]
  node_wizard["Setup wizard<br/>[wizard_utils.sh]"]
end

subgraph group_operations["Run operations"]
  node_monitor["Live monitor<br/>[ralph_monitor.sh]"]
  node_queue["Queue management<br/>[ralph_queue.sh]"]
  node_queue_manager["Queue operations<br/>[queue_manager.sh]"]
  node_stats["Loop analytics<br/>[ralph-stats.sh]"]
end

subgraph group_sandbox["Sandbox execution"]
  node_e2b["E2B transport<br/>[e2b_helper.py]"]
  node_e2b_service["E2B sandbox"]
end

node_owner(("Project owner"))

node_owner -->|"starts"| node_loop
node_loop -->|"runs iterations"| node_agent
node_loop -->|"analyzes output"| node_response
node_loop -->|"guards runs"| node_circuit
node_loop -->|"limits calls"| node_rate
node_owner -->|"imports tasks"| node_task_import
node_task_import -->|"analyzes issues"| node_issue_analysis
node_enable -->|"runs wizard"| node_enable_core
node_enable_core -->|"uses utilities"| node_wizard
node_enable_core -->|"imports tasks"| node_task_sources
node_owner -->|"enables project"| node_enable
node_owner -->|"monitors runs"| node_monitor
node_owner -->|"manages queue"| node_queue
node_queue -.->|"manages tasks"| node_queue_manager
node_owner -->|"views metrics"| node_stats
node_loop -.->|"uses transport"| node_e2b
node_e2b -.->|"connects remotely"| node_e2b_service

click node_loop "https://github.com/frankbria/ralph-claude-code/blob/main/ralph_loop.sh"
click node_response "https://github.com/frankbria/ralph-claude-code/blob/main/lib/response_analyzer.sh"
click node_circuit "https://github.com/frankbria/ralph-claude-code/blob/main/lib/circuit_breaker.sh"
click node_rate "https://github.com/frankbria/ralph-claude-code/blob/main/lib/timeout_utils.sh"
click node_task_import "https://github.com/frankbria/ralph-claude-code/blob/main/ralph_import.sh"
click node_issue_analysis "https://github.com/frankbria/ralph-claude-code/blob/main/lib/issue_analyzer.sh"
click node_task_sources "https://github.com/frankbria/ralph-claude-code/blob/main/lib/task_sources.sh"
click node_enable "https://github.com/frankbria/ralph-claude-code/blob/main/ralph_enable.sh"
click node_enable_core "https://github.com/frankbria/ralph-claude-code/blob/main/lib/enable_core.sh"
click node_wizard "https://github.com/frankbria/ralph-claude-code/blob/main/lib/wizard_utils.sh"
click node_monitor "https://github.com/frankbria/ralph-claude-code/blob/main/ralph_monitor.sh"
click node_queue "https://github.com/frankbria/ralph-claude-code/blob/main/ralph_queue.sh"
click node_queue_manager "https://github.com/frankbria/ralph-claude-code/blob/main/lib/queue_manager.sh"
click node_stats "https://github.com/frankbria/ralph-claude-code/blob/main/ralph-stats.sh"
click node_e2b "https://github.com/frankbria/ralph-claude-code/blob/main/lib/e2b_helper.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_loop,node_agent toneBlue
class node_response,node_circuit,node_rate toneAmber
class node_task_import,node_issue_analysis,node_task_sources,node_enable,node_enable_core,node_wizard toneMint
class node_monitor,node_queue,node_queue_manager,node_stats toneRose
class node_e2b,node_e2b_service,node_owner toneIndigo
```

## Components

### Loop runtime

- [Development loop](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_loop.sh): `ralph_loop.sh`
- **Claude Code**

### Runtime safeguards

- [Response analysis](https://github.com/frankbria/ralph-claude-code/blob/main/lib/response_analyzer.sh): `lib/response_analyzer.sh`
- [Circuit breaker](https://github.com/frankbria/ralph-claude-code/blob/main/lib/circuit_breaker.sh): `lib/circuit_breaker.sh`
- [Rate limiting](https://github.com/frankbria/ralph-claude-code/blob/main/lib/timeout_utils.sh): `lib/timeout_utils.sh`

### Project workflows

- [Task import](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_import.sh): `ralph_import.sh`
- [Issue analysis](https://github.com/frankbria/ralph-claude-code/blob/main/lib/issue_analyzer.sh): `lib/issue_analyzer.sh`
- [Task sources](https://github.com/frankbria/ralph-claude-code/blob/main/lib/task_sources.sh): `lib/task_sources.sh`
- [Project enablement](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_enable.sh): `ralph_enable.sh`
- [Enablement workflow](https://github.com/frankbria/ralph-claude-code/blob/main/lib/enable_core.sh): `lib/enable_core.sh`
- [Setup wizard](https://github.com/frankbria/ralph-claude-code/blob/main/lib/wizard_utils.sh): `lib/wizard_utils.sh`

### Run operations

- [Live monitor](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_monitor.sh): `ralph_monitor.sh`
- [Queue management](https://github.com/frankbria/ralph-claude-code/blob/main/ralph_queue.sh): `ralph_queue.sh`
- [Queue operations](https://github.com/frankbria/ralph-claude-code/blob/main/lib/queue_manager.sh): `lib/queue_manager.sh`
- [Loop analytics](https://github.com/frankbria/ralph-claude-code/blob/main/ralph-stats.sh): `ralph-stats.sh`

### Sandbox execution

- [E2B transport](https://github.com/frankbria/ralph-claude-code/blob/main/lib/e2b_helper.py): `lib/e2b_helper.py`
- **E2B sandbox**

### Other components

- **Project owner**

## Connections

- Project owner → Development loop: starts (evidence: `README.md`)
- Development loop → Claude Code: runs iterations (evidence: `README.md`)
- Development loop → Response analysis: analyzes output (evidence: `README.md`)
- Development loop → Circuit breaker: guards runs (evidence: `README.md`)
- Development loop → Rate limiting: limits calls (evidence: `README.md`)
- Project owner → Task import: imports tasks (evidence: `README.md`)
- Task import → Issue analysis: analyzes issues (evidence: `README.md`)
- Project enablement → Enablement workflow: runs wizard (evidence: `README.md`)
- Enablement workflow → Setup wizard: uses utilities (evidence: `README.md`)
- Enablement workflow → Task sources: imports tasks (evidence: `README.md`)
- Project owner → Project enablement: enables project (evidence: `README.md`)
- Project owner → Live monitor: monitors runs (evidence: `README.md`)
- Project owner → Queue management: manages queue (evidence: `README.md`)
- Queue management → Queue operations: manages tasks
- Project owner → Loop analytics: views metrics (evidence: `README.md`)
- Development loop → E2B transport: uses transport
- E2B transport → E2B sandbox: connects remotely
