resume | Ralph TUI

Synopsis

Bash

ralph-tui resume [session-id] [options]

The resume command continues execution from a previously interrupted session. Ralph loads the saved session state and picks up where it left off, automatically resetting any stale "in_progress" tasks.

INFO

Session state is automatically saved to .ralph-tui/session.json. You can resume even after crashes or forced exits.

Arguments

Argument	Description
`session-id`	(Optional) Session ID to resume. First 8 characters are usually enough. If not provided, resumes session in current directory.

Options

Option	Description
`--list`, `-l`	List all resumable sessions across all directories
`--cleanup`	Remove stale entries from the session registry
`--cwd <path>`	Working directory (where to find the session file)
`--headless`	Run without TUI
`--force`	Override stale lock (use if another instance crashed)

Session Registry

Ralph maintains a global registry of sessions at ~/.config/ralph-tui/sessions.json. This allows you to:

Resume from any directory - No need to cd into the project first
List all active sessions - See what's running across all projects
Resume by session ID - Use the first 8 characters of the session ID

INFO

The session registry is automatically updated when you start, pause, or complete sessions. Use --cleanup to remove entries for sessions that no longer exist.

Examples

Basic Resume

Bash

# Resume from current directory
ralph-tui resume
 
# Resume headless for CI pipelines
ralph-tui resume --headless

List Available Sessions

Bash

# See all resumable sessions
ralph-tui resume --list

Output example:

Resumable sessions:

   ID        Status       Agent       Tracker
   ─────────────────────────────────────────────────
1. ⏸ a1b2c3d4  paused       claude      prd:./tasks/prd.json
   /home/user/my-project

2. ⚠ e5f6g7h8  interrupted  codex       epic:EPIC-123
   /home/user/another-project

3. ⏸ j9k0l1m2  paused       claude      epics:UI,Backend
   /home/user/multi-epic-project

Resume by Session ID

Bash

# Resume a specific session (from any directory)
ralph-tui resume a1b2c3d4
 
# The full session ID also works
ralph-tui resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

Resume from Different Directory

Bash

# Resume a session in another project (traditional method)
ralph-tui resume --cwd /path/to/project

Clean Up Stale Registry Entries

Bash

# Remove registry entries for sessions that no longer exist
ralph-tui resume --cleanup

Force Override Stale Lock

Bash

# Override if previous instance crashed
ralph-tui resume --force

INFO

Only use --force when you're certain no other Ralph instance is running. Using it while another instance is active can cause conflicts.

What Gets Restored

When you resume a session, Ralph restores:

Iteration number - Continues counting from where you left off
Task statuses - Completed tasks remain completed
Progress file - Cross-iteration context is preserved
Configuration - Uses the same config as the original run
Epic selection - Multi-epic sessions restore the same epicIds and execution scopes

Handling Stale Tasks

If Ralph was interrupted while a task was "in_progress", resume automatically:

Detects tasks stuck in "in_progress" state
Resets them to "open" status
Re-selects the next task based on priority

This ensures no tasks are permanently stuck due to crashes.

Multi-Epic Resume

When a multi-epic hierarchy tracker session is resumed, Ralph reconstructs the same scoped tracker wrapper from the saved epicIds and execution scopes. The resumed session continues to use one scheduler, one session branch, and one merge queue across the original selected epic set.

Existing sessions that only have a single epicId continue to load as single-epic sessions.

Session States

Sessions can be in one of these states:

State	Icon	Resumable	Description
`running`	▶	Yes	Session is (or was) actively running
`paused`	⏸	Yes	Session was manually paused
`interrupted`	⚠	Yes	Session was stopped via Ctrl+C or signal
`completed`	✓	No	All tasks finished successfully
`failed`	✗	No	Session encountered a fatal error

Session Lock

Ralph uses a lock mechanism to prevent multiple instances:

The session file includes a lock timestamp
If the lock is stale (older than a threshold), resume can proceed
Use --force to override the lock if needed

Example Workflow

Start Execution

Bash

ralph-tui run --prd ./prd.json

Ralph begins processing tasks.

Interrupt

Press q to quit, or the process gets interrupted. Session state is saved automatically.

Check Sessions (Optional)

Bash

ralph-tui resume --list

View all available sessions.

Resume Later

Bash

# From the same directory
ralph-tui resume
 
# Or from anywhere using session ID
ralph-tui resume a1b2c3d4

Ralph continues from where it left off.

Troubleshooting

"Session lock exists"

Another Ralph instance may be running, or a previous instance crashed:

Bash

# Check if another instance is running
ps aux | grep ralph-tui
 
# If not, force resume
ralph-tui resume --force

"No session found"

No .ralph-tui/session.json file exists in the working directory:

Bash

# Check if there are sessions in other directories
ralph-tui resume --list
 
# If session exists elsewhere, resume by ID
ralph-tui resume <session-id>
 
# Or start a new session
ralph-tui run --prd ./prd.json

"Multiple sessions match prefix"

Your session ID prefix matches multiple sessions:

Bash

# Use a longer prefix to be more specific
ralph-tui resume a1b2c3d4e5
 
# Or use --list to see all session IDs
ralph-tui resume --list

"Session not found in registry"

The session may have been started before the registry feature was added:

Bash

# Resume using --cwd instead
ralph-tui resume --cwd /path/to/project
 
# Or clean up stale entries
ralph-tui resume --cleanup

"Task stuck in_progress"

Resume handles this automatically, but you can also manually reset:

Bash

# For beads tracker
bd update TASK-ID --status open
 
# For JSON tracker, edit prd.json directly

run - Start a new execution session
status - Check session status without resuming
logs - View iteration history