parallel-task-tmux

Name: parallel-task-tmux
Author: am-will

222stars12forks

How to install parallel-task-tmux?

am-will/swarms/parallel-task-tmux

$npx -y skills add am-will/swarms --skill parallel-task-tmux

Installs into the current project.

Summary

Only to be triggered by explicit /parallel-task-tmux commands. Dependency-aware parallel plan execution that launches each unblocked Codex worker in a live tmux pane, keeps pane output visible in real time, and shrinks the layout by closing panes as tasks complete.

Files · 1

View on GitHub

SKILL.md

1	# Parallel Task Executor (tmux Live Workers)
2
3	Run dependency-ordered plan execution like `parallel-task`, but route each worker through `codex exec` inside tmux panes so progress is visible in real time.
4
5	Use this skill when you want:
6	- Live visibility into each running worker
7	- A tiled worker view that expands as tasks launch
8	- Automatic pane cleanup that shrinks the layout as tasks finish
9
10	## Execution Model
11
12	1. Parse the plan and compute unblocked tasks by `depends_on`.
13	2. Build one worker prompt file per task.
14	3. Launch one tmux pane per task via `scripts/tmux_spawn_worker.sh`.
15	4. Monitor status/logs and reap completed panes via `scripts/tmux_reap_completed.sh`.
16	5. Validate completed tasks before advancing to the next dependency wave.
17	6. Repeat until all requested tasks are complete.
18
19	## Preflight
20
21	Run these checks before launching workers:
22
23	```bash
24	command -v tmux >/dev/null
25	command -v codex >/dev/null
26	```
27
28	Resolve the skill directory once so helper script paths are stable:
29
30	```bash
31	SKILL_ROOT="$(fd -td -p 'parallel-task-tmux' "$PWD" "$HOME/.codex/skills" "$HOME/.agents/skills" 2>/dev/null \| head -n 1)"
32	```
33
34	Fail fast if `SKILL_ROOT` is empty.
35
36	Initialize one run directory per execution:
37
38	```bash
39	PLAN_FILE="./plan.md"
40	PLAN_BASE="$(basename "$PLAN_FILE" .md)"
41	RUN_ID="$(date +%Y%m%d-%H%M%S)"
42	SESSION_NAME="swarms-${PLAN_BASE}-${RUN_ID}"
43	RUN_ROOT=".swarms/tmux/${SESSION_NAME}"
44	mkdir -p "$RUN_ROOT/prompts" "$RUN_ROOT/logs"
45	: > "$RUN_ROOT/status.tsv"
46	: > "$RUN_ROOT/task_map.tsv"
47	: > "$RUN_ROOT/reaped.tsv"
48	```
49
50	## Plan Parsing and Scheduling
51
52	Mirror `parallel-task` behavior:
53	- Parse task sections (for example `### T1:`).
54	- Extract task id, title, `depends_on`, location, description, acceptance criteria, validation.
55	- Filter to requested subset and required dependencies if the user passes a subset.
56	- Launch only tasks whose dependencies are complete.
57
58	## Worker Prompt Contract
59
60	Create one prompt file per task at:
61	- `$RUN_ROOT/prompts/<TASK_ID>.md`
62
63	Use the same task context and completion requirements as `parallel-task`:
64	- Read the working plan and relevant files before coding.
65	- Default to TDD RED phase first using a `tdd_test_writer` subagent, or explicitly record `reason_not_testable` with an alternative verification contract.
66	- Treat RED-phase tests (or approved non-testable verification plan) as the implementation contract.
67	- Implement acceptance criteria.
68	- Keep edits atomic.
69	- Run the exact new/updated test commands until GREEN, or run the documented alternative verification and capture evidence.
70	- Commit only task-scoped files.
71	- Update the plan status/log/files after the commit.
72	- Return modified files, criteria coverage, and RED -> GREEN or non-testable verification evidence.
73
74	## Launching tmux Workers
75
76	When running inside tmux, prefer in-place splits so the user can keep chatting in the current Codex pane while workers appear beside it.
77
78	In-place mode (recommended inside tmux):
79
80	```bash
81	"$SKILL_ROOT/scripts/tmux_spawn_worker.sh" \
82	--split-current \
83	--workspace "$PWD" \
84	--task-id "$TASK_ID" \
85	--prompt-file "$RUN_ROOT/prompts/${TASK_ID}.md" \
86	--log-file "$RUN_ROOT/logs/${TASK_ID}.log" \
87	--status-file "$RUN_ROOT/status.tsv" \
88	--map-file "$RUN_ROOT/task_map.tsv"
89	```
90
91	Detached session mode (for non-tmux shells):
92
93	```bash
94	"$SKILL_ROOT/scripts/tmux_spawn_worker.sh" \
95	--session "$SESSION_NAME" \
96	--workspace "$PWD" \
97	--task-id "$TASK_ID" \
98	--prompt-file "$RUN_ROOT/prompts/${TASK_ID}.md" \
99	--log-file "$RUN_ROOT/logs/${TASK_ID}.log" \
100	--status-file "$RUN_ROOT/status.tsv" \
101	--map-file "$RUN_ROOT/task_map.tsv"
102	```
103
104	Behavior:
105	- In split-current mode, launches workers as new panes in the current tmux window.
106	- In detached mode, creates tmux session/window if missing.
107	- Re-tiles panes after each launch so the grid expands live.
108	- Streams `codex exec` output live in each pane while also writing logs to `logs/<TASK_ID>.log`.
109	- Tracks pane ids in `task_map.tsv` for deterministic cleanup.
110
111	In detached mode, if not already attached, print:
112
113	```bash
114	tmux attach -t "$SESSION_NAME"
115	```
116
117	## Monitoring and Pane Reaping
118
119	During each wave, monitor active panes:
120
121	```bash
122	tmux list-panes -t "${SESSION_NAME}:workers" -F '#{pane_id} #{pane_current_command} #{pane_dead}'
123	```
124
125	Collect completed workers and close their panes:
126
127	```bash
128	"$SKILL_ROOT/scripts/tmux_reap_completed.sh" \
129	--session "$SESSION_NAME" \
130	--status-file "$RUN_ROOT/status.tsv" \
131	--map-file "$RUN_ROOT/task_map.tsv" \
132	--seen-file "$RUN_ROOT/reaped.tsv"
133	```
134
135	This is what gives the expand/shrink behavior:
136	- Launching tasks adds panes and expands the tile grid.
137	- Reaping completed tasks kills panes and shrinks the grid.
138
139	Ins

