Skip to Content
WorkflowsRun a Workflow

Run a Workflow

WorktreeWise executes multi-step command sequences across any combination of Git worktrees. Run build and deployment routines in sequential series or execute concurrent test suites in parallel with live ANSI color streaming and process management.

Execution Modes

Before starting a run, configure how WorktreeWise schedules commands across target worktrees:

ModeScheduling BehaviorIdeal Use Cases
Sequential ExecutionExecutes all commands on one worktree at a time in series. WorktreeWise completes all steps on Worktree A before starting on Worktree B. If any command fails (non-zero exit code), execution stops immediately for that worktree.Resource-intensive compilation, shared database migrations, integration tests binding to shared local ports.
Parallel ExecutionConcurrently launches tasks across all selected worktrees simultaneously via asynchronous worker threads (Promise.all). Each worktree runs its commands independently.Unit test suites, linting, formatting checks, typechecking, running parallel builds across multiple feature branches.

How to Run a Workflow

Select Target Worktrees

In the Workflows table, locate the target workflow. Use the Worktrees dropdown to specify target worktrees:

  • Select individual worktrees (e.g. your active feature branches).
  • If left empty, WorktreeWise automatically runs the workflow across all active worktrees in the repository.

Choose Sequential or Parallel Mode

Toggle the execution mode selector to either Sequential or Parallel based on your concurrency and resource requirements.

Start the Workflow

Select the green Play (▶) button on the workflow row.

Monitor Live Process Output

As execution begins:

  • A live progress drawer displays real-time step cards for each participating worktree.
  • Logs stream into the execution viewer with ANSI color codes and formatted progress spinners.
  • Press Shift + F to expand the log panel to full screen; press Esc to restore standard view.

Underlying Engine & Process Architecture

WorktreeWise executes workflow commands inside dedicated pseudo-terminals (PTY) via node-pty:

Pseudo-Terminal Semantics

Each command runs inside a real pseudo-terminal with xterm-256color and COLORTERM=truecolor support. Colors, spinners, and interactive progress bars from package managers (npm, pnpm, cargo) render identically to native consoles.

Shell Resolution

Commands execute using your configured shell preference (PowerShell, Git Bash, WSL, Bash, Zsh, Fish, or Nushell) as specified in Settings → Shell.

Environment Sanitization

WorktreeWise cleanses the process environment before spawning workers, stripping internal Electron runtime variables (ELECTRON_RUN_AS_NODE, ELECTRON_NO_ASAR, NODE_OPTIONS, TS_NODE_*). This prevents interference with your local Node.js runtime and build scripts.

Bounded Memory Buffer

To prevent Electron memory leaks during long-running builds or continuous log streams, WorktreeWise enforces a safety buffer limit of 250,000 characters per command output (MAX_WORKFLOW_COMMAND_OUTPUT_CHARS). If logs exceed this threshold, the buffer is trimmed from the start and prepended with:

[Earlier output omitted to limit memory usage]

Interactive Prompt Interception

Commands that trigger unexpected interactive prompts (such as generator overwrite prompts Overwrite?) are automatically intercepted to prevent background terminal hangs.

Step Status Indicators

Each step in an active workflow reflects its real-time process state:

Status TagIndicatorDescription
ProcessingBlue SpinnerCommand is actively executing inside its PTY process.
SuccessGreen CheckmarkProcess completed successfully with an exit code of 0.
ErrorRed ExclamationProcess exited with a non-zero exit code. Subsequent steps on this worktree are halted.
WarningYellow AlertExecution was aborted or cancelled by the user.

Stopping Workflows

To cancel a running workflow:

  1. Select the red Stop (⏹) button in the Workflows header.
  2. Or press the Esc key.

WorktreeWise calls stopActiveWorkflowProcesses(), safely terminating all active child PTY sessions and their process groups across participating worktrees without leaving orphaned background processes.

Worktree Path Validation: Before launching any workflow, WorktreeWise validates that every selected worktree path exists on disk. If a worktree was removed or moved outside WorktreeWise, the run is intercepted with a safety notice: "Some selected worktrees have been deleted: <name>. Please update your selection."

Create a WorkflowEdit & Duplicate