thuongtin/Ralph-TUI.md

## Ralph-TUI.md

      
    Raw
  

              Ralph-TUI.md
            
          
  tags
  
  
  type/guide
  ai/concept/agent
  ai/concept/vibe-coding
  ai/concept/orchestration
  dev/tool/cli
  dev/tool/tui
  dev/open-source
  lang/typescript
  project/vibe-coding
  
  
Ralph TUI – Hướng dẫn từ cơ bản đến thành thạo

Giới thiệu tổng quan

Ralph TUI là một AI Agent Loop Orchestrator – giao diện terminal (TUI) điều phối các AI coding agents làm việc tự động qua danh sách task. Ý tưởng cốt lõi rất đơn giản: kết nối AI coding assistant (theo docs chính thức: Claude Code, OpenCode, Factory Droid) với task tracker, rồi chạy chúng trong vòng lặp tự động – hoàn thành từng task một với khả năng chọn task thông minh, xử lý lỗi, và theo dõi real-time.
Ralph TUI là bước tiến hóa của dự án Ralph gốc (bash loop đơn giản) thành một hệ thống hoàn chỉnh với TypeScript, Bun runtime, plugin architecture, remote control, và giao diện TUI hiện đại.
Thông tin dự án (snapshot 2026-02-25):

Repository: github.com/subsy/ralph-tui
Website: ralph-tui.com
Giấy phép: MIT (miễn phí 100%, mã nguồn mở)
Ngôn ngữ: TypeScript (TSX cho TUI components)
Runtime: Bun (>= 1.0.0)
Phiên bản hiện tại: v0.10.0 (20 tháng 2, 2026)
Stars: 1,954 | Forks: 189
Ngày tạo: 11 tháng 1, 2026
Tests: 1,400+ tests


      graph TB
    CENTER["Ralph TUI"]

    subgraph core ["Core Loop"]
        C1["Select Task"]
        C2["Build Prompt"]
        C3["Execute Agent"]
        C4["Detect Completion"]
        C5["Next Task"]
    end

    subgraph agents ["AI Agents"]
        A1["Claude Code"]
        A2["OpenCode · Gemini CLI"]
        A3["Codex · Kiro CLI"]
        A4["GitHub Copilot · Cursor · Kimi"]
    end

    subgraph trackers ["Task Trackers"]
        T1["prd.json (simple)"]
        T2["Beads (git-backed)"]
    end

    subgraph features ["Tính năng"]
        F1["Session Persistence"]
        F2["Remote Control"]
        F3["Sandbox Execution"]
        F4["Subagent Tracing"]
    end

    CENTER --- core
    CENTER --- agents
    CENTER --- trackers
    CENTER --- features

    style CENTER fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style core fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style agents fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style trackers fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style features fill:#1e272e,color:#dfe6e9,stroke:#fdcb6e,stroke-width:2px
    style C1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style C2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style C3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style C4 fill:#0984e3,color:#fff,stroke:#74b9ff
    style C5 fill:#0984e3,color:#fff,stroke:#74b9ff
    style A1 fill:#00b894,color:#fff,stroke:#55efc4
    style A2 fill:#00b894,color:#fff,stroke:#55efc4
    style A3 fill:#00b894,color:#fff,stroke:#55efc4
    style A4 fill:#00b894,color:#fff,stroke:#55efc4
    style T1 fill:#e17055,color:#fff,stroke:#fab1a0
    style T2 fill:#e17055,color:#fff,stroke:#fab1a0
    style F1 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style F2 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style F3 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style F4 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Tại sao cần Ralph TUI?

Trước Ralph TUI, developer sử dụng AI coding agents theo cách thủ công: mở chat, paste task, chờ AI làm, review, rồi lặp lại. Với dự án có 20-30 tasks, quy trình này cực kỳ mệt mỏi và tốn thời gian. Ralph TUI tự động hóa toàn bộ vòng lặp này.


Vấn đề
Workflow thủ công
Ralph TUI


Chọn task tiếp theo
Developer tự đọc danh sách, quyết định
Tự động chọn theo priority + dependency


Build prompt
Copy-paste context mỗi lần
Template Handlebars, tự inject context


Execute agent
Mở chat mới, paste instructions
Spawn agent instance tự động (fresh context)


Phát hiện hoàn thành
Developer tự đánh giá "xong chưa?"
Auto-detect completion patterns


Theo dõi tiến độ
Mental tracking hoặc markdown notes
TUI dashboard real-time


Xử lý lỗi
Tự debug, tự quyết định retry
Circuit breaker, auto-recovery


Nhiều máy
SSH vào từng máy
Remote control từ 1 TUI


An toàn
Agent có full access
Sandbox execution (bwrap/sandbox-exec)


      graph LR
    subgraph before ["Workflow thủ công"]
        B1["Chọn task"]
        B2["Paste prompt"]
        B3["Chờ AI làm"]
        B4["Review output"]
        B5["Lặp lại..."]
        B1 --> B2 --> B3 --> B4 --> B5
        B5 -.->|"Mệt"| B1
    end

    subgraph after ["Ralph TUI"]
        A1["ralph-tui run"]
        A2["Tự động loop"]
        A3["Dashboard real-time"]
        A4["Tasks complete!"]
        A1 --> A2 --> A3 --> A4
    end

    before -->|"Chuyển sang"| after

    style before fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style after fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style B1 fill:#e17055,color:#fff,stroke:#fab1a0
    style B2 fill:#e17055,color:#fff,stroke:#fab1a0
    style B3 fill:#e17055,color:#fff,stroke:#fab1a0
    style B4 fill:#e17055,color:#fff,stroke:#fab1a0
    style B5 fill:#636e72,color:#dfe6e9,stroke:#b2bec3
    style A1 fill:#00b894,color:#fff,stroke:#55efc4
    style A2 fill:#00b894,color:#fff,stroke:#55efc4
    style A3 fill:#00b894,color:#fff,stroke:#55efc4
    style A4 fill:#0984e3,color:#fff,stroke:#74b9ff

    
      Loading

  
Ralph TUI so với các công cụ khác


Tiêu chí
Ralph TUI
Ralph gốc (bash)
Beads + Gas Town
Claude Code Tasks


Kiểu
TUI orchestrator
Bash loop
Memory + multi-agent
Built-in task list


Agents hỗ trợ
8+ agents
Claude Code only
Mọi agent
Claude Code only


Task tracker
prd.json, Beads
@fix_plan.md
Beads issues
Local tasks


Remote control
WebSocket multi-instance
Không
tmux-based
Không


Session persistence
Crash-safe, resume
Cơ bản
Git-backed
Session-level


Sandbox
bwrap/sandbox-exec
Không
Không
Không


Giao diện
TUI (React-based)
Terminal output
Terminal/TUI
CLI integrated


PRD creation
AI chat mode
Tự viết
CLI tạo issues
Không


Cài đặt

Yêu cầu hệ thống


      graph TD
    subgraph req ["Yêu cầu bắt buộc"]
        BUN["Bun >= 1.0.0"]
        AGENT["Ít nhất 1 AI Agent<br/>(claude, opencode, gemini...)"]
    end

    subgraph optional ["Khuyến nghị"]
        GIT["Git"]
        BD["Beads CLI (bd)"]
    end

    subgraph sandbox_req ["Sandbox (tùy chọn)"]
        BWRAP["bwrap (Linux)"]
        SBEXEC["sandbox-exec (macOS, built-in)"]
    end

    BUN --> READY["Sẵn sàng cài đặt"]
    AGENT --> READY

    style req fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style optional fill:#1e272e,color:#dfe6e9,stroke:#636e72,stroke-width:1px
    style sandbox_req fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:1px
    style BUN fill:#0984e3,color:#fff,stroke:#74b9ff
    style AGENT fill:#0984e3,color:#fff,stroke:#74b9ff
    style GIT fill:#636e72,color:#fff,stroke:#b2bec3
    style BD fill:#636e72,color:#fff,stroke:#b2bec3
    style BWRAP fill:#e17055,color:#fff,stroke:#fab1a0
    style SBEXEC fill:#e17055,color:#fff,stroke:#fab1a0
    style READY fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px

    
      Loading

  
