Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ralph

ralph wraps claude -p with rich terminal rendering. Bare ralph opens one persistent chat whose memory is a compressed tree of summaries. From that chat, Claude can start background workers in their own git worktrees and watch long-running commands. ralph ask sends one prompt and stores nothing.

Features

  • Persistent chat - Bare ralph runs ralph chat. One Claude process serves the chat, started with a compressed view of the chat so far, stored under ~/.ralph/chat.
  • Compressed memory - The chat log is summarized into a tree by a background nap pass. Claude opens details with the zoom and recall tools.
  • Background workers - Claude starts, messages, and closes workers with spawn_worker, reply, and close_worker. Harnesses: claude in tmux, cursor, and opencode. Each worker gets its own git worktree. These tools come from ralph chat-mcp, which talks to the running chat over a Unix socket.
  • Inbox and watches - Worker reports and finished watch commands land in the chat inbox. Read them with /inbox.
  • Status line - Shows the chat mode (NAP, INBOX, WORK, IDLE); colors are set under [theme.status].
  • Chat input - Multi-line editor with history, $EDITOR drafts, clipboard images, ! shell cells, skills, and an opt-in vi mode ([chat] edit_mode = "vi").
  • Single-shot ask - ralph ask sends one prompt from an argument or stdin and stores nothing.
  • Rich terminal output - Syntax highlighting for code, diffs, and tool results, with built-in themes or custom .tmTheme files (ralph themes).

Installation

git clone https://github.com/cloudbridgeuy/ralph.git
cd ralph
cargo install --path crates/ralph --root ~/.local --force  # Install to ~/.local/bin
cargo install --path crates/ralph --root /usr/local --force  # Custom prefix (binary in /usr/local/bin)

Requirements

  • Rust 1.95.0 or later
  • Claude Code (claude on PATH)
  • git, for worker worktrees
  • Per worker harness: tmux for claude workers, the Cursor agent CLI for cursor workers, opencode for opencode workers

Quick Start

  1. Chat:
ralph
  1. Ask a single-shot question:
ralph ask 'Explain this codebase'
  1. List syntax highlighting themes:
ralph themes