People who liked this also viewed

6 picks

Type

parallel-task-tmux

222stars12forks

View on GitHub

How to install parallel-task-tmux?

am-will/swarms/parallel-task-tmux

$npx -y skills add am-will/swarms --skill parallel-task-tmux

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Parallel Task Executor (tmux Live Workers)
2
3	Run dependency-ordered plan execution like `parallel-task`, but route each worker through `codex exec` inside tmux panes so progress is visible in real time.
4
5	Use this skill when you want:
6	- Live visibility into each running worker
7	- A tiled worker view that expands as tasks launch
8	- Automatic pane cleanup that shrinks the layout as tasks finish
9
10	## Execution Model
11
12	1. Parse the plan and compute unblocked tasks by `depends_on`.
13	2. Build one worker prompt file per task.
14	3. Launch one tmux pane per task via `scripts/tmux_spawn_worker.sh`.
15	4. Monitor status/logs and reap completed panes via `scripts/tmux_reap_completed.sh`.
16	5. Validate completed tasks before advancing to the next dependency wave.
17	6. Repeat until all requested tasks are complete.
18
19	## Preflight
20
21	Run these checks before launching workers:
22
23	```bash
24	command -v tmux >/dev/null
25	command -v codex >/dev/null
26	```
27
28	Resolve the skill directory once so helper script paths are stable:
29
30	```bash
31	SKILL_ROOT="$(fd -td -p 'parallel-task-tmux' "$PWD" "$HOME/.codex/skills" "$HOME/.agents/skills" 2>/dev/null \| head -n 1)"
32	```
33
34	Fail fast if `SKILL_ROOT` is empty.
35
36	Initialize one run directory per execution:
37
38	```bash
39	PLAN_FILE="./plan.md"
40	PLAN_BASE="$(basename "$PLAN_FILE" .md)"
41	RUN_ID="$(date +%Y%m%d-%H%M%S)"
42	SESSION_NAME="swarms-${PLAN_BASE}-${RUN_ID}"
43	RUN_ROOT=".swarms/tmux/${SESSION_NAME}"
44	mkdir -p "$RUN_ROOT/prompts" "$RUN_ROOT/logs"
45	: > "$RUN_ROOT/status.tsv"
46	: > "$RUN_ROOT/task_map.tsv"
47	: > "$RUN_ROOT/reaped.tsv"
48	```
49
50	## Plan Parsing and Scheduling
51
52	Mirror `parallel-task` behavior:
53	- Parse task sections (for example `### T1:`).
54	- Extract task id, title, `depends_on`, location, description, acceptance criteria, validation.
55	- Filter to requested subset and required dependencies if the user passes a subset.
56	- Launch only tasks whose dependencies are complete.
57
58	## Worker Prompt Contract
59
60	Create one prompt file per task at:
61	- `$RUN_ROOT/prompts/<TASK_ID>.md`
62
63	Use the same task context and completion requirements as `parallel-task`:
64	- Read the working plan and relevant files before coding.
65	- Default to TDD RED phase first using a `tdd_test_writer` subagent, or explicitly record `reason_not_testable` with an alternative verification contract.
66	- Treat RED-phase tests (or approved non-testable verification plan) as the implementation contract.
67	- Implement acceptance criteria.
68	- Keep edits atomic.
69	- Run the exact new/updated test commands until GREEN, or run the documented alternative verification and capture evidence.
70	- Commit only task-scoped files.
71	- Update the plan status/log/files after the commit.
72	- Return modified files, criteria coverage, and RED -> GREEN or non-testable verification evidence.
73
74	## Launching tmux Workers
75
76	When running inside tmux, prefer in-place splits so the user can keep chatting in the current Codex pane while workers appear beside it.
77
78	In-place mode (recommended inside tmux):
79
80	```bash
81	"$SKILL_ROOT/scripts/tmux_spawn_worker.sh" \
82	--split-current \
83	--workspace "$PWD" \
84	--task-id "$TASK_ID" \
85	--prompt-file "$RUN_ROOT/prompts/${TASK_ID}.md" \
86	--log-file "$RUN_ROOT/logs/${TASK_ID}.log" \
87	--status-file "$RUN_ROOT/status.tsv" \
88	--map-file "$RUN_ROOT/task_map.tsv"
89	```
90
91	Detached session mode (for non-tmux shells):
92
93	```bash
94	"$SKILL_ROOT/scripts/tmux_spawn_worker.sh" \
95	--session "$SESSION_NAME" \
96	--workspace "$PWD" \
97	--task-id "$TASK_ID" \
98	--prompt-file "$RUN_ROOT/prompts/${TASK_ID}.md" \
99	--log-file "$RUN_ROOT/logs/${TASK_ID}.log" \
100	--status-file "$RUN_ROOT/status.tsv" \
101	--map-file "$RUN_ROOT/task_map.tsv"
102	```
103
104	Behavior:
105	- In split-current mode, launches workers as new panes in the current tmux window.
106	- In detached mode, creates tmux session/window if missing.
107	- Re-tiles panes after each launch so the grid expands live.
108	- Streams `codex exec` output live in each pane while also writing logs to `logs/<TASK_ID>.log`.
109	- Tracks pane ids in `task_map.tsv` for deterministic cleanup.
110
111	In detached mode, if not already attached, print:
112
113	```bash
114	tmux attach -t "$SESSION_NAME"
115	```
116
117	## Monitoring and Pane Reaping
118
119	During each wave, monitor active panes:
120
121	```bash
122	tmux list-panes -t "${SESSION_NAME}:workers" -F '#{pane_id} #{pane_current_command} #{pane_dead}'
123	```
124
125	Collect completed workers and close their panes:
126
127	```bash
128	"$SKILL_ROOT/scripts/tmux_reap_completed.sh" \
129	--session "$SESSION_NAME" \
130	--status-file "$RUN_ROOT/status.tsv" \
131	--map-file "$RUN_ROOT/task_map.tsv" \
132	--seen-file "$RUN_ROOT/reaped.tsv"
133	```
134
135	This is what gives the expand/shrink behavior:
136	- Launching tasks adds panes and expands the tile grid.
137	- Reaping completed tasks kills panes and shrinks the grid.
138
139	Ins

People who liked this also viewed

6 picks

Type