👑 RalphSpec

Spec-driven AI coding loop CLI — with a supervisor that keeps the King honest

Quick Start · Architecture · Spec Kit · TUI Dashboard · Regent · Config · CLI Reference

📑 Table of Contents

⚡ Quick Start
🏗️ Architecture
📜 Spec Kit Workflow
🖥️ TUI Dashboard
🏰 The Regent
🌿 Worktrees (Parallel Agents)
⚙️ Configuration
🎯 CLI Reference
📁 Project Structure
🔒 Safety & Guardrails
🤝 Supported Agents

⚡ Quick Start

# 📥 Install
go install github.com/LISSConsulting/RalphSpec/cmd/ralph@latest

# 🎬 Initialize a new project
ralph init

# 📋 Create a spec from a description
ralph specify "Add user authentication with JWT tokens"

# 📐 Generate implementation plan
ralph plan

# 🔨 Build it — autonomous loop with TUI dashboard
ralph build

# 👑 Or just launch the dashboard and control everything from there
ralph

That's it. Ralph reads your spec, drives Claude through iterations, commits results, and the Regent supervises the whole thing.

🏗️ Architecture

%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'monospace', 'fontSize': '13px', 'primaryColor': '#7D56F4', 'primaryBorderColor': '#000', 'primaryTextColor': '#000', 'lineColor': '#000'}}}%%
graph LR
    A["🏰 Regent<br/>supervisor"] --> B["👑 Ralph<br/>loop engine"]
    B --> C["🤖 Claude<br/>worker"]
    C --> D["📝 Code Changes<br/>commit · push"]

    classDef lavender fill:#A78BFA,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef yellow fill:#FFE66D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef mint fill:#4ECDC4,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef pink fill:#FF6B9D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold

    class A lavender
    class B yellow
    class C mint
    class D pink

Layer	Role	Details
🏰 Regent	Supervisor	Watches Ralph for crashes, hangs, and test regressions. Rolls back bad commits, restarts with backoff.
👑 Ralph	Loop engine	Reads specs, builds prompts, invokes Claude, parses streaming JSON output, commits and pushes results.
🤖 Claude	Worker	Claude Code CLI — executes the actual coding work within spec boundaries.

Tip

Ralph targets your active spec by default. Use --roam to let Claude sweep freely across the entire codebase for polish and improvement work.

📜 Spec Kit Workflow

Specs live in specs/NNN-name/ directories. Ralph drives Claude through a sequential, spec-driven development lifecycle:

%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'monospace', 'fontSize': '13px', 'primaryBorderColor': '#000', 'primaryTextColor': '#000', 'lineColor': '#000'}}}%%
graph LR
    A["📋 specify<br/>spec.md"] --> B["❓ clarify<br/>resolve gaps"]
    B --> C["📐 plan<br/>plan.md"]
    C --> D["✅ tasks<br/>tasks.md"]
    D --> E["🔨 build<br/>autonomous loop"]

    classDef yellow fill:#FFE66D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef pink fill:#FF6B9D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef mint fill:#4ECDC4,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef lavender fill:#A78BFA,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef lime fill:#C7F464,stroke:#000,stroke-width:3px,color:#000,font-weight:bold

    class A yellow
    class B pink
    class C lavender
    class D mint
    class E lime

Command	Artifact	Description
`ralph specify`	`spec.md`	Create a feature spec from a natural language description
`ralph clarify`	updates `spec.md`	Resolve ambiguities through targeted clarification questions
`ralph plan`	`plan.md`	Generate architecture, tech stack, and implementation phases
`ralph tasks`	`tasks.md`	Break the plan into ordered, dependency-aware tasks
`ralph run`	—	Execute the spec kit run skill against the active spec
`ralph build`	code	Autonomous loop — Claude implements tasks, commits, pushes

# 📋 List all specs and their status
ralph spec list

#   📋 003-tui-redesign         ✅ Tasked
#   📐 004-speckit-alignment    ✅ Tasked
#   📋 005-spec-bounded-roam    ✅ Tasked
#   📋 006-polish-and-hardening ✅ Tasked

Note

Ralph auto-detects the active spec from your branch name. Branch 005-spec-bounded-roam maps to specs/005-spec-bounded-roam/. Override with the --spec flag.

🖥️ TUI Dashboard

Launch with ralph (no arguments) for the full four-panel interactive dashboard:

