dmux-workflows

Here's a `dmux` command that does what you want:

```bash
dmux --layout tiled \
     --title fetch_data.py --on-exit-error kill-session -- python fetch_data.py \
     --title process_data.py --on-exit-error kill-session -- python process_data.py \
     --title visualize.py --on-exit-error kill-session -- python visualize.py
```

**Explanation of each option:**

- `--layout tiled` — splits the window into three equal panes (one per command) instead of the default single pane.
- `--title <name>` — sets the pane label to the given string, so each pane is visibly named after its script (`fetch_data.py`, `process_data.py`, `visualize.py`).
- `--on-exit-error kill-session` — instructs dmux to terminate the entire session (all panes) if that pane's command exits with a nonzero status. Applied per-command, so a failure in *any* of the three scripts tears down the whole session.
- `--` — separates dmux's own options from the command to run in the pane, so arguments meant for Python aren't parsed by dmux.

**Note:** If your dmux version doesn't support `--on-exit-error`, the equivalent is often `--abort-on-error` or wrapping each command as `python fetch_data.py || dmux kill-session` — check `dmux --help` for the exact flag name in your build.

dmux is a tmux-based pane manager, so the cleanest way to do this is with a tmux command (which dmux sessions sit on top of). Here's the exact command:

```bash
tmux new-session -d -s pipeline 'python fetch_data.py; [ $? -ne 0 ] && tmux kill-session -t pipeline' \
  \; select-pane -T fetch_data.py \
  \; split-window -h -t pipeline 'python process_data.py; [ $? -ne 0 ] && tmux kill-session -t pipeline' \
  \; select-pane -T process_data.py \
  \; split-window -v -t pipeline 'python visualize.py; [ $? -ne 0 ] && tmux kill-session -t pipeline' \
  \; select-pane -T visualize.py \
  \; set-option -t pipeline status on \
  \; attach -t pipeline
```

**Explanation of each option:**

- `tmux new-session -d -s pipeline '<cmd>'` — creates a detached session named `pipeline` and runs the first script (`fetch_data.py`) in its initial pane.
- `; [ $? -ne 0 ] && tmux kill-session -t pipeline` — appended to each script's command: if the script exits with a non-zero (error) status, the entire `pipeline` session is killed, tearing down all three panes at once.
- `split-window -h -t pipeline '<cmd>'` — splits the window horizontally to create a second pane running `process_data.py` (with the same error guard).
- `split-window -v -t pipeline '<cmd>'` — splits again vertically for `visualize.py`.
- `select-pane -T <name>` — sets the pane's title/label to the script name (visible in the status line / pane border if you enable pane titles).
- `attach -t pipeline` — attaches you to the session so you can watch all three panes run simultaneously.

**Notes:**

- All three scripts start at the same time — tmux launches each pane's command immediately, so this is true parallel execution, not sequential.
- If your scripts have dependencies (e.g., `visualize.py` needs output from `process_data.py`), parallelism will break them — in that case chain them sequentially in one pane instead: `python fetch_data.py && python process_data.py && python visualize.py`.
- If you're already inside a dmux session, you can press `n` to spawn panes and type each command (`python fetch_data.py` etc.) — but the CLI above is the way to get the automatic kill-on-error behavior.

# Coordinating Two Agents with dmux

## Overview

- **Agent A (test-writer)**: writes unit tests for `calculateTax(income)` → outputs `calculateTax.test.js`
- **Agent B (implementer)**: implements `calculateTax` based on the tests → outputs `calculateTax.js`
- **Phase 3**: both run in parallel to verify the implementation passes the tests

## Step 0 — Setup workspace

```bash
mkdir -p tax-project && cd tax-project
git init 2>/dev/null || true
```

## Step 1 — Run the test-writer agent (sequential, must finish first)

```bash
# Start a dmux pane dedicated to the test-writer
dmux new --name test-writer

# Send the task to that pane and wait for it to finish
dmux send test-writer "Write comprehensive Jest unit tests for a function calculateTax(income). Save the file as calculateTax.test.js in the current directory. Cover: income <= 0, low bracket, mid bracket, high bracket, non-numeric input, negative income. Do NOT implement calculateTax itself."

# Block until the agent's pane goes idle / exits
dmux wait test-writer
```

