Parallel Configuration

Parallel execution can be configured through the config file, CLI flags, or both. CLI flags take precedence over config file settings.

Config File

Add a [parallel] section to your .ralph-tui/config.toml:

TOML

[parallel]
mode = "never"                          # auto | always | never
maxWorkers = 3                          # Maximum concurrent workers
directMerge = false                     # Merge directly to current branch (vs session branch)

Options

Option	Type	Default	Description
`mode`	string	`"never"`	Execution mode: `auto` analyzes dependencies, `always` forces parallel, `never` disables
`maxWorkers`	number	`3`	Maximum concurrent workers (worktrees)
`directMerge`	boolean	`false`	If true, merge directly to current branch; if false (default), create a session branch
`worktreeDir`	string	`".ralph-tui/worktrees"`	Directory for git worktrees (relative to project root)

Mode Behavior

Mode	Behavior
`auto`	Analyze task dependencies; use parallel when beneficial, fall back to sequential otherwise
`always`	Force parallel execution regardless of dependency analysis (may cause more merge conflicts)
`never`	Disable parallel execution entirely; always run sequentially

CLI Flags

Override configuration with command-line flags:

Bash

# Force sequential execution
ralph-tui run --serial
ralph-tui run --sequential
 
# Force parallel execution (auto worker count)
ralph-tui run --parallel
 
# Force parallel with specific worker count
ralph-tui run --parallel 4
 
# Force one parallel session across multiple epics
ralph-tui run --parallel --epic ui-epic --epic backend-epic
ralph-tui run --parallel --epics ui-epic,backend-epic

Flag Reference

Flag	Description
`--serial`, `--sequential`	Force sequential execution (overrides config)
`--parallel`	Force parallel execution with default worker count
`--parallel N`	Force parallel execution with N workers
`--direct-merge`	Merge directly to current branch instead of creating a session branch
`--epic <id>`	Select an epic. This option can be repeated for multi-epic hierarchy tracker runs.
`--epics <ids>`	Select comma-separated epics for hierarchy tracker runs.

INFO

When both --serial and --parallel are specified, --serial takes precedence.

INFO

Multi-epic selection is currently a runtime option, not a config-file setting. Use repeated --epic or --epics so each session records the exact selected epic set.

Precedence

Configuration is resolved in this order (highest priority first):

CLI flags — --serial or --parallel N
Config file — [parallel] section in .ralph-tui/config.toml
Built-in default — mode = "never" (sequential execution)

Examples

Minimal Config

No parallel config means sequential-by-default execution:

Bash

# Just run (sequential by default)
ralph-tui run

To enable automatic parallel detection:

TOML

[parallel]
mode = "auto"

High-Parallelism Setup

For large projects with many independent tasks:

TOML

[parallel]
mode = "always"
maxWorkers = 6

CI/Headless Mode

For CI pipelines where you want deterministic behavior:

Bash

# Force sequential for reproducible builds
ralph-tui run --serial --headless
 
# Or force parallel with fixed worker count
ralph-tui run --parallel 2 --headless

Conservative Mode

If you want to opt in to parallel execution only via CLI:

TOML

[parallel]
mode = "never"    # Disable auto-detection

Bash

# Override config to run parallel when you choose
ralph-tui run --parallel 3

Multi-Epic Hierarchy Tracker Run

For Beads-style hierarchy trackers, select more than one epic at runtime:

Bash

ralph-tui run --tracker beads-rust --parallel 4 \
  --epic ui-epic \
  --epic backend-epic

Ralph preserves the first ID as epicId for compatibility and stores the full selected set as epicIds in session state. Worker count remains global across all selected epics.

Smart Parallelism Heuristics

Ralph TUI automatically adjusts the recommended worker count based on task characteristics. This helps prevent merge conflicts when tasks are likely to touch overlapping files.

How It Works

The heuristic analyzes:

Task titles and labels — Looking for keywords like "test", "refactor", etc.
File overlap — Using the affects metadata field if available

Heuristic Rules

Pattern	Effect	Reasoning
`>50%` test tasks	Full parallelism	Test files rarely conflict with each other
`>50%` refactor tasks	Reduce to 2 workers	Refactoring often touches many files
High file overlap	Reduce parallelism	Overlapping files cause merge conflicts

Example

If your task list contains:

1. Write unit tests for UserService
2. Add tests for AuthController
3. Test coverage for OrderProcessor
4. Add integration tests for PaymentService

The heuristic detects >50% test-related tasks and recommends full parallelism since test files typically don't conflict.

Conversely, if your tasks are:

1. Refactor database layer
2. Refactor API endpoints
3. Refactor auth middleware

The heuristic reduces parallelism to 2 workers to minimize merge conflicts.

Overriding Heuristics

You can always override the recommendation with explicit flags:

Bash

# Force specific worker count regardless of heuristics
ralph-tui run --parallel 6
 
# Or disable parallel entirely
ralph-tui run --serial