┌─ Specs ──────────┐┌─ Main ─────────────────────────────────────────┐
│ 📋 003-tui-red…  ││ [Live Log] [Summary]                          │
│ 📐 004-speckit…  ││                                                │
│ ✅ 005-spec-bo…  ││ ▶ Iteration 3 — building spec 005              │
│ ✅ 006-polish-…  ││   Reading spec.md... done                      │
│                   ││   Running Claude... streaming                  │
│                   ││   ██████████░░░░░░ 64%                        │
├─ Iterations ─────┤├─ Secondary ───────────────────────────────────┤
│ #1  $0.12  2m    ││ [Regent] [Git] [Tests] [Cost]                 │
│ #2  $0.08  1m    ││                                                │
│ #3  running…     ││ 🏰 Regent: watching · 0 rollbacks              │
│                   ││ 💰 Session: $0.20 · 3 iterations              │
└───────────────────┘└───────────────────────────────────────────────┘

⌨️ Keyboard Reference

Key	Action
`tab` / `shift+tab`	Cycle panel focus
`1` `2` `3` `4`	Jump to Specs / Iterations / Main / Secondary
`5`	Jump to Worktrees panel (when worktree support enabled)
`b`	Start build loop
`p`	Start plan loop
`R`	Smart run (plan if needed, then build)
`x`	Cancel running loop immediately
`s`	Graceful stop after current iteration
`?`	Toggle help overlay
`q` / `ctrl+c`	Quit

Panel shortcuts:

Panel	Keys
📋 Specs	`j`/`k` navigate · `enter` view · `e` edit in `$EDITOR` · `n` create new · `W` launch in worktree
📊 Iterations	`j`/`k` navigate · `enter` view log · `]` switch to summary
📝 Main	`[`/`]` switch tabs · `f` toggle follow · `ctrl+u`/`ctrl+d` page
📡 Secondary	`[`/`]` switch tabs (Regent / Git / Tests / Cost) · `j`/`k` scroll
🌿 Worktrees	`j`/`k` navigate · `enter` view log · `x` stop · `M` merge · `D` discard

Tip

Minimum terminal size: 80×24. Set your accent color via [tui] accent_color in ralph.toml.

🏰 The Regent

The Regent is Ralph's supervisor — it watches the loop and intervenes when things go wrong:

%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'monospace', 'fontSize': '13px', 'primaryBorderColor': '#000', 'primaryTextColor': '#000', 'lineColor': '#000'}}}%%
graph TD
    A["👑 Ralph iterating"] --> B{"🧪 Tests pass?"}
    B -- Yes --> C["✅ Keep commit<br/>continue loop"]
    B -- No --> D["⏪ Rollback commit<br/>retry iteration"]
    A --> E{"💀 Crash?"}
    E -- Yes --> F["♻️ Restart Ralph<br/>exponential backoff"]
    A --> G{"⏱️ Hung?"}
    G -- Yes --> H["🔪 Kill process<br/>restart with backoff"]

    classDef yellow fill:#FFE66D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef mint fill:#4ECDC4,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef pink fill:#FF6B9D,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef orange fill:#FF6B35,stroke:#000,stroke-width:3px,color:#fff,font-weight:bold
    classDef decision fill:#FF8A80,stroke:#000,stroke-width:3px,color:#000,font-weight:bold
    classDef lavender fill:#A78BFA,stroke:#000,stroke-width:3px,color:#000,font-weight:bold

    class A yellow
    class B,E,G decision
    class C mint
    class D pink
    class F orange
    class H lavender

Feature	Description
🧪 Test-gated commits	Runs your test command after each iteration; rolls back on failure
💀 Crash recovery	Detects process exit, restarts Ralph with exponential backoff
⏱️ Hang detection	Kills Ralph if no output for `hang_timeout_seconds` (default: 5 min)
🔄 Retry with backoff	Up to `max_retries` restarts with configurable backoff
📡 Observable	All Regent actions stream to the TUI Secondary panel

🌿 Worktrees (Parallel Agents)

Requires worktrunk (wt) installed on your PATH.

Quick Start

# Run a build in an isolated git worktree (your working dir stays clean)
ralph build --worktree

# Same in headless mode
ralph build -w --no-tui --max 10

# List active worktrees
ralph worktree list

# Merge a completed worktree branch and clean up
ralph worktree merge feat/my-branch

# Discard a worktree without merging
ralph worktree clean feat/my-branch

Parallel Agents from the Dashboard

Open the TUI (ralph), navigate to the Specs panel, and press W on any spec to launch it in its own worktree. The Worktrees panel (panel 5) shows all active agents in real-time.

Key	Action
`W`	Launch selected spec in a new worktree (Specs panel)
`x`	Stop the selected worktree agent (Worktrees panel)
`M`	Merge the selected worktree (Worktrees panel)
`D`	Clean (discard) the selected worktree (Worktrees panel)
`enter`	View the selected agent's live log in the Main panel

Worktree Config

[worktree]
enabled       = false         # enable worktree support
max_parallel  = 5             # max concurrent agents
auto_merge    = false         # auto-merge on completion (requires tests to pass)
merge_target  = ""            # branch to merge into (default: current branch)
path_template = ""            # worktree path template (uses worktrunk default)