## Step 2 — Capture the test-writer's output

```bash
# Capture the pane's transcript (for provenance / debugging)
dmux capture test-writer --file test-writer-transcript.log

# Verify the test file actually exists before proceeding
test -f calculateTax.test.js || { echo "test-writer failed to produce tests"; exit 1; }
```

## Step 3 — Feed the tests to the implementation agent

```bash
dmux new --name implementer

# Send the test file contents as the agent's input spec
dmux send implementer "Implement calculateTax(income) in calculateTax.js so that ALL tests in the following file pass. Export the function. Here are the tests:

$(cat calculateTax.test.js)"

dmux wait implementer
dmux capture implementer --file implementer-transcript.log
test -f calculateTax.js || { echo "implementer failed"; exit 1; }
```

## Step 4 — Run both agents in parallel to verify

```bash
# Reviewer agent: run the tests and report pass/fail
dmux new --name reviewer
dmux send reviewer "Run 'npx jest calculateTax.test.js' in the current directory. If any test fails, report the failure and suggest a fix to calculateTax.js. If all pass, confirm verification."

# Reviewer runs while the implementer stays live for potential fixes
dmux wait reviewer
dmux capture reviewer --file reviewer-transcript.log
```

If the reviewer reports failures, loop back:

```bash
dmux send implementer "The reviewer reported: $(dmux capture reviewer --stdout). Fix calculateTax.js accordingly."
dmux wait implementer
dmux send reviewer "Re-run the tests and confirm."
dmux wait reviewer
```

## Step 5 — Teardown

```bash
dmux kill test-writer
dmux kill implementer
dmux kill reviewer
```

## Key sequencing guarantees

1. `dmux wait <name>` after each `dmux send` ensures strict ordering in Steps 1–3 (tests exist before implementation starts).
2. Step 4 deliberately omits waiting between launching reviewer and keeping implementer alive — they operate concurrently, with the reviewer's captured output fed back to the implementer only if needed.
3. File-existence checks (`test -f ...`) act as gates so a failed agent run never silently propagates to the next stage.

# dmux Workflow: Test-Writer → Implementer → Parallel Verification

## Overview

```
Step 1: Pane A (test-writer) runs alone → writes tests to tests/calculateTax.test.js
Step 2: Capture Pane A's output/spec to a handoff file
Step 3: Pane B (implementer) receives the handoff → writes src/calculateTax.js
Step 4: Both panes run in parallel to verify (test-runner + fixer)
```

## Step 0 — Setup

```bash
mkdir -p src tests /tmp/dmux-handoff
git init   # optional but recommended for isolation
dmux       # start the dmux session
```

## Step 1 — Run the test-writer agent first (Pane A)

Inside dmux, press `n` to create a pane and launch the agent with a prompt that forces file output:

```bash
# Pane A (Claude Code example):
claude "Write comprehensive unit tests for a function calculateTax(income) in
src/calculateTax.js. Use Jest. Cover: 0 income, negative income, income below
the tax-free threshold, progressive brackets, very large incomes, and
non-numeric input. Write the tests to tests/calculateTax.test.js and a short
behavioral spec of what the function should do to
/tmp/dmux-handoff/tax-spec.md. Do NOT implement the function."
```

Wait for Pane A to finish (check with `m` to merge/read its output).

## Step 2 — Capture the test-writer's output

```bash
# Capture the pane's transcript (tmux underneath dmux)
tmux capture-pane -t dmux:0.0 -p -S - > /tmp/dmux-handoff/paneA-output.txt

# The agent also wrote the spec file; verify both artifacts exist
ls -l /tmp/dmux-handoff/tax-spec.md tests/calculateTax.test.js
```

## Step 3 — Feed output to the implementation agent (Pane B)

Press `n` for a second pane and pass the captured artifacts as input:

```bash
# Pane B:
claude "Read /tmp/dmux-handoff/tax-spec.md and
/tmp/dmux-handoff/paneA-output.txt. Implement calculateTax(income) in
src/calculateTax.js so that every test in tests/calculateTax.test.js passes.
Do NOT modify the tests. Run 'npx jest tests/calculateTax.test.js' and
iterate until all tests pass."
```

## Step 4 — Run both agents in parallel to verify

Create two panes (`n` twice):

