Skip to Content
WorkflowsPlay a Workflow

Play a Workflow

WorktreeWise allows you to execute defined multi-step command sequences across any combination of Git worktrees. Whether you need to install dependencies and run migrations sequentially across feature branches, or run test suites simultaneously in parallel, WorktreeWise handles process management, output streaming, and error handling seamlessly.

Execution Modes

Before starting a workflow, you can choose how WorktreeWise schedules tasks across your selected worktrees:

Execution ModeBehaviorIdeal Use Cases
Sequential ExecutionProcesses worktrees one at a time in series. WorktreeWise executes all defined commands from start to finish on Worktree A before beginning execution on Worktree B. If any command encounters a failure (non-zero exit code), execution for that worktree is immediately halted.Ideal for resource-intensive compilation tasks, shared database migrations, integration tests requiring local ports, or operations where order of completion matters.
Parallel ExecutionConcurrently launches tasks across all selected worktrees simultaneously via asynchronous worker threads (Promise.all). Each worktree runs its commands independently.Ideal for fast unit test runs, linting, code formatting, running parallel builds, or verifying bug fixes across multiple versions at once.

How to Play a Workflow

Select Target Worktrees

In the Workflows table, locate the target workflow. Use the Worktrees multi-select dropdown column to specify which worktrees should participate in the run:

  • Target a single specific worktree (e.g., your active feature worktree).
  • Target multiple selected worktrees.
  • 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 depending on your concurrency requirements.

Start the Workflow

Click the green Play button on the workflow row.

  • Shortcut: You can also trigger the active workflow run with keyboard shortcuts configured in the workspace.

Monitor Live Process Output

As soon as execution begins:

  • A live progress drawer opens displaying real-time step cards for each worktree.
  • Output streams directly into the log viewer with full ANSI color syntax highlighting.

Underlying Engine & Architecture

WorktreeWise does not execute simple shell strings through basic background subprocesses; it runs each workflow command inside a dedicated pseudo-terminal (PTY) via node-pty:

Full Terminal Semantics

Each command runs inside a genuine pseudo-terminal session with xterm-256color and COLORTERM=truecolor support. ANSI color codes, spinners, and interactive progress bars from tools like npm, cargo, vite, and jest render identically to a standard terminal.

Shell Resolution

Commands execute inside your configured shell preference (e.g., PowerShell, Git Bash, WSL, Bash, Zsh, Fish, or Nushell) as configured in Settings.

Environment Isolation

WorktreeWise sanitizes the execution environment before spawning workflow processes, actively stripping internal Electron runtime variables (ELECTRON_RUN_AS_NODE, ELECTRON_NO_ASAR, NODE_OPTIONS, TS_NODE_*). This prevents interference with your local Node.js tooling and build scripts.

Bounded Memory Buffer

To prevent Electron memory leaks during long-running builds or continuous log generators, 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]

Prompt & Hang Protection

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

Step Status & Error Handling

Each step in a running workflow reflects real-time execution state:

Status TagIndicatorDescription
ProcessingBlue SpinnerThe command is actively executing inside its PTY process.
SuccessGreen CheckmarkThe process completed successfully with an exit code of 0.
ErrorRed ExclamationThe process exited with a non-zero exit code or encountered an execution failure. Subsequent commands on this worktree are skipped.
WarningYellow AlertExecution was aborted or stopped early by the user.

Stopping Workflows

If you need to cancel a running workflow:

  1. Click the red Stop button in the Workflows interface.
  2. Alternatively, press the Esc key.

WorktreeWise immediately calls stopActiveWorkflowProcesses(), safely killing all active child PTY sessions and their process groups across every target worktree. Stopped tasks transition cleanly to the warning state without leaving orphaned background processes consuming CPU or locking files.

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

Import a WorkflowSettings