- Multitask Skill
- Purpose
- Execute multiple independent development tasks in parallel. Each workstream runs in an isolated
- /tmp
- clone with its own Recipe Runner process following code-enforced workflow steps.
- Key Advantage
-
- Uses Recipe Runner YAML recipes instead of prompt-based markdown workflows. Python controls step execution, making it impossible to skip steps.
- Quick Start
- Inline Tasks
- /multitask
- - #123 (feat/add-auth): Implement user authentication
- - #124 (feat/add-logging): Add structured logging
- - #125 (feat/update-api): Update API endpoints
- JSON Config
- Create
- workstreams.json
- :
- [
- {
- "issue"
- :
- 123
- ,
- "branch"
- :
- "feat/add-auth"
- ,
- "description"
- :
- "User authentication"
- ,
- "task"
- :
- "Implement JWT-based authentication with login/logout endpoints"
- ,
- "recipe"
- :
- "default-workflow"
- }
- ,
- {
- "issue"
- :
- 124
- ,
- "branch"
- :
- "feat/add-logging"
- ,
- "description"
- :
- "Structured logging"
- ,
- "task"
- :
- "Add structured JSON logging across all API endpoints"
- }
- ]
- Then:
- /multitask workstreams.json
- How It Works
- User provides task list
- |
- v
- For each task:
- 1. Clone branch to /tmp/amplihack-workstreams/ws-{issue}/
- 2. Write launcher.py (Recipe Runner with CLISubprocessAdapter)
- 3. Write run.sh (sets session tree vars, runs launcher.py)
- 4. Launch subprocess via Popen
- |
- v
- Monitor all workstreams (60s intervals)
- |
- v
- Report: PR numbers, success/failure, runtime
- Why Recipe Runner?
- Aspect
- Classic (markdown)
- Recipe Runner (YAML)
- Step ordering
- Prompt-based (skippable)
- Code-enforced (Python loop)
- Template variables
- None
- {{task_description}}
- ,
- {{repo_path}}
- Error handling
- Implicit
- Fail-fast per step
- Progress tracking
- Opaque
- Step-by-step status
- Critical Implementation Details
- /tmp
- clones
- (not worktrees): Worktree symlinks confuse nested Claude sessions. Clean clones avoid this.
- --subprocess-safe
-
- Classic mode passes this flag to skip staging/env updates, preventing concurrent write races on
- ~/.amplihack/.claude/
- (issue #2567).
- Recipe Runner adapter
- :
- CLISubprocessAdapter
- shells out to
- claude -p
- for each agent step within the recipe (no
- amplihack
- wrapper, so no staging race).
- Child env cleanup
- The shared build_child_env() utility strips blocking env vars and propagates session tree context. Execution Modes Recipe Mode (Default) Each workstream runs run_recipe_by_name() through a Python launcher: from amplihack . recipes import run_recipe_by_name from amplihack . recipes . adapters . cli_subprocess import CLISubprocessAdapter adapter = CLISubprocessAdapter ( cli = "claude" , working_dir = "." ) result = run_recipe_by_name ( "default-workflow" , adapter = adapter , user_context = { "task_description" : task , "repo_path" : "." } ) Classic Mode Falls back to single-session prompt-based execution with --subprocess-safe to avoid concurrent staging races (see issue #2567): amplihack claude --subprocess-safe -- -p "@TASK.md Execute autonomously following DEFAULT_WORKFLOW.md." The --subprocess-safe flag skips all staging/env updates so parallel workstreams don't race on ~/.amplihack/.claude/ . The parent amplihack process has already staged the framework files. Use --mode classic when Recipe Runner is unavailable or for tasks that benefit from full session context. Available Recipes Any recipe in amplifier-bundle/recipes/ can be used per-workstream: Recipe Steps Best For default-workflow 52 Features, bugs, refactoring (default) investigation-workflow 23 Research, codebase analysis verification-workflow 5 Trivial changes, config updates auto-workflow 9 Autonomous iteration until complete Specify per-task: "recipe": "investigation-workflow" in JSON config. Monitoring
Watch all logs
tail -f /tmp/amplihack-workstreams/log-*.txt
Check specific workstream
tail -f /tmp/amplihack-workstreams/log-123.txt
Check running processes
ps aux | grep launcher.py
Final report
cat /tmp/amplihack-workstreams/REPORT.md When to Read Supporting Files Need File Full API, config options, architecture reference.md Real-world usage examples examples.md Python orchestrator source orchestrator.py Disk Management & Cleanup Understanding Disk Usage Each workstream creates a full git clone (~1.5GB). With 10 parallel workstreams, this is ~15GB of temporary disk usage. Locations: /tmp/amplihack-workstreams/ws-{issue}/ - Each workstream's working directory /tmp/amplihack-workstreams/log-{issue}.txt - Log files (kept separately) /tmp/amplihack-workstreams/REPORT.md - Final execution report When to Clean Up ✅ SAFE to delete: PR has been merged to main You've finished debugging/inspecting the workstream You need disk space for new workstreams All PRs from a multitask session are complete ❌ NOT safe to delete: PR is still under review PR has merge conflicts you need to resolve manually You might need to inspect the working directory for debugging Workstream failed and you haven't diagnosed the issue Manual Cleanup Commands
Check disk usage first
du -sh /tmp/amplihack-workstreams/*
Clean up specific workstream (after PR merged)
rm -rf /tmp/amplihack-workstreams/ws-123
Clean up all workstreams (after all PRs merged)
rm -rf /tmp/amplihack-workstreams/ws-*
Keep log files, delete only working directories
find /tmp/amplihack-workstreams -type d -name "ws-*" -exec rm -rf { } +
Check available disk space
df -h /tmp Automatic Cleanup (Helper Command) After merging PRs, use the cleanup helper to automatically remove merged workstreams:
Clean up all workstreams with merged PRs
python .claude/skills/multitask/orchestrator.py --cleanup workstreams.json
Dry run (show what would be deleted)
python .claude/skills/multitask/orchestrator.py --cleanup --dry-run workstreams.json The cleanup helper: Checks each workstream's PR status using gh CLI Only deletes workstreams with MERGED status Preserves log files for historical reference Reports disk space freed Disk Space Monitoring The orchestrator automatically checks disk space before launching workstreams: ⚠️ WARNING: Only 8.2GB free in /tmp Each workstream requires ~1.5GB. Consider cleaning up: rm -rf /tmp/amplihack-workstreams/ws-* Continue anyway? (y/N): Rule of thumb: Keep at least 20GB free for comfortable multi-workstream development. Preventing Disk Issues Before large multitask runs (10+ workstreams): df -h /tmp
Check available space
rm -rf /tmp/amplihack-workstreams/ws-*
Clean old workstreams
- After merging PRs
- :
- python orchestrator.py
- --cleanup
- workstreams.json
- Monitor during execution
- :
- watch
- -n
- 60
- 'du -sh /tmp/amplihack-workstreams && df -h /tmp'
- Troubleshooting
- Empty log files
-
- Process started but exited immediately. Check if
- amplihack
- package is importable in the clone's environment.
- Recipe not found
-
- Ensure
- amplifier-bundle/recipes/
- exists in the cloned branch. The recipe discovery checks this directory first.
- Fallback
-
- If recipe mode fails, retry with
- --mode classic
- to use the prompt-based approach.
- Disk full during execution
- The orchestrator warns if <10GB free. If disk fills mid-execution, manually clean up: rm -rf /tmp/amplihack-workstreams/ws-* (after stopping running workstreams).