```bash
# Pane C (test-runner / watcher):
npx jest --watch --notify
# or as an agent:
claude "Run 'npx jest tests/calculateTax.test.js'. If any test fails,
write a summary of the exact failures to /tmp/dmux-handoff/failures.md."

# Pane D (fixer):
claude "Watch /tmp/dmux-handoff/failures.md. If it appears with content,
fix src/calculateTax.js until all tests pass. Never edit the tests."
```

## Full scripted version (non-interactive)

```bash
#!/usr/bin/env bash
set -euo pipefail

mkdir -p src tests /tmp/dmux-handoff

# Step 1: test-writer (blocking, headless)
claude -p "Write Jest unit tests for calculateTax(income) to
tests/calculateTax.test.js and a behavioral spec to
/tmp/dmux-handoff/tax-spec.md. Do not implement the function." \
  > /tmp/dmux-handoff/paneA-output.txt

# Step 2: artifacts already captured; sanity check
test -s tests/calculateTax.test.js && test -s /tmp/dmux-handoff/tax-spec.md

# Step 3: implementer, fed the captured output
claude -p "Read /tmp/dmux-handoff/tax-spec.md and
/tmp/dmux-handoff/paneA-output.txt. Implement src/calculateTax.js so all
tests in tests/calculateTax.test.js pass. Do not modify the tests." \
  > /tmp/dmux-handoff/paneB-output.txt

# Step 4: parallel verification via dmux panes
dmux &
sleep 2
tmux send-keys -t dmux:0.0  "npx jest --watch" Enter
tmux split-window -t dmux:0
tmux send-keys -t dmux:0.1  "claude 'Fix src/calculateTax.js if tests fail; never edit tests'" Enter
```

## Notes

- **Handoff via files, not prompts:** writing the spec/tests to disk (`/tmp/dmux-handoff/`) is more reliable than pasting pane output, but `tmux capture-pane` gives you the full agent transcript as a fallback.
- **Isolation:** if both agents might touch the same files, use `git worktree add ../tax-impl` and run the implementer there, then merge.
- **Merge results:** press `m` in dmux to pull each pane's final output back into your main session for review before committing.

Here's a complete `dmux` session script for your project:

## `dmux.session.sh`

```bash
#!/usr/bin/env bash
# dmux session: backend + frontend + docker deployment
set -euo pipefail

SESSION="devstack"

# Start a new dmux session (detached)
dmux new-session -d -s "$SESSION" -n "dev"

# ── Pane 1: Backend API (Node.js, live reload via nodemon) ──
dmux select-pane -t "$SESSION:0.0"
dmux rename-pane -t "$SESSION:0.0" "🔧 backend"
dmux send-keys -t "$SESSION:0.0" "cd backend && nodemon --watch src src/index.js" Enter

# ── Pane 2: Frontend UI (React dev server) ──
dmux split-window -h -t "$SESSION:0.0"
dmux rename-pane -t "$SESSION:0.1" "⚛️ frontend"
dmux send-keys -t "$SESSION:0.1" "cd frontend && npm run dev" Enter

# ── Pane 3: Docker deployment ──
dmux split-window -v -t "$SESSION:0.1"
dmux rename-pane -t "$SESSION:0.2" "🐳 docker"
dmux send-keys -t "$SESSION:0.2" "docker compose up" Enter

# ── Auto-focus: watch backend pane logs for "Server listening" ──
(
  # Capture the backend pane's output stream and scan each line
  dmux pipe-pane -o -t "$SESSION:0.0" 'cat >> /tmp/backend.log'
  tail -f /tmp/backend.log | while read -r line; do
    if [[ "$line" == *"Server listening"* ]]; then
      dmux select-pane -t "$SESSION:0.0"   # focus the backend pane
      dmux set-option -t "$SESSION" -w remain-on-exit off
      break
    fi
  done
) &

# Attach the user to the session
dmux attach -t "$SESSION"
```

## How the focus-switch works