With auto_merge = true and a test_command configured in [regent], completed agents are automatically merged and cleaned up when tests pass. On test failure the worktree is left intact for review.

Worktree CLI Commands

Command	Description
`ralph worktree list`	List active worktrees and their status
`ralph worktree list --json`	JSON output for scripting
`ralph worktree merge [branch]`	Merge a completed worktree branch
`ralph worktree clean [branch]`	Remove a worktree without merging
`ralph worktree clean --all`	Remove all non-running worktrees

⚙️ Configuration

Place ralph.toml in your project root. All fields are optional with sensible defaults:

[project]
name = "MyProject"

[claude]
model = "sonnet"              # Claude model to use
max_turns = 0                 # 0 = unlimited agentic turns per iteration
danger_skip_permissions = true

[plan]
prompt_file = "PLAN.md"       # prompt template for plan iterations
max_iterations = 3

[build]
prompt_file = "BUILD.md"      # prompt template for build iterations
max_iterations = 0            # 0 = unlimited
roam = false                  # --roam flag overrides this

[git]
auto_pull_rebase = true       # pull --rebase before each iteration
auto_push = true              # push after each commit

[regent]
enabled = true
rollback_on_test_failure = false
test_command = "go test ./..."
max_retries = 3
retry_backoff_seconds = 30
hang_timeout_seconds = 300    # kill if no output for 5 min

[tui]
accent_color = "#7D56F4"      # hex color for header/accent elements
log_retention = 20            # session logs to keep; 0 = unlimited

[notifications]
url = ""                      # ntfy.sh topic URL or HTTP webhook
on_complete = true            # notify on iteration complete
on_error = true               # notify on loop error
on_stop = true                # notify when loop finishes

[worktree]
enabled       = false         # enable worktree support (requires worktrunk)
max_parallel  = 5             # max concurrent worktree agents
auto_merge    = false         # auto-merge and clean up on successful completion
merge_target  = ""            # target branch for auto-merge (default: current branch)
path_template = ""            # worktree directory template (uses worktrunk default)

🔑 Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	⬜	Direct API key — Ralph warns if set (prefer Claude Pro/Max subscription)
`EDITOR`	⬜	Editor for `e` keybind in Specs panel (defaults to system editor)

Warning

If ANTHROPIC_API_KEY is set, Ralph prints a prominent warning on startup. Claude may use direct API billing instead of your subscription. Unset it to avoid unexpected charges.

🎯 CLI Reference

Top-level Commands

Command	Description
`ralph`	👑 Launch the interactive TUI dashboard
`ralph init`	🎬 Scaffold a new ralph project (config, prompts, specs dir)
`ralph status`	📊 Show last run, cost, iteration count, branch
`ralph spec list`	📋 List all specs and their status

Spec Kit Commands

Command	Description
`ralph specify "<description>"`	📋 Create a new spec from a description
`ralph plan`	📐 Generate implementation plan for active spec
`ralph clarify`	❓ Resolve ambiguities in active spec
`ralph tasks`	✅ Break plan into actionable task list
`ralph run`	🚀 Execute spec kit run against active spec

Loop Commands

Command	Description
`ralph build`	🔨 Build mode — autonomous coding loop (alias for `ralph loop build`)
`ralph build --roam`	🌍 Roam freely across codebase, no spec boundary
`ralph loop plan`	📐 Plan mode loop
`ralph loop build`	🔨 Build mode loop
`ralph loop run`	🧠 Smart mode — plan if needed, then build

Flags (all loop commands)

Flag	Description
`--no-tui`	Disable TUI; print plain log lines to stdout (CI/headless)
`--no-color`	Disable ANSI color output (pipe-safe)
`--max N`	Override max iterations (0 = use config)
`--roam`	Roam freely across the codebase (no spec boundary)
`--focus "<topic>"`	Constrain roam to a specific topic (e.g. `"UI/UX"`, `"tests"`)
`--worktree` / `-w`	Run loop in an isolated git worktree via worktrunk

Examples

# 🔨 Standard build with TUI
ralph build

# 🌍 Improvement sweep — roam across the whole codebase
ralph build --roam

# 🤖 Headless build for CI (no TUI, no color, max 10 iterations)
ralph build --no-tui --no-color --max 10

# 🧠 Smart run — plan first if no plan exists, then build
ralph loop run

# 📐 Run 3 planning iterations only
ralph loop plan --max 3

# 🌿 Isolated build in a git worktree (requires worktrunk)
ralph build --worktree

# 🌿 Headless worktree build
ralph build -w --no-tui --max 5

📁 Project Structure

📦 RalphSpec
├── 📂 cmd/ralph/                   # CLI entry point (cobra)
│   ├── 🎯 main.go                  #   └─ Root command, signal handling
│   ├── 🔧 commands.go              #   └─ Subcommand definitions
│   ├── ⚡ execute.go               #   └─ Loop execution & TUI wiring
│   ├── 🔌 wiring.go                #   └─ LoopController, store, TUI plumbing
│   └── 🛠️ speckit_cmds.go          #   └─ specify/plan/clarify/tasks/run
├── 📂 internal/
│   ├── 📂 claude/                   # Claude CLI adapter & stream-JSON parser
│   ├── 📂 config/                   # TOML config parsing (ralph.toml)
│   ├── 📂 git/                      # Pull, push, branch, stash helpers
│   ├── 📂 loop/                     # Core iteration: prompt → claude → parse → git
│   ├── 📂 notify/                   # Desktop notifications on loop events
│   ├── 📂 orchestrator/             # Parallel-agent orchestration; one Regent per agent
│   ├── 📂 regent/                   # Supervisor: crash/hang detection, rollback
│   ├── 📂 spec/                     # Spec file discovery & active spec resolution
│   ├── 📂 store/                    # JSONL session log storage & querying
│   ├── 📂 tui/                      # Bubbletea + lipgloss multi-panel TUI
│   │   ├── 📂 components/           #   └─ Reusable TUI components
│   │   └── 📂 panels/              #   └─ Specs, Iterations, Main, Secondary
│   └── 📂 worktree/                 # Git worktree detection, listing, and lifecycle
├── 📂 specs/                        # Feature specifications (spec kit layout)
│   ├── 📂 003-tui-redesign/
│   ├── 📂 004-speckit-alignment/
│   ├── 📂 005-spec-bounded-roam/
│   ├── 📂 006-polish-and-hardening/
│   ├── 📂 007-worktree-support/
│   └── 📂 008-tui-overhaul/
├── 📄 ralph.toml                    # Project configuration
├── 📄 CLAUDE.md                     # AI coding instructions
├── 📄 PLAN.md                       # Plan mode prompt template
├── 📄 BUILD.md                      # Build mode prompt template
└── 📄 CHRONICLE.md                  # Development history & sweep log

🔒 Safety & Guardrails

Measure	Details
📋 Spec boundaries	Claude is constrained to the active spec directory by default
🧪 Test-gated commits	Regent runs tests after every iteration; bad commits get rolled back
⏪ Automatic rollback	Failed test suite → `git revert` → retry with error context
⏱️ Hang protection	No output for 5 min → process killed and restarted
💀 Crash recovery	Process exit → restart with exponential backoff (up to 3 retries)
🚫 No global state	Dependencies passed explicitly; structs hold state, functions transform it
📡 Full observability	Every event streams to TUI, JSONL session logs, and optional webhooks

🤝 Supported Agents

Agent	Status	Description
🤖 Claude Code CLI	✅	Default — streaming JSON event parser, full integration
🔮 OpenAI Codex	🔜	Planned
💎 Gemini	🔜	Planned
🔧 Custom	🔜	Bring your own agent via adapter interface

_{LISS Consulting, Corp. · Ralph is King. The Regent keeps him honest.}

Name		Name	Last commit message	Last commit date
Latest commit History 237 Commits
.claude		.claude
.github/workflows		.github/workflows
.specify		.specify
cmd/ralph		cmd/ralph
internal		internal
specs		specs
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
BUILD.md		BUILD.md
CHRONICLE.md		CHRONICLE.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
PLAN.md		PLAN.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
ralph.toml		ralph.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

👑 RalphSpec

📑 Table of Contents

⚡ Quick Start

🏗️ Architecture

📜 Spec Kit Workflow

🖥️ TUI Dashboard

⌨️ Keyboard Reference

🏰 The Regent

🌿 Worktrees (Parallel Agents)

Quick Start

Parallel Agents from the Dashboard

Worktree Config

Worktree CLI Commands

⚙️ Configuration

🔑 Environment Variables

🎯 CLI Reference

Top-level Commands

Spec Kit Commands

Loop Commands

Flags (all loop commands)

Examples

📁 Project Structure

🔒 Safety & Guardrails

🤝 Supported Agents

About

Uh oh!

Releases 31

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

👑 RalphSpec

📑 Table of Contents

⚡ Quick Start

🏗️ Architecture

📜 Spec Kit Workflow

🖥️ TUI Dashboard

⌨️ Keyboard Reference

🏰 The Regent

🌿 Worktrees (Parallel Agents)

Quick Start

Parallel Agents from the Dashboard

Worktree Config

Worktree CLI Commands

⚙️ Configuration

🔑 Environment Variables

🎯 CLI Reference

Top-level Commands

Spec Kit Commands

Loop Commands

Flags (all loop commands)

Examples

📁 Project Structure

🔒 Safety & Guardrails

🤝 Supported Agents

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 31

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages