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

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

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.

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