1. **`pipe-pane`** mirrors everything printed in the backend pane into `/tmp/backend.log`. The `-o` flag ensures output is captured only once (not duplicated on repeated pipe calls).
2. **`tail -f`** streams the log file line-by-line in a background subshell, so the watcher runs concurrently with the three dev processes and doesn't block anything.
3. **Pattern match**: each streamed line is checked for the substring `Server listening` — the phrase your Node server presumably prints once it's ready.
4. **`dmux select-pane -t "$SESSION:0.0"`** programmatically moves focus to the backend pane the moment the match fires. Because the watcher runs in the background, this happens automatically without any user interaction — you could be typing in the frontend pane and get yanked to the backend as soon as the API is up.
5. The watcher exits after the first match (`break`), so it's a one-shot trigger, not a repeated interruption. If you want it to re-trigger on every restart (e.g., nodemon reloads), remove the `break` and add a debounce (e.g., `sleep 5` after each match).

**Tips:**
- Make the script executable: `chmod +x dmux.session.sh`
- If your server logs a different readiness phrase, just change the match string.
- To avoid stale logs between runs, add `rm -f /tmp/backend.log` before `pipe-pane`.

Here's a complete dmux session script for your three-component web app:

## `dev-session.sh`

```bash
#!/usr/bin/env bash
# dev-session.sh — dmux session for backend + frontend + docker deployment
set -euo pipefail

BACKEND_DIR="./backend"
FRONTEND_DIR="./frontend"
LOG_PHRASE="Server listening"

# --- 1. Start dmux session ---------------------------------------------------
dmux start --session webapp-dev

# --- 2. Backend pane (live reload) -------------------------------------------
dmux new-pane \
  --session webapp-dev \
  --title "🔧 Backend API" \
  --cwd "$BACKEND_DIR" \
  --command "npm run dev"          # nodemon / ts-node-dev live reload

# --- 3. Frontend pane (React dev server) --------------------------------------
dmux new-pane \
  --session webapp-dev \
  --title "⚛️ React UI" \
  --cwd "$FRONTEND_DIR" \
  --command "npm start"           # Vite: "npm run dev"

# --- 4. Docker deployment pane -------------------------------------------------
dmux new-pane \
  --session webapp-dev \
  --title "🐳 Docker Deploy" \
  --cwd "." \
  --command "docker compose up"

# --- 5. Auto-focus on backend when it's ready ----------------------------------
echo "Waiting for backend to report '$LOG_PHRASE'..."

while true; do
  # Capture the visible + scrollback content of the backend pane
  if dmux capture-pane \
       --session webapp-dev \
       --title "🔧 Backend API" \
       --scrollback 200 | grep -q "$LOG_PHRASE"; then
    dmux focus-pane \
      --session webapp-dev \
      --title "🔧 Backend API"
    echo "✅ Backend is up — focused backend pane."
    break
  fi
  sleep 1
done

echo "All three services launched. Attach with: dmux attach webapp-dev"
```

Make it executable and run:

```bash
chmod +x dev-session.sh
./dev-session.sh
```

## How the focus-switch works

1. **Pane creation with titles** — Each `dmux new-pane` call spawns a pane running its command (`npm run dev`, `npm start`, `docker compose up`) and tags it with a unique `--title`. Titles are the stable handle used later to address panes, so you don't need to track pane IDs.

2. **Polling loop** — The script enters a `while true` loop that runs every second. Each iteration calls `dmux capture-pane`, which dumps the pane's visible content plus up to 200 lines of scrollback into stdout.

3. **Log matching** — `grep -q "$LOG_PHRASE"` checks whether the backend's output contains `Server listening`. This is the signal that nodemon has finished booting the API (adjust the phrase to match your server's actual startup log, e.g. `Listening on port`).

4. **Conditional focus** — The moment the phrase appears, `dmux focus-pane --title "🔧 Backend API"` moves keyboard focus to the backend pane and the loop breaks. If the backend fails to start, the loop simply keeps polling — you can add a timeout (`for i in {1..60}`) if you'd rather give up after 60 seconds.

The net effect: you run one script, all three services start in parallel in titled panes, and your terminal lands on the backend pane exactly when the API is ready to accept requests.

Below is a complete dmux workflow for your four-stage pipeline. It launches all four stages as parallel dmux panes, each wrapped in a small shell script that tees stdout to a log file and records the exit code, then a fifth "collector" pane waits for all panes to finish and prints the summary table.

## 1. Shell wrapper (used by every stage)

Save as `run_stage.sh`:

