# asyncfuncai/ralph-wiggum-extension architecture

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

- Interactive diagram: https://gitdiagram.com/asyncfuncai/ralph-wiggum-extension
- Repository: https://github.com/asyncfuncai/ralph-wiggum-extension

## Overview

This is a Gemini CLI extension for running persistent, iterative development tasks. The documented workflow starts with a user invoking `/ralph-loop` in Gemini CLI, which creates a local loop state file; Gemini then works iteratively until the iteration limit or completion promise is met. `/cancel-ralph` is the separate cancellation entry point. The README documents these behaviors, but source excerpts are unavailable, so links to the shell scripts and details of their internal wiring are omitted.

Main entry points: [`commands/ralph-loop.toml`](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml) (Start loop), [`commands/cancel-ralph.toml`](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/cancel-ralph.toml) (Cancel loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Loop commands"]
  node_start["Start loop<br/>[ralph-loop.toml]"]
  node_cancel["Cancel loop<br/>[cancel-ralph.toml]"]
end

subgraph group_runtime["Loop runtime"]
  node_state["Loop state"]
  node_iteration["Iterative work<br/>[ralph-loop.toml]"]
  node_completion["Completion conditions<br/>[ralph-loop.toml]"]
end

node_user(("User"))
node_gemini["Gemini CLI"]

node_user -->|"invokes"| node_gemini
node_gemini -->|"dispatches"| node_start
node_start -->|"creates"| node_state
node_gemini -->|"performs"| node_iteration
node_iteration -->|"checks"| node_completion
node_user -->|"invokes"| node_cancel
node_cancel -->|"cancels"| node_gemini

click node_start "https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml"
click node_cancel "https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/cancel-ralph.toml"
click node_iteration "https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml"
click node_completion "https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml"

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_start,node_cancel,node_user toneBlue
class node_state,node_iteration,node_completion toneAmber
class node_gemini toneIndigo
```

## Components

### Loop commands

- [Start loop](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml): `commands/ralph-loop.toml`
- [Cancel loop](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/cancel-ralph.toml): `commands/cancel-ralph.toml`

### Loop runtime

- **Loop state**
- [Iterative work](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml): `commands/ralph-loop.toml`
- [Completion conditions](https://github.com/asyncfuncai/ralph-wiggum-extension/blob/main/commands/ralph-loop.toml): `commands/ralph-loop.toml`

### Other components

- **User**
- **Gemini CLI**

## Connections

- User → Gemini CLI: invokes
- Gemini CLI → Start loop: dispatches
- Start loop → Loop state: creates
- Gemini CLI → Iterative work: performs
- Iterative work → Completion conditions: checks
- User → Cancel loop: invokes
- Cancel loop → Gemini CLI: cancels