Yêu cầu
Chi tiết


Bun
Runtime JavaScript/TypeScript. Cài: curl -fsSL https://bun.sh/install | bash


AI Agent
Ít nhất 1 agent đã cài trong PATH: claude, opencode, gemini, codex, kiro


Git
Khuyến nghị cho version control


Beads
Tùy chọn – nếu muốn dùng Beads tracker thay vì prd.json


Cài đặt Ralph TUI

# Cài đặt global
bun install -g ralph-tui

# Kiểm tra
ralph-tui --version
# Output: 0.10.0
Kiểm tra sức khỏe

ralph-tui doctor
Lệnh doctor kiểm tra: Bun version, agents có sẵn, trackers, config files, permissions.

Kiến trúc hệ thống

Ralph TUI được xây dựng theo kiến trúc plugin-based với 4 lớp chính:

  
      graph TD
    subgraph tui_layer ["Lớp TUI"]
        TUI1["React/OpenTUI Components"]
        TUI2["TabBar · Toast · Dashboard"]
        TUI3["Keyboard Shortcuts"]
    end

    subgraph engine_layer ["Lớp Engine"]
        ENG1["Iteration Loop"]
        ENG2["Task Selection"]
        ENG3["Prompt Builder (Handlebars)"]
        ENG4["Completion Detection"]
    end

    subgraph plugin_layer ["Lớp Plugin"]
        subgraph agent_plugins ["Agent Plugins"]
            AP1["Claude Code"]
            AP2["OpenCode"]
            AP3["Gemini CLI"]
            AP4["Codex · Kiro · Copilot · Cursor · Kimi"]
        end
        subgraph tracker_plugins ["Tracker Plugins"]
            TP1["JSON (prd.json)"]
            TP2["Beads"]
            TP3["Beads-BV · Beads-Rust"]
        end
    end

    subgraph infra_layer ["Lớp Infrastructure"]
        INF1["Session Persistence"]
        INF2["Remote Server/Client (WebSocket)"]
        INF3["Sandbox (bwrap/sandbox-exec)"]
        INF4["Config (Zod + TOML)"]
        INF5["Logs · Notifications · Sound"]
    end

    tui_layer --> engine_layer
    engine_layer --> plugin_layer
    plugin_layer --> infra_layer

    style tui_layer fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style engine_layer fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style plugin_layer fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style agent_plugins fill:#2d3436,color:#dfe6e9,stroke:#00b894,stroke-width:1px
    style tracker_plugins fill:#2d3436,color:#dfe6e9,stroke:#00b894,stroke-width:1px
    style infra_layer fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style TUI1 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style TUI2 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style TUI3 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style ENG1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style ENG2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style ENG3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style ENG4 fill:#0984e3,color:#fff,stroke:#74b9ff
    style AP1 fill:#00b894,color:#fff,stroke:#55efc4
    style AP2 fill:#00b894,color:#fff,stroke:#55efc4
    style AP3 fill:#00b894,color:#fff,stroke:#55efc4
    style AP4 fill:#00b894,color:#fff,stroke:#55efc4
    style TP1 fill:#00b894,color:#fff,stroke:#55efc4
    style TP2 fill:#00b894,color:#fff,stroke:#55efc4
    style TP3 fill:#00b894,color:#fff,stroke:#55efc4
    style INF1 fill:#e17055,color:#fff,stroke:#fab1a0
    style INF2 fill:#e17055,color:#fff,stroke:#fab1a0
    style INF3 fill:#e17055,color:#fff,stroke:#fab1a0
    style INF4 fill:#e17055,color:#fff,stroke:#fab1a0
    style INF5 fill:#e17055,color:#fff,stroke:#fab1a0

    
      Loading

  
Core Loop

Vòng lặp cốt lõi của Ralph TUI gồm 5 bước:
SELECT TASK → BUILD PROMPT → EXECUTE AGENT → DETECT COMPLETION → NEXT TASK
     ↑                                                              |
     └──────────────────────────────────────────────────────────────┘


Select Task: Chọn task có priority cao nhất, không bị block (nếu dùng Beads tracker có dependency)
Build Prompt: Dùng Handlebars template để inject task details, project context, cross-iteration memory
Execute Agent: Spawn agent process mới (fresh context mỗi iteration)
Detect Completion: Phân tích output để xác định task đã hoàn thành hay chưa
Next Task: Chuyển sang task tiếp theo, lặp lại cho đến khi hết tasks

Cấu trúc thư mục dự án

ralph-tui/
├── src/
│   ├── cli.tsx                # CLI entry point
│   ├── commands/              # CLI commands
│   │   ├── run.tsx            # Main execution loop
│   │   ├── resume.tsx         # Resume interrupted session
│   │   ├── create-prd.tsx     # Create PRDs with AI
│   │   ├── setup.ts           # Interactive setup wizard
│   │   ├── config.ts          # Config commands
│   │   ├── template.ts        # Template commands
│   │   ├── plugins.ts         # Plugin listing
│   │   ├── logs.ts            # View iteration logs
│   │   ├── status.ts          # Check status
│   │   ├── listen.ts          # Remote listener
│   │   ├── remote.ts          # Remote management
│   │   ├── skills.ts          # Skill management
│   │   ├── doctor.ts          # Diagnostics
│   │   └── info.ts            # Info display
│   ├── config/                # Zod schemas cho validation
│   ├── engine/                # Iteration loop, events
│   ├── plugins/
│   │   ├── agents/            # Agent plugins
│   │   │   ├── claude.ts
│   │   │   ├── opencode.ts
│   │   │   ├── gemini.ts
│   │   │   ├── codex.ts
│   │   │   ├── kiro.ts
│   │   │   ├── cursor.ts
│   │   │   ├── github-copilot.ts
│   │   │   ├── kimi.ts
│   │   │   └── tracing/       # Subagent tracing parser
│   │   └── trackers/          # Tracker plugins
│   │       ├── beads/         # Git-backed issues
│   │       └── json/          # Simple prd.json
│   ├── remote/                # WebSocket server/client
│   ├── session/               # Session persistence & locking
│   ├── sandbox/               # Sandbox execution
│   ├── templates/             # Handlebars prompt templates
│   ├── tui/                   # Terminal UI components
│   └── chat/                  # AI chat for PRD creation
├── skills/                    # Bundled skills
├── website/                   # Next.js docs site
└── tests/                     # 1,400+ tests


Quick Start (5 phút)

Bước 1: Setup dự án

cd your-project
ralph-tui setup
Lệnh setup sẽ hướng dẫn bạn:

Chọn AI agent (Claude Code, OpenCode, v.v.)
Chọn task tracker (prd.json hoặc Beads)
Cấu hình cơ bản

Bước 2: Tạo PRD (Product Requirements Document)

# Tạo PRD với AI assistance (chat mode)
ralph-tui create-prd --chat
# Alias ngắn gọn:
ralph-tui prime
AI sẽ hỏi bạn về mục tiêu/requirements, rồi sinh ra PRD Markdown (thường ở ./tasks/prd-<feature>.md) và file task ./prd.json sẵn để chạy.
Hoặc nếu đã có sẵn PRD, tạo prd.json thủ công:
{
  "name": "My Todo App",
  "branchName": "feature/todo-app",
  "userStories": [
    {
      "id": "US-001",
      "title": "Setup Vite + React + TypeScript",
      "description": "Khởi tạo project scaffold, cấu hình lint/typecheck cơ bản.",
      "acceptanceCriteria": [
        "Project chạy được ở chế độ dev",
        "Typecheck pass",
        "Lint pass"
      ],
      "priority": 1,
      "passes": false
    },
    {
      "id": "US-002",
      "title": "Todo model + state management",
      "description": "Tạo model Todo và state management cho danh sách todo.",
      "acceptanceCriteria": [
        "CRUD todo chạy được",
        "Không có lỗi typecheck"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"]
    }
  ]
}
Bước 3: Chạy Ralph

ralph-tui run --prd ./prd.json
Ralph sẽ:

Mở TUI dashboard
Nhấn s để start execution
Tự động pick task → build prompt → execute agent → next task
Bạn theo dõi real-time qua TUI


      sequenceDiagram
    participant U as Bạn
    participant R as Ralph TUI
    participant A as AI Agent

    U->>R: ralph-tui run --prd ./prd.json
    R->>R: Load tasks, validate config
    U->>R: Nhấn 's' (start)

    loop Mỗi task
        R->>R: Select highest priority task
        R->>R: Build prompt (Handlebars template)
        R->>A: Spawn fresh agent instance
        A->>A: Implement task (fresh context)
        A-->>R: Output + completion signal
        R->>R: Detect completion, update status
        R->>R: Log iteration, next task
    end

    R-->>U: All tasks complete!

    
      Loading

  
Khái niệm cốt lõi

1. Task Trackers

Ralph TUI hỗ trợ 3 tracker phổ biến (theo docs chính thức):
JSON / prd.json (Simple)

File JSON đơn giản chứa danh sách tasks. Phù hợp cho solo dev, dự án nhỏ.
{
  "name": "My App",
  "userStories": [
    {
      "id": "US-001",
      "title": "Setup project",
      "description": "Khởi tạo dự án và cấu hình cơ bản.",
      "acceptanceCriteria": [
        "Có thể chạy dev server",
        "Typecheck pass"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    }
  ]
}
Một vài điểm quan trọng của schema (JSON tracker):

Task = mỗi phần tử trong userStories
Ralph chỉ chọn story có passes: false và không bị block bởi dependsOn
priority là số (1 = cao nhất)

Beads (Git-backed)

Hệ thống issue tracking phân tán với dependency graph. Phù hợp cho dự án phức tạp, multi-agent.
# Chạy với Beads epic
ralph-tui run --epic my-epic-id


So sánh
prd.json
Beads


Setup
Zero – tạo file JSON
Cần cài bd CLI


Dependencies
Mảng ID đơn giản
6 loại dependency có ngữ nghĩa


Multi-agent
Không tối ưu
Hash-based IDs, 3-way merge


Persistence
File trên disk
Git-backed, offline-first


Khi nào dùng
Solo dev, prototype
Team, dự án dài hạn


Beads-BV (Graph-based)

Nếu dependency graph phức tạp, bạn có thể dùng beads-bv để chọn task “thông minh” dựa trên phân tích đồ thị:
ralph-tui run --tracker beads-bv --epic my-epic-id

Note: beads-bv cần thêm bv (Beads Viewer). Nếu bv không có, tracker sẽ fallback về Beads thường.

2. Agent Plugins

Ralph TUI hỗ trợ nhiều AI agents qua hệ thống plugin. Theo docs chính thức, 3 agent built-in được tài liệu hóa rõ nhất là Claude Code, OpenCode, và Factory Droid (các plugin khác tùy phiên bản/nhánh repo):

  
      graph TD
    RALPH["Ralph TUI Engine"]

    subgraph agents ["Agent Plugins"]
        CL["Claude Code<br/>claude"]
        OC["OpenCode<br/>opencode"]
        GE["Gemini CLI<br/>gemini"]
        CO["Codex<br/>codex"]
        KI["Kiro CLI<br/>kiro"]
        GH["GitHub Copilot<br/>github-copilot"]
        CU["Cursor<br/>cursor"]
        KM["Kimi<br/>kimi"]
    end

    RALPH --> agents

    style RALPH fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style agents fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style CL fill:#0984e3,color:#fff,stroke:#74b9ff
    style OC fill:#00b894,color:#fff,stroke:#55efc4
    style GE fill:#e17055,color:#fff,stroke:#fab1a0
    style CO fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style KI fill:#636e72,color:#fff,stroke:#b2bec3
    style GH fill:#636e72,color:#fff,stroke:#b2bec3
    style CU fill:#636e72,color:#fff,stroke:#b2bec3
    style KM fill:#636e72,color:#fff,stroke:#b2bec3

    
      Loading

  
# Override agent cho một run
ralph-tui run --agent claude --prd ./prd.json
ralph-tui run --agent opencode --prd ./prd.json
ralph-tui run --agent droid --prd ./prd.json   # Factory Droid (nếu cài)

# Override model
ralph-tui run --agent claude --model sonnet --prd ./prd.json
ralph-tui run --agent claude --model opus --prd ./prd.json
ralph-tui run --agent opencode --model openai/gpt-4o --prd ./prd.json
ralph-tui run --agent opencode --model anthropic/claude-3-5-sonnet --prd ./prd.json

# Xem danh sách agents
ralph-tui plugins agents

# Xem danh sách trackers
ralph-tui plugins trackers
3. Session Persistence

Ralph TUI tự động lưu trạng thái session. Nếu bị crash, mất điện, hoặc bạn nhấn Ctrl+C:
# Kiểm tra trạng thái session
ralph-tui status

# Resume session đã bị gián đoạn
ralph-tui resume
Cơ chế hoạt động:

Session state lưu trên disk với file lock
Mỗi iteration được log riêng biệt
Resume tự động pick up từ task cuối cùng chưa hoàn thành

4. Subagent Tracing

Khi AI agent tạo subagents (ví dụ Claude Code spawn Task agents), Ralph TUI hiển thị cây subagent real-time trong TUI:


Phím
Hành động


T (Shift+T)
Bật/tắt panel subagent tree


t
Chuyển đổi mức độ chi tiết


5. Cross-iteration Context

Ralph TUI tự động tích lũy context giữa các iteration. Khi task 3 đang chạy, agent có thể biết task 1 và 2 đã làm gì – giúp tránh lặp lại công việc hoặc conflicts.
6. Completion Detection

Ralph TUI nhận biết task hoàn thành dựa trên token trong output của agent:

Khi agent in ra: <promise>COMPLETE</promise> → Ralph đánh dấu task “done” và chuyển sang task tiếp theo.
Nếu task không tự complete (hoặc complete sai), thường là do prompt template chưa nhắc rõ token này.

Plugin Architecture Deep Dive

Ralph TUI thiết kế theo dạng plugin để có thể “mix & match”:

Agent plugin: kết nối tới AI coding CLI (Claude Code, OpenCode, Factory Droid…)
Tracker plugin: kết nối tới nguồn task (prd.json, Beads, Beads-BV…)

Điểm hay là: agent và tracker độc lập → bạn có thể dùng Claude + Beads, hoặc OpenCode + prd.json… tùy workflow.
So sánh Agent Plugins (theo docs chính thức)


Feature
Claude Code
OpenCode
Factory Droid


Provider
Anthropic
Multi-provider
Factory


Models
sonnet, opus, haiku
provider/model (vd: openai/gpt-4o)
Theo danh sách model của Factory


Subagent Tracing
Có (Task tool)
Có (Task tool)
Không


File Context
Có (--add-dir)
Có (--file)
Không (dùng --cwd)


Streaming
Có
Có
Có


So sánh Tracker Plugins (theo docs chính thức)


Feature
JSON
Beads
Beads-BV


External CLI
None
bd
bd + bv


Dependencies
Có
Có
Có


Priority Ordering
Có
Có
Có + PageRank


Hierarchy (Epics)
Không
Có
Có


Graph Analysis
Không
Không
Có


Git Sync
Không
Có
Có


Beads-BV – Smart Task Selection

beads-bv là phiên bản nâng cấp của Beads tracker: nó dùng phân tích đồ thị dependency (ví dụ PageRank, critical path, betweenness…) để ưu tiên “task cổ chai” – task nào làm xong sẽ unblock được nhiều việc nhất.
Các cờ “robot” hay gặp của BV:


Flag
Purpose


--robot-triage
Get ranked recommendations


--robot-next
Get single top pick


--robot-plan
Get parallel execution tracks


--robot-insights
Get full graph metrics


Parallel Execution

Mặc định ralph-tui chạy sequential. Parallel là opt-in, và mỗi worker chạy trong git worktree riêng để cách ly thay đổi.
# Force parallel với 4 workers
ralph-tui run --prd ./prd.json --parallel 4

# Force sequential
ralph-tui run --prd ./prd.json --serial
Trong TUI (khi chạy parallel):

w: bật/tắt workers view
m: bật/tắt merge progress view

Task Range Filtering

Nếu PRD rất dài, bạn có thể chạy một đoạn task theo index (1-indexed) bằng --task-range:
ralph-tui run --prd ./prd.json --task-range 1-5
ralph-tui run --prd ./prd.json --task-range 3-
ralph-tui run --prd ./prd.json --task-range -10

CLI Reference

Tổng hợp lệnh


      graph TD
    subgraph exec ["Execution"]
        E1["ralph-tui run"]
        E2["ralph-tui resume"]
        E3["ralph-tui status"]
        E4["ralph-tui logs"]
    end

    subgraph setup_cmd ["Setup"]
        S1["ralph-tui setup"]
        S2["ralph-tui create-prd"]
        S3["ralph-tui convert"]
    end

    subgraph config_cmd ["Configuration"]
        C1["ralph-tui config show"]
        C2["ralph-tui template show"]
        C3["ralph-tui plugins agents"]
        C4["ralph-tui plugins trackers"]
    end

    subgraph remote_cmd ["Remote"]
        R1["ralph-tui run --listen"]
        R2["ralph-tui remote add"]
        R3["ralph-tui remote list"]
        R4["ralph-tui remote test"]
    end

    subgraph util_cmd ["Utilities"]
        U1["ralph-tui doctor"]
        U2["ralph-tui info"]
        U3["ralph-tui skills install"]
    end

    style exec fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style setup_cmd fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style config_cmd fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style remote_cmd fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style util_cmd fill:#1e272e,color:#dfe6e9,stroke:#fdcb6e,stroke-width:2px
    style E1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style E2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style E3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style E4 fill:#0984e3,color:#fff,stroke:#74b9ff
    style S1 fill:#00b894,color:#fff,stroke:#55efc4
    style S2 fill:#00b894,color:#fff,stroke:#55efc4
    style S3 fill:#00b894,color:#fff,stroke:#55efc4
    style C1 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style C2 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style C3 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style C4 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style R1 fill:#e17055,color:#fff,stroke:#fab1a0
    style R2 fill:#e17055,color:#fff,stroke:#fab1a0
    style R3 fill:#e17055,color:#fff,stroke:#fab1a0
    style R4 fill:#e17055,color:#fff,stroke:#fab1a0
    style U1 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style U2 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style U3 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Execution Commands

INFO: Chạy ralph-tui không kèm command cũng sẽ mở TUI, rồi bạn start execution trong UI.
# === RUN ===
ralph-tui run --prd ./prd.json              # Chạy với PRD file
ralph-tui run --epic my-epic-id             # Chạy với Beads epic
ralph-tui run --agent claude                # Override agent
ralph-tui run --model sonnet                # Override model
ralph-tui run --iterations 5               # Giới hạn số iteration
ralph-tui run --delay 5000                  # Delay giữa các iteration (ms)
ralph-tui run --task-range 1-5              # Chỉ chạy task 1-5 (1-indexed)
ralph-tui run --parallel 4                  # Parallel execution với 4 workers
ralph-tui run --serial                      # Force sequential (tắt parallel)
ralph-tui run --prompt ./my-template.hbs     # Dùng custom prompt template
ralph-tui run --output-dir ./logs/ralph      # Thư mục log iterations
ralph-tui run --progress-file ./.ralph-tui/progress.md # Cross-iteration progress file
ralph-tui run --headless                    # Chạy không TUI (cho CI/CD)
ralph-tui run --no-setup                    # Skip setup dù chưa có config
ralph-tui run --sandbox                     # Chạy trong sandbox (nếu bật trong version bạn dùng)
ralph-tui run --theme dracula              # Dùng theme khác (nếu bật trong version bạn dùng)

# === RESUME ===
ralph-tui resume                            # Resume session gián đoạn

# === STATUS ===
ralph-tui status                            # Xem trạng thái hiện tại

# === LOGS ===
ralph-tui logs                              # Xem output của các iteration
Setup & PRD Commands

# === SETUP ===
ralph-tui setup                             # Interactive setup wizard

# === CREATE PRD ===
ralph-tui create-prd                        # Tạo PRD với AI chat (default)
ralph-tui prime                             # Alias cho create-prd
ralph-tui create-prd --prd-skill my-skill   # Dùng custom PRD skill
ralph-tui create-prd --agent claude         # Override agent cho PRD creation
ralph-tui create-prd --output ./docs        # Output directory

# === CONVERT ===
ralph-tui convert                           # Convert PRD sang tracker format
create-prd (deep dive)

Theo docs chính thức, mode khuyến nghị là chat/AI:
ralph-tui create-prd --chat   # (recommended)
ralph-tui create-prd --ai     # alias cho --chat
Một số option hay dùng:

--prd-skill <name>: dùng custom PRD skill
--timeout <ms>: timeout cho agent call (0 = không timeout, mặc định 180000ms)
--output <dir> (-o): thư mục output (mặc định ./tasks)
--force: ghi đè file đã tồn tại

Yêu cầu format PRD (để convert sang task được):

User story phải có heading theo pattern: ### US-XXX: Title
Có thể thêm ## Quality Gates để liệt kê command bắt buộc pass (vd: bun run typecheck, bun run lint). Ralph sẽ dùng phần này làm “quality bar” khi chạy.

Configuration Commands

# === CONFIG ===
ralph-tui config show                       # Hiển thị merged config

# === TEMPLATE ===
ralph-tui template show                     # Hiển thị prompt template hiện tại

# === PLUGINS ===
ralph-tui plugins agents                    # Liệt kê agent plugins
ralph-tui plugins trackers                  # Liệt kê tracker plugins
Remote Commands

# === LISTEN (trên server) ===
ralph-tui run --listen --prd ./prd.json     # Bật remote listener
ralph-tui run --listen --listen-port 8080   # Custom port
ralph-tui run --listen --rotate-token       # Rotate auth token

# === REMOTE (trên client) ===
ralph-tui remote add prod server:7890 --token TOKEN
ralph-tui remote list                       # Liệt kê remotes + status
ralph-tui remote test prod                  # Test connectivity
ralph-tui remote remove prod               # Xóa remote
ralph-tui remote push-config prod          # Push config đến remote
ralph-tui remote push-config --all          # Push đến tất cả remotes
ralph-tui remote push-config prod --preview # Preview trước khi push
Utility Commands

# === DOCTOR ===
ralph-tui doctor                            # Kiểm tra sức khỏe
ralph-tui doctor --json                     # JSON output

# === INFO ===
ralph-tui info                              # Thông tin hệ thống

# === SKILLS ===
ralph-tui skills install                    # Cài skills cho agent
ralph-tui skills install --agent claude     # Cài cho agent cụ thể

TUI – Giao diện terminal

Keyboard Shortcuts


Phím
Hành động


s
Start execution


p
Pause / Resume execution


+ / =
Add 10 iterations


- / _
Remove 10 iterations


j / ↓
Navigate down


k / ↑
Navigate up


Tab
Switch focus giữa các panel


Enter
Drill into item đang chọn


Esc
Go back / đóng dialog


o
Cycle right panel views (details → output → prompt)


O
Jump thẳng tới prompt preview


d
Toggle dashboard (trạng thái, agent, tracker, git, sandbox)


h
Toggle show/hide closed tasks


r
Refresh task list từ tracker


T
Toggle subagent tree panel (Shift+T)


t
Cycle mức độ chi tiết subagent


w
Toggle workers view (parallel mode)


m
Toggle merge progress view (parallel mode)


l
Mở epic selector (Beads tracker)


,
Mở settings (tab local)


C
Mở config viewer read-only (Shift+C)


q
Quit


?
Hiển thị help


1-9
Chuyển tab (remote instances)


[ / ]
Tab trước / sau


a
Thêm remote mới


e
Sửa remote hiện tại


x
Xóa remote hiện tại


Dashboard (d key)

Dashboard hiển thị:

Trạng thái execution hiện tại và task đang chạy
Tên agent và model (vd: claude-code, anthropic/claude-sonnet)
Tracker source (vd: prd, beads)
Git branch với dirty indicator (vd: repo:main*)
Sandbox status (locked/unlocked) với mode
Auto-commit setting

Themes

Ralph TUI hỗ trợ custom themes:
# Themes có sẵn
ralph-tui run --theme bright
ralph-tui run --theme catppuccin
ralph-tui run --theme dracula
ralph-tui run --theme high-contrast
ralph-tui run --theme solarized-light

# Custom theme file
ralph-tui run --theme ./my-theme.json

Cấu hình

File cấu hình

Ralph TUI đọc config theo thứ tự ưu tiên (cao → thấp):


Nguồn
Scope
Ghi chú


CLI flags
Per-run
Ưu tiên cao nhất (override config file)


.ralph-tui/config.toml
Project
Settings riêng cho dự án


~/.config/ralph-tui/config.toml
Global
Default cho tất cả dự án


Config file dùng format TOML, validate bằng Zod schemas.
Config mẫu

# .ralph-tui/config.toml (ví dụ theo docs)

# Default tracker và agent
tracker = "json"
agent = "claude"

# Execution limits
maxIterations = 10

# Agent-specific options
[agentOptions]
model = "sonnet"

# Error handling
[errorHandling]
strategy = "skip"
maxRetries = 3
retryDelayMs = 5000

# Subagent tracing (off|minimal|moderate|full)
subagentTracingDetail = "moderate"
Rate Limit Handling

Nếu bạn chạy lâu và hay dính rate limit (đặc biệt với Claude), có thể cấu hình retry + fallback agent:
agent = "claude"
fallbackAgents = ["opencode"]

[rateLimitHandling]
enabled = true
maxRetries = 3
baseBackoffMs = 5000
recoverPrimaryBetweenIterations = true
Ý nghĩa nhanh:

Retry với backoff khi rate limit
Quá maxRetries thì chuyển qua fallbackAgents
Sau mỗi iteration thử quay lại primary agent

File cấu hình khác


File
Mục đích


~/.config/ralph-tui/config.toml
Global config


.ralph-tui/config.toml
Project config


~/.config/ralph-tui/remotes.toml
Remote server list


~/.config/ralph-tui/remote.json
Server token storage


~/.config/ralph-tui/audit.log
Audit log cho remote actions


Remote Control – Quản lý nhiều instance

Một trong những tính năng độc đáo nhất của Ralph TUI: điều khiển nhiều instance chạy trên các máy khác nhau từ một TUI duy nhất.

  
      graph TD
    subgraph local ["Máy local (Client)"]
        CLIENT["Ralph TUI<br/>Tab: LOCAL | prod | staging | dev"]
    end

    subgraph remote1 ["VPS Production"]
        SERVER1["ralph-tui run --listen<br/>Port 7890"]
    end

    subgraph remote2 ["Staging Server"]
        SERVER2["ralph-tui run --listen<br/>Port 7890"]
    end

    subgraph remote3 ["Dev Machine"]
        SERVER3["ralph-tui run --listen<br/>Port 7890"]
    end

    CLIENT -->|"WebSocket"| SERVER1
    CLIENT -->|"WebSocket"| SERVER2
    CLIENT -->|"WebSocket"| SERVER3

    style local fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style remote1 fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style remote2 fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style remote3 fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style CLIENT fill:#0984e3,color:#fff,stroke:#74b9ff
    style SERVER1 fill:#00b894,color:#fff,stroke:#55efc4
    style SERVER2 fill:#e17055,color:#fff,stroke:#fab1a0
    style SERVER3 fill:#6c5ce7,color:#fff,stroke:#a29bfe

    
      Loading

  
Setup Remote

Trên server (remote machine):
# Start ralph với remote listener
ralph-tui run --listen --prd ./prd.json

# Output:
# ═══════════════════════════════════════════════════════════════
#                    Remote Listener Enabled
# ═══════════════════════════════════════════════════════════════
#   Port: 7890
#   New server token generated:
#   OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ
#   ⚠️  Save this token securely - it won't be shown again!
# ═══════════════════════════════════════════════════════════════
Trên local machine (client):
# Thêm remote
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...

# Test kết nối
ralph-tui remote test prod

# Mở TUI – sẽ thấy tabs cho local + remote
ralph-tui
Bảo mật (Two-tier Token System)


Loại Token
Thời hạn
Mục đích


Server Token
90 ngày
Authentication ban đầu, lưu trên disk


Connection Token
24 giờ
Session authentication, auto-refresh


Tính năng bảo mật:

Không token → chỉ bind localhost (127.0.0.1)
Có token → bind tất cả interfaces (0.0.0.0)
Tất cả kết nối yêu cầu authentication
Mọi remote action được log vào audit.log
Token chỉ hiển thị một lần khi generate

Connection Resilience


Auto-reconnect: Exponential backoff từ 1s đến 30s (tối đa 10 retries)
Silent retries: 3 retry đầu im lặng, sau đó hiển thị toast notification
Status indicators: ● connected, ◐ connecting, ⟳ reconnecting, ○ disconnected
Metrics: Latency (ms) và connection duration hiển thị trên tab bar

Remote Control Actions

Khi kết nối remote, bạn có full control:

View: Agent output, logs, progress, task list
Control: Pause, resume, cancel execution
Modify: Add/remove iterations, refresh tasks
Start: Bắt đầu execution mới

Tất cả operations có latency <100ms.
Push Config đến Remote

# Push config đến 1 remote
ralph-tui remote push-config prod

# Preview trước khi push
ralph-tui remote push-config prod --preview

# Push đến tất cả remotes
ralph-tui remote push-config --all

# Push chỉ global hoặc project scope
ralph-tui remote push-config prod --scope global
ralph-tui remote push-config prod --scope project

Sandbox Execution

Ralph TUI hỗ trợ chạy agent trong môi trường cách ly (sandbox), giới hạn quyền truy cập file system và network:
ralph-tui run --sandbox --prd ./prd.json


Platform
Công nghệ
Yêu cầu


macOS
sandbox-exec
Built-in (không cần cài thêm)


Linux
bwrap (bubblewrap)
Cần cài: apt install bubblewrap


Dashboard hiển thị trạng thái sandbox: locked (enabled) hoặc unlocked (disabled).

Skills System

Ralph TUI tích hợp hệ thống skills cho phép tạo PRD trực tiếp trong AI agent:
Cài đặt Skills

# Cài tất cả skills cho tất cả agents
bunx add-skill subsy/ralph-tui --all

# Cài cho agent cụ thể
bunx add-skill subsy/ralph-tui -a claude-code -g -y

# Hoặc dùng wrapper của ralph-tui
ralph-tui skills install
ralph-tui skills install --agent claude
Sử dụng Skills trong Agent

Sau khi cài, bạn có 3 slash commands trong AI agent:


Slash Command
Mô tả


/ralph-tui-prd
Tạo PRD interactively


/ralph-tui-create-json
Convert PRD → prd.json


/ralph-tui-create-beads
Convert PRD → Beads issues


Workflow: Tạo PRD trong agent (có thể reference source files với @filename) → Convert sang prd.json → Chạy ralph-tui run để autonomous execution.
Custom Skills Directory

# Trong config.toml
skills_dir = "/path/to/my-skills"
# Dùng custom skill
ralph-tui create-prd --prd-skill my-custom-skill
Mỗi skill phải là folder chứa file SKILL.md.

Workflows thực hành

Workflow 1: Solo Dev – PRD → Autonomous Implementation


      graph LR
    W1["ralph-tui setup"]
    W2["ralph-tui create-prd"]
    W3["Review prd.json"]
    W4["ralph-tui run --prd ./prd.json"]
    W5["Monitor TUI"]
    W6["Review commits"]

    W1 -->|"1. Setup"| W2
    W2 -->|"2. Tạo PRD"| W3
    W3 -->|"3. Review"| W4
    W4 -->|"4. Auto-run"| W5
    W5 -->|"5. Done"| W6

    style W1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style W2 fill:#00b894,color:#fff,stroke:#55efc4
    style W3 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style W4 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style W5 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style W6 fill:#00b894,color:#fff,stroke:#55efc4

    
      Loading

  
# 1. Setup
cd my-project && git init
ralph-tui setup

# 2. Tạo PRD
ralph-tui create-prd --chat
# AI hỏi về dự án, tạo prd.json

# 3. Review prd.json, sửa nếu cần
# (mở file, kiểm tra tasks, priorities, descriptions)

# 4. Chạy
ralph-tui run --prd ./prd.json

# 5. Nhấn 's' để start, theo dõi qua TUI
# 6. Khi xong, review git log
Workflow 2: Beads Integration – Dependency-aware Execution

# 1. Cài Beads
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# 2. Khởi tạo Beads trong dự án
bd init

# 3. Tạo epic và tasks
bd create "REST API" -t epic -p 0
bd create "Database schema" -p 1 --parent bd-a1b2
bd create "Auth middleware" -p 1 --parent bd-a1b2
bd dep add bd-a1b2.2 bd-a1b2.1  # Auth cần DB trước

# 4. Chạy Ralph với Beads epic
ralph-tui run --epic bd-a1b2

# Ralph sẽ tự động chọn tasks theo dependency order
Workflow 3: Multi-machine – Remote Orchestration

# === Trên server 1 (production tasks) ===
ralph-tui run --listen --prd ./prod-tasks.json

# === Trên server 2 (staging tasks) ===
ralph-tui run --listen --prd ./staging-tasks.json

# === Trên laptop (control center) ===
ralph-tui remote add prod server1:7890 --token TOKEN1
ralph-tui remote add staging server2:7890 --token TOKEN2

# Mở TUI – 3 tabs: LOCAL | prod | staging
ralph-tui

# Điều khiển tất cả từ 1 nơi!
Workflow 4: bmalph Integration – Planning → Execution Pipeline

Ralph TUI là engine execution đằng sau bmalph (framework kết hợp BMAD planning + Ralph execution):
# 1. Cài bmalph
npm install -g bmalph

# 2. Planning (BMAD Phase 1-3)
cd my-project
bmalph init
# Trong Claude Code: /analyst → /create-prd → /create-architecture → /create-epics-stories

# 3. Transition
# Trong Claude Code: /bmalph-implement
# → Generate @fix_plan.md và specs

# 4. Execution (dùng Ralph gốc hoặc Ralph TUI)
ralph-tui run --prd ./prd.json
Workflow 5: Headless – CI/CD Integration

# Chạy không có TUI (cho automated pipelines)
ralph-tui run --headless --prd ./prd.json --iterations 10

# Kết hợp với giới hạn iteration để kiểm soát chi phí
ralph-tui run --headless --prd ./prd.json --iterations 5 --agent claude --model haiku

Ví dụ thực tế: Xây dựng Todo App

Bước 1: Setup

mkdir todo-app && cd todo-app
git init
ralph-tui setup
# Chọn: Claude Code, prd.json tracker
Bước 2: Tạo PRD

ralph-tui create-prd --chat
AI sẽ hỏi:

"Ứng dụng này làm gì?"
"Ai là người dùng chính?"
"Cần những tính năng gì?"

Kết quả: prd.json với ~8-12 tasks.
Bước 3: Review và chỉnh sửa

Mở prd.json, kiểm tra:

Tasks có đúng scope không?
Priority đã hợp lý chưa?
Descriptions đủ chi tiết cho AI hiểu?

Bước 4: Chạy Ralph TUI

ralph-tui run --prd ./prd.json
TUI hiện lên:

Nhấn s → Start
Nhấn d → Xem dashboard (agent, task hiện tại, git branch)
Nhấn T → Xem subagent tree
Quan sát AI implement từng task
Nhấn p nếu muốn tạm dừng
Khi xong: review code, chạy tests

# Xem logs nếu cần
ralph-tui logs

# Xem trạng thái
ralph-tui status
Bước 5: Tiếp tục phát triển

Thêm tasks mới vào prd.json:
{
  "id": "US-013",
  "title": "Add dark mode support",
  "description": "Implement theme switching...",
  "acceptanceCriteria": [
    "Có thể toggle dark/light",
    "Không break layout hiện có"
  ],
  "priority": 3,
  "passes": false,
  "dependsOn": []
}
# Resume với tasks mới
ralph-tui run --prd ./prd.json
# Ralph sẽ chỉ pick `userStories` có `passes: false` (và không bị block bởi `dependsOn`)

Prompt Templates (Handlebars)

Ralph TUI sử dụng Handlebars templates để build prompt cho mỗi iteration. Template quyết định AI agent nhận được context gì.
Xem template hiện tại

ralph-tui template show
Custom template

Template mặc định inject:

Task title và description
Project context
Cross-iteration progress
Specs và constraints

Và quan trọng nhất: template nên nhắc agent kết thúc bằng token hoàn thành để Ralph auto-advance:
<promise>COMPLETE</promise>

Nếu thấy task “làm xong” nhưng không tự chuyển, thường là do thiếu dòng này trong prompt.
Bạn có thể customize template trong config nếu cần thêm/bớt context.

Troubleshooting

Bảng xử lý lỗi thường gặp


Vấn đề
Nguyên nhân
Giải pháp


ralph-tui: command not found
Chưa cài hoặc Bun không trong PATH
bun install -g ralph-tui


Agent không chạy
Agent CLI chưa cài hoặc không trong PATH
which claude / which opencode


PRD validation fail
Format prd.json sai
Kiểm tra schema JSON, dùng ralph-tui create-prd


Session lock exists
Có instance khác đang chạy, hoặc lần trước tắt không sạch
ralph-tui resume --force hoặc rm .ralph-tui/ralph.lock


Tasks stuck trong in_progress
Crash/force-kill khi đang chạy
ralph-tui resume (thường tự reset), hoặc bd update TASK-ID --status open


Session won't resume
Session file/lock bị lỗi hoặc thiếu
ls -la .ralph-tui/session.json, `cat .ralph-tui/session.json


Orphaned worktrees (parallel)
Bị force-kill khi chạy parallel
git worktree list, git worktree prune (và remove worktree orphan nếu cần)


Merge conflicts (parallel)
Nhiều workers sửa cùng file
Ralph thử AI-assisted resolve; nếu fail thì xử lý conflict thủ công hoặc re-queue chạy sequential


Báo lỗi (bug report)
Cần đủ context để maintainers debug
ralph-tui info -c rồi đính kèm vào GitHub issue


Remote connection fail
Token sai hoặc port blocked
ralph-tui remote test <alias>


Sandbox fail (Linux)
bwrap chưa cài
apt install bubblewrap


Sandbox fail (macOS)
Permission issue
Kiểm tra SIP settings


Task stuck in loop
AI không hoàn thành được task
Review task description, chia nhỏ hơn


doctor báo lỗi
Config hoặc dependencies thiếu
Theo hướng dẫn ralph-tui doctor


Debug

# Kiểm tra sức khỏe
ralph-tui doctor

# Xem config đã merge
ralph-tui config show

# Xem logs iteration
ralph-tui logs

# Xem thông tin hệ thống
ralph-tui info

Best Practices (10 quy tắc)


      graph TB
    subgraph planning ["Chuẩn bị"]
        D1["1. Task nhỏ, rõ ràng"]
        D2["2. Description đủ chi tiết"]
        D3["3. Priority đúng thứ tự"]
    end

    subgraph execution ["Thực thi"]
        S1["4. Commit trước khi chạy"]
        S2["5. Dùng sandbox cho code untrusted"]
        S3["6. Giới hạn iterations khi test"]
    end

    subgraph monitor ["Theo dõi"]
        DE1["7. Dùng dashboard (d key)"]
        DE2["8. Review logs thường xuyên"]
        DE3["9. Pause khi cần review"]
    end

    subgraph scale ["Mở rộng"]
        A1["10. Remote control cho multi-machine"]
    end

    style planning fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style execution fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style monitor fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style scale fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style D1 fill:#00b894,color:#fff,stroke:#55efc4
    style D2 fill:#00b894,color:#fff,stroke:#55efc4
    style D3 fill:#00b894,color:#fff,stroke:#55efc4
    style S1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style S2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style S3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style DE1 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style DE2 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style DE3 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style A1 fill:#e17055,color:#fff,stroke:#fab1a0

    
      Loading

  
Task nhỏ, right-sized – Mỗi task nên hoàn thành được trong 1 agent iteration (~15-30 phút). Task quá lớn → AI mất focus.


Description đủ chi tiết – Agent chỉ biết những gì bạn viết trong description. Thiếu context = kết quả kém.


Priority đúng thứ tự – Ralph chọn task theo priority. Setup tasks phải cao hơn feature tasks.


Commit trước khi chạy – Ralph tạo commits cho mỗi task. Uncommitted changes có thể conflict.


Dùng sandbox cho code untrusted – --sandbox giới hạn quyền truy cập, an toàn hơn.


Giới hạn iterations khi test – --iterations 3 để test pipeline trước khi chạy full.


Dùng dashboard – Nhấn d để xem trạng thái real-time: agent, task, git branch, sandbox.


Review logs thường xuyên – ralph-tui logs cho biết AI đang làm gì, có stuck không.


Pause khi cần review – Nhấn p bất cứ lúc nào. Review code rồi resume.


Remote control cho multi-machine – Thay vì SSH vào từng máy, dùng --listen + remote add.


So sánh với hệ sinh thái


      graph TB
    subgraph ralph_col ["Ralph TUI"]
        RT1["TypeScript/Bun · TUI"]
        RT2["8+ agent plugins"]
        RT3["Remote multi-instance"]
        RT4["Sandbox · Session persistence"]
        RT5["1,900+ stars"]
    end

    subgraph ralph_og ["Ralph gốc (bash)"]
        RO1["Bash loop đơn giản"]
        RO2["Claude Code only"]
        RO3["Circuit breaker cơ bản"]
        RO4["File-based progress"]
        RO5["Upstream cho bmalph"]
    end

    subgraph gastown ["Gas Town"]
        GT1["Go · Multi-agent orchestrator"]
        GT2["20-30 agents song song"]
        GT3["7 vai trò agent"]
        GT4["Beads-backed memory"]
        GT5["Steve Yegge"]
    end

    subgraph claude_tasks ["Claude Code Tasks"]
        CT1["Built-in task list"]
        CT2["Session-level persistence"]
        CT3["Claude Code native"]
        CT4["Lấy cảm hứng từ Beads"]
        CT5["Anthropic official"]
    end

    style ralph_col fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style ralph_og fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style gastown fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style claude_tasks fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style RT1 fill:#00b894,color:#fff,stroke:#55efc4
    style RT2 fill:#00b894,color:#fff,stroke:#55efc4
    style RT3 fill:#00b894,color:#fff,stroke:#55efc4
    style RT4 fill:#00b894,color:#fff,stroke:#55efc4
    style RT5 fill:#00b894,color:#fff,stroke:#55efc4
    style RO1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style RO2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style RO3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style RO4 fill:#0984e3,color:#fff,stroke:#74b9ff
    style RO5 fill:#0984e3,color:#fff,stroke:#74b9ff
    style GT1 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style GT2 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style GT3 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style GT4 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style GT5 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style CT1 fill:#e17055,color:#fff,stroke:#fab1a0
    style CT2 fill:#e17055,color:#fff,stroke:#fab1a0
    style CT3 fill:#e17055,color:#fff,stroke:#fab1a0
    style CT4 fill:#e17055,color:#fff,stroke:#fab1a0
    style CT5 fill:#e17055,color:#fff,stroke:#fab1a0

    
      Loading

  
Tiêu chí
Ralph TUI
Ralph gốc
Gas Town
Claude Tasks


Focus
Orchestration 1 agent/iteration
Simple loop
Multi-agent swarm
Task tracking


Agents
8+ plugins
Claude only
Claude + nhiều
Claude only


Complexity
Trung bình
Thấp
Cao
Thấp


Remote
WebSocket multi-instance
Không
tmux
Không


Setup
bun install -g ralph-tui
Copy bash scripts
Go build
Built-in


Best for
Autonomous task execution
Simple automation
Factory-scale
In-session tracking


Hệ sinh thái liên quan

Ralph TUI là phần trung tâm trong hệ sinh thái agentic coding tools:

  
      graph TD
    RALPH_TUI["Ralph TUI<br/>Orchestrator"]

    BEADS["Beads<br/>Memory System"]
    BMALPH["bmalph<br/>Planning + Execution"]
    RALPH_OG["Ralph (bash)<br/>Original Loop"]
    GASTOWN["Gas Town<br/>Multi-Agent Factory"]

    RALPH_OG -->|"Tiến hóa thành"| RALPH_TUI
    RALPH_OG -->|"Tích hợp vào"| BMALPH
    BEADS -->|"Tracker plugin"| RALPH_TUI
    BEADS -->|"Memory cho"| GASTOWN
    BMALPH -->|"Dùng engine từ"| RALPH_OG

    style RALPH_TUI fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style BEADS fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style BMALPH fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style RALPH_OG fill:#636e72,color:#dfe6e9,stroke:#b2bec3,stroke-width:2px
    style GASTOWN fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px

    
      Loading

  
Công cụ
Vai trò
Link


Ralph TUI
Orchestrate agent loop với TUI
github.com/subsy/ralph-tui


Ralph (gốc)
Bash loop đơn giản, upstream
github.com/snarktank/ralph


Beads
Persistent memory cho agents
github.com/steveyegge/beads


bmalph
BMAD planning + Ralph execution
github.com/LarsCowe/bmalph


Gas Town
Multi-agent factory (20-30 agents)
github.com/steveyegge/gastown


Tài nguyên học tập

Documentation chính thức


Website: ralph-tui.com – Full documentation, guides, examples
Quick Start: ralph-tui.com/docs/getting-started/quick-start
Installation: ralph-tui.com/docs/getting-started/installation
CLI Reference: ralph-tui.com/docs/cli/overview
Configuration: ralph-tui.com/docs/configuration/overview
Themes: ralph-tui.com/docs/configuration/themes
Troubleshooting: ralph-tui.com/docs/troubleshooting/common-issues

Repository


GitHub: github.com/subsy/ralph-tui – Source, issues, contributing
npm: npmjs.com/package/ralph-tui – Package registry
CONTRIBUTING.md – Hướng dẫn đóng góp, test conventions

Guides liên quan (trong Obsidian vault này)


[[Beads-Guide]] – Hướng dẫn Beads (tracker plugin cho Ralph TUI)
[[Bmalph-Guide]] – Hướng dẫn bmalph (BMAD + Ralph pipeline)
[[Claude-Code-Best-Practice-Guide]] – Best practices cho Claude Code (agent chính)


Kết luận

Ralph TUI đại diện cho bước tiến hóa quan trọng trong hệ sinh thái agentic coding: từ bash loop đơn giản → TUI orchestrator hoàn chỉnh với plugin architecture, remote control, sandbox, và session persistence.
Điểm mạnh cốt lõi:

Agent-agnostic: Không lock-in vào 1 AI agent – hỗ trợ 8+ agents qua plugin
Fresh context per iteration: Mỗi task chạy trong agent instance mới, tránh context pollution
Remote multi-instance: Điều khiển nhiều máy từ 1 TUI – lý tưởng cho team hoặc CI/CD
Production-ready: Sandbox, session persistence, audit logging, 1,400+ tests


      graph LR
    P1["Manual prompting"]
    P2["Bash loop (Ralph)"]
    P3["TUI Orchestrator (Ralph TUI)"]
    P4["Multi-agent Factory (Gas Town)"]

    P1 -->|"Tự động hóa"| P2
    P2 -->|"TUI + Plugins"| P3
    P3 -->|"Scale up"| P4

    style P1 fill:#e17055,color:#fff,stroke:#fab1a0
    style P2 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style P3 fill:#00b894,color:#fff,stroke:#55efc4
    style P4 fill:#6c5ce7,color:#fff,stroke:#a29bfe

    
      Loading
Vấn đề	Workflow thủ công	Ralph TUI
Chọn task tiếp theo	Developer tự đọc danh sách, quyết định	Tự động chọn theo priority + dependency
Build prompt	Copy-paste context mỗi lần	Template Handlebars, tự inject context
Execute agent	Mở chat mới, paste instructions	Spawn agent instance tự động (fresh context)
Phát hiện hoàn thành	Developer tự đánh giá "xong chưa?"	Auto-detect completion patterns
Theo dõi tiến độ	Mental tracking hoặc markdown notes	TUI dashboard real-time
Xử lý lỗi	Tự debug, tự quyết định retry	Circuit breaker, auto-recovery
Nhiều máy	SSH vào từng máy	Remote control từ 1 TUI
An toàn	Agent có full access	Sandbox execution (bwrap/sandbox-exec)
Tiêu chí	Ralph TUI	Ralph gốc (bash)	Beads + Gas Town	Claude Code Tasks
Kiểu	TUI orchestrator	Bash loop	Memory + multi-agent	Built-in task list
Agents hỗ trợ	8+ agents	Claude Code only	Mọi agent	Claude Code only
Task tracker	prd.json, Beads	@fix_plan.md	Beads issues	Local tasks
Remote control	WebSocket multi-instance	Không	tmux-based	Không
Session persistence	Crash-safe, resume	Cơ bản	Git-backed	Session-level
Sandbox	bwrap/sandbox-exec	Không	Không	Không
Giao diện	TUI (React-based)	Terminal output	Terminal/TUI	CLI integrated
PRD creation	AI chat mode	Tự viết	CLI tạo issues	Không
Yêu cầu	Chi tiết
Bun	Runtime JavaScript/TypeScript. Cài: `curl -fsSL https://bun.sh/install \| bash`
AI Agent	Ít nhất 1 agent đã cài trong PATH: `claude`, `opencode`, `gemini`, `codex`, `kiro`
Git	Khuyến nghị cho version control
Beads	Tùy chọn – nếu muốn dùng Beads tracker thay vì prd.json
So sánh	prd.json	Beads
Setup	Zero – tạo file JSON	Cần cài `bd` CLI
Dependencies	Mảng ID đơn giản	6 loại dependency có ngữ nghĩa
Multi-agent	Không tối ưu	Hash-based IDs, 3-way merge
Persistence	File trên disk	Git-backed, offline-first
Khi nào dùng	Solo dev, prototype	Team, dự án dài hạn
Phím	Hành động
`T` (Shift+T)	Bật/tắt panel subagent tree
`t`	Chuyển đổi mức độ chi tiết
Feature	Claude Code	OpenCode	Factory Droid
Provider	Anthropic	Multi-provider	Factory
Models	`sonnet`, `opus`, `haiku`	`provider/model` (vd: `openai/gpt-4o`)	Theo danh sách model của Factory
Subagent Tracing	Có (Task tool)	Có (Task tool)	Không
File Context	Có (`--add-dir`)	Có (`--file`)	Không (dùng `--cwd`)
Streaming	Có	Có	Có
Feature	JSON	Beads	Beads-BV
External CLI	None	`bd`	`bd` + `bv`
Dependencies	Có	Có	Có
Priority Ordering	Có	Có	Có + PageRank
Hierarchy (Epics)	Không	Có	Có
Graph Analysis	Không	Không	Có
Git Sync	Không	Có	Có
Flag	Purpose
`--robot-triage`	Get ranked recommendations
`--robot-next`	Get single top pick
`--robot-plan`	Get parallel execution tracks
`--robot-insights`	Get full graph metrics
Phím	Hành động
`s`	Start execution
`p`	Pause / Resume execution
`+` / `=`	Add 10 iterations
`-` / `_`	Remove 10 iterations
`j` / `↓`	Navigate down
`k` / `↑`	Navigate up
`Tab`	Switch focus giữa các panel
`Enter`	Drill into item đang chọn
`Esc`	Go back / đóng dialog
`o`	Cycle right panel views (details → output → prompt)
`O`	Jump thẳng tới prompt preview
`d`	Toggle dashboard (trạng thái, agent, tracker, git, sandbox)
`h`	Toggle show/hide closed tasks
`r`	Refresh task list từ tracker
`T`	Toggle subagent tree panel (Shift+T)
`t`	Cycle mức độ chi tiết subagent
`w`	Toggle workers view (parallel mode)
`m`	Toggle merge progress view (parallel mode)
`l`	Mở epic selector (Beads tracker)
`,`	Mở settings (tab local)
`C`	Mở config viewer read-only (Shift+C)
`q`	Quit
`?`	Hiển thị help
`1-9`	Chuyển tab (remote instances)
`[` / `]`	Tab trước / sau
`a`	Thêm remote mới
`e`	Sửa remote hiện tại
`x`	Xóa remote hiện tại
Nguồn	Scope	Ghi chú
CLI flags	Per-run	Ưu tiên cao nhất (override config file)
`.ralph-tui/config.toml`	Project	Settings riêng cho dự án
`~/.config/ralph-tui/config.toml`	Global	Default cho tất cả dự án