```bash
#!/usr/bin/env bash
# usage: run_stage.sh <stage_name> <logfile> <command...>
set -u
STAGE="$1"; LOG="$2"; shift 2
"$@" > >(tee "$LOG") 2> >(tee -a "$LOG" >&2)
echo "$STAGE $?" >> ./.stage_exit_codes
```

```bash
chmod +x run_stage.sh
rm -f ./.stage_exit_codes   # clean state before each run
```

## 2. Launch the four stages in parallel with dmux

```bash
dmux new-session -s pipeline

dmux split-window -t pipeline -h \
  './run_stage.sh Extraction extract.log python3 extract.py'

dmux split-window -t pipeline -h \
  './run_stage.sh Validation validate.log ./validate'          # Rust binary

dmux split-window -t pipeline -v \
  './run_stage.sh Transformation transform.log psql -f transform.sql'

dmux split-window -t pipeline -v \
  './run_stage.sh Loading load.log bash load.sh'
```

(If you prefer a single command, the same four stages can be launched with `dmux run-pane` calls issued back-to-back — dmux starts them concurrently since they are independent.)

## 3. Collector pane: wait for all panes, then print the summary

```bash
dmux split-window -t pipeline \
  'while dmux list-panes -t pipeline -F "#{pane_dead}" | grep -qv 1; do sleep 1; done; ./summarize.sh'
```

`summarize.sh`:

```bash
#!/usr/bin/env bash
printf 'Stage | Exit Code\n------|----------\n'
while read -r stage code; do
  printf '%s | %s\n' "$stage" "$code"
done < ./.stage_exit_codes
```

```bash
chmod +x summarize.sh
```

## 4. Example output

```
Stage | Exit Code
------|----------
Extraction | 0
Validation | 1
Transformation | 0
Loading | 0
```

## Notes

- Each stage's stdout is captured via `tee` into `extract.log`, `validate.log`, `transform.log`, and `load.log`; stderr is appended to the same log (drop the `2>` redirect if you want stdout only).
- Exit codes are appended to `.stage_exit_codes` as `StageName code` pairs, so the summary reflects the real exit status of each stage (e.g., Validation failing with 1).
- The collector polls `dmux list-panes` for pane death; alternatively, if your dmux version supports `wait-for`/`sync` channels, replace the polling loop with `dmux wait-for all-stages` and have each wrapper signal `dmux signal done-<stage>` on completion.
- To fail the whole pipeline when any stage fails, add at the end of `summarize.sh`:

```bash
grep -q ' 0$' <(awk 'NR>2' <<<"$(cat ./.stage_exit_codes)") || exit 1
```

## dmux Parallel Pipeline Workflow

### 1. Shell wrapper (captures exit code + logs stdout)

Create `run_stage.sh`:

```bash
#!/usr/bin/env bash
# Usage: ./run_stage.sh <StageName> <LogFile> <StatusFile> -- <command...>
set -o pipefail
STAGE="$1"; LOG="$2"; STATUS="$3"; shift 3; shift   # skip "--"
"$@" > "$LOG" 2>&1
echo "$?" > "$STATUS"
```

```bash
chmod +x run_stage.sh
mkdir -p logs status
```

### 2. Launch all four stages in parallel dmux panes

From inside a dmux session (or scripted with `dmux spawn` / `n` prompts):

```bash
dmux spawn "./run_stage.sh Extraction logs/extract.log   status/extract.status   -- python extract.py"
dmux spawn "./run_stage.sh Validation logs/validate.log  status/validate.status  -- ./target/release/validate"
dmux spawn "./run_stage.sh Transformation logs/transform.log status/transform.status -- psql -f transform.sql"
dmux spawn "./run_stage.sh Loading logs/load.log         status/load.status      -- bash load.sh"
```

(If your dmux version has no `spawn`, press `n` in the dmux UI and paste each command as the pane prompt — the panes run plain shell commands fine.)

### 3. Wait for all panes to finish

```bash
while [ "$(ls status/*.status 2>/dev/null | wc -l)" -lt 4 ]; do sleep 2; done
```

### 4. Summary generation

```bash
printf "Stage | Exit Code\n------|----------\n"
for s in extract validate transform load; do
  name=$(echo "$s" | sed 's/^\(.\)/\U\1/')
  printf "%s | %s\n" "$name" "$(cat status/$s.status)"
done
```

Example output:

```
Stage | Exit Code
------|----------
Extract | 0
Validate | 1
Transform | 0
Load | 0
```

(To match your exact labels, use a mapping: `declare -A N=([extract]=Extraction [validate]=Validation [transform]=Transformation [load]=Loading)` and print `"${N[$s]}"`.)

### Notes
- Each stage's stdout/stderr goes to its own `logs/*.log`; exit codes land in `status/*.status`.
- Stages are fully independent, so parallel panes are safe (per the skill's best practices).
- If a stage hangs, inspect its pane with `m` in dmux, or add a `timeout 600` prefix inside `run_stage.sh`.

The simplest setup is **tmux** with three panes — no extra tooling needed.

## 1. Create the session and panes

```bash
# Create a detached session named "agents"
tmux new-session -d -s agents -c ~/path/to/repo

# Split into three panes (one split, then split one pane again)
tmux split-window -h -t agents
tmux split-window -v -t agents:0.1

# Optional: even out the layout
tmux select-layout -t agents tiled
```

## 2. Launch each agent in its pane

Assuming your agents are CLI tools (e.g., `claude`, `aider`, `codex` — substitute whatever you use):

```bash
tmux send-keys -t agents:0.0 "claude 'Update the README with the new install instructions'" Enter
tmux send-keys -t agents:0.1 "claude 'Fix parse_date in utils.py: it returns None for ISO strings'" Enter
tmux send-keys -t agents:0.2 "claude 'Add unit tests for api.py'" Enter
```

Or just attach and type into each pane manually:

```bash
tmux attach -t agents
```

Then use `Ctrl-b` then arrow keys (or `o`) to move between panes and start each agent.

## 3. Reattach later

```bash
tmux attach -t agents
```

The session (and all three agents) keeps running even if you disconnect. Useful extras:

- `Ctrl-b z` — zoom a pane full-screen, press again to restore
- `tmux list-sessions` — see running sessions
- `tmux kill-session -t agents` — clean up when done

## One caveat: parallel agents + git

Three agents editing the same working tree concurrently can clobber each other (e.g., two of them running `git commit` at once). Two easy mitigations:

- **Git worktrees** — give each agent its own checkout:
  ```bash
  git worktree add ../repo-readme main
  git worktree add ../repo-utils  main
  git worktree add ../repo-tests  main
  ```
  Then point each pane at a different worktree (`-c` flag or `cd` in the pane), and merge the branches afterward.
- Or just accept the risk if the tasks touch disjoint files (yours mostly do — README, utils.py, api.py/tests) and review before committing.

For three small, disjoint tasks, plain tmux with a shared checkout is usually fine; add worktrees if you see conflicts.

Your three tasks are independent (README, `utils.py`, `api.py` tests — no overlapping files), so parallel panes are a good fit. The simplest setup is **dmux**:

## 1. Install (one-time)

```bash
npm install -g dmux
# dmux uses tmux under the hood
brew install tmux        # macOS
# or: apt install tmux   # Linux
```

## 2. Start the session

```bash
cd /path/to/your/repo
dmux
```

## 3. Launch the three agents

Inside dmux, press `n` three times to create three panes, giving each a prompt:

- **Pane 1:** `Update README.md with the new install instructions.`
- **Pane 2:** `Fix the bug in utils.py where parse_date returns None for ISO format strings. Add a regression check.`
- **Pane 3:** `Add unit tests for api.py covering all public functions.`

If you prefer non-interactive launching, you can seed each pane with its harness directly:

```bash
dmux claude "Update README.md with the new install instructions."
dmux claude "Fix parse_date in utils.py to correctly parse ISO strings."
dmux claude "Write unit tests for api.py."
```

(Or mix harnesses per pane, e.g. `dmux codex "..."` — each pane runs its own agent session.)

## 4. Monitor and merge

- Press `m` on a pane to merge/inspect its output back into the main session.
- Review each pane's diff before merging results — since all three touch different files, there should be no conflicts, so no git worktrees are needed here.

## 5. Detach and reattach later

dmux sessions persist in tmux, so:

```bash
# Detach: Ctrl-b then d  (or just close the terminal)

# Reattach later:
dmux attach
# or, if you named the session:
tmux attach -t dmux
```

That's it — three agents working simultaneously, one per pane, reattachable anytime.