Skip to main content
skill CX Codex

task-orchestrator — Claude Code skill: features and install

The task-orchestrator skill sorts GitHub tasks by dependency and runs independent work in separate git worktrees and tmux sessions with Codex. It’s for projects that need coordinated parallel task execution.

MIT ★ 239 updated 2026-08-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jdrhyne/agent-skills --skill task-orchestrator -a claude-code
Open on GitHub

What task-orchestrator does

The skill fetches open issues with gh, groups work by files and declared dependencies, then arranges tasks into phases. Work that touches the same file must run in sequence. Each task gets its own branch, git worktree, and tmux session, where Codex handles execution.

A monitor checks session output for completion, errors, or prompts waiting for input. It can save error logs and restart a task with failure context. The setup requires tmux, codex, and gh; without them, this workflow cannot launch. The instructions also rule out endless retries and prohibit pushing branches or merging when human review is needed.

What it helps with

  • Sort GitHub issues by task dependencies
  • Separate work that can run in parallel
  • Launch tasks in isolated git worktrees
  • Monitor Codex sessions for errors or stalled prompts
  • Restart a failed task with its error context

Example prompts for the agent

  • Review the open issues in OWNER/REPO, map dependencies, and split them into phases.
  • Run the independent tasks from the manifest in separate worktrees and tmux sessions.
  • Check the task sessions, save error logs, and restart stalled work with its failure context.

How to install task-orchestrator

1Skills CLI (Vercel)

npx skills add jdrhyne/agent-skills --skill task-orchestrator -a claude-code

2Manually: put the files in place

~/.claude/skills/task-orchestrator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/task-orchestrator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about task-orchestrator

How do I install task-orchestrator in Claude Code?

Run npx skills add jdrhyne/agent-skills --skill task-orchestrator -a claude-code. The skill file is at ~/.claude/skills/task-orchestrator/SKILL.md.

What does task-orchestrator do?

It maps dependencies between GitHub issues, starts independent tasks with Codex in separate git worktrees and tmux sessions, then monitors their state.

What does task-orchestrator need to run?

The workflow requires tmux, codex, and gh. Tasks that modify the same file must also be run in sequence.

Source text

SKILL.md · MIT
---
name: task-orchestrator
description: Autonomous multi-agent task orchestration with dependency analysis, parallel tmux/Codex execution, and self-healing heartbeat monitoring. Use for large projects with multiple issues/tasks that need coordinated parallel execution.
metadata: {"clawdbot":{"emoji":"🎭","requires":{"anyBins":["tmux","codex","gh"]}}}
permissions:
  - exec: "Runs local git, tmux, gh, and codex commands to coordinate isolated task workers."
  - file_write: "Creates manifests, logs, and per-task working directories for the orchestration run."
  - network: "Uses GitHub CLI and git remotes for issue metadata and repository operations."
---

# Task Orchestrator

Autonomous orchestration of multi-agent builds using tmux + Codex with self-healing monitoring.

**Load the senior-engineering skill alongside this one for engineering principles.**

## Safety Boundaries

- Do not launch parallel workers for tasks with overlapping write scope until the dependency is resolved.
- Do not push branches, merge work, or self-heal by guessing when human review is required.
- Do not store secrets in manifests, logs, prompts, or tmux pane captures.
- Do not continue retrying a failing task indefinitely; stop and surface the blocker after bounded retries.

## Core Concepts

### 1. Task Manifest
A JSON file defining all tasks, their dependencies, files touched, and status.

```json
{
  "project": "project-name",
  "repo": "owner/repo",
  "workdir": "/path/to/worktrees",
  "created": "2026-01-17T00:00:00Z",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {
          "id": "t1",
          "issue": 1,
          "title": "Fix X",
          "files": ["src/foo.js"],
          "dependsOn": [],
          "status": "pending",
          "worktree": null,
          "tmuxSession": null,
          "startedAt": null,
          "lastProgress": null,
          "completedAt": null,
          "prNumber": null
        }
      ]
    }
  ]
}
```

### 2. Dependency Rules
- **Same file = sequential** — Tasks touching the same file must run in order or merge
- **Different files = parallel** — Independent tasks can run simultaneously
- **Explicit depends = wait** — `dependsOn` array enforces ordering
- **Phase gates** — Next phase waits for current phase completion

### 3. Execution Model
- Each task gets its own **git worktree** (isolated branch)
- Each task runs in its own **tmux session**
- Use **Codex with --yolo** for autonomous execution
- Model: **GPT-5.2-codex high** (configurable)

---

## Setup Commands

### Initialize Orchestration

```bash
# 1. Create working directory
WORKDIR="${TMPDIR:-/tmp}/orchestrator-$(date +%s)"
mkdir -p "$WORKDIR"

# 2. Clone repo for worktrees
git clone https://github.com/OWNER/REPO.git "$WORKDIR/repo"
cd "$WORKDIR/repo"

# 3. Create tmux socket
SOCKET="$WORKDIR/orchestrator.sock"

# 4. Initialize manifest
cat > "$WORKDIR/manifest.json" << 'EOF'
{
  "project": "PROJECT_NAME",
  "repo": "OWNER/REPO",
  "workdir": "WORKDIR_PATH",
  "socket": "SOCKET_PATH",
  "created": "TIMESTAMP",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": []
}
EOF
```

### Analyze GitHub Issues for Dependencies

```bash
# Fetch all open issues
gh issue list --repo OWNER/REPO --state open --json number,title,body,labels > issues.json

# Group by files mentioned in issue body
# Tasks touching same files should serialize
```

### Create Worktrees

```bash
# For each task, create isolated worktree
cd "$WORKDIR/repo"
git worktree add -b fix/issue-N "$WORKDIR/task-tN" main
```

### Launch Tmux Sessions

```bash
SOCKET="$WORKDIR/orchestrator.sock"

# Create session for task
tmux -S "$SOCKET" new-session -d -s "task-tN"

# Launch Codex (uses gpt-5.2-codex with reasoning_effort=high from ~/.codex/config.toml)
# Note: Model config is in ~/.codex/config.toml, not CLI flag
tmux -S "$SOCKET" send-keys -t "task-tN" \
  "cd $WORKDIR/task-tN && codex --yolo 'Fix issue #N: DESCRIPTION. Run tests, commit with good message, push to origin.'" Enter
```

---

## Monitoring & Self-Healing

### Progress Check Script

```bash
#!/bin/bash
# check_progress.sh - Run via heartbeat

WORKDIR="$1"
SOCKET="$WORKDIR/orchestrator.sock"
MANIFEST="$WORKDIR/manifest.json"
STALL_THRESHOLD_MINS=20

check_session() {
  local session="$1"
  local task_id="$2"
  
  # Capture recent output
  local output=$(tmux -S "$SOCKET" capture-pane -p -t "$session" -S -50 2>/dev/null)
  
  # Check for completion indicators
  if echo "$output" | grep -qE "(All tests passed|Successfully pushed|❯ $)"; then
    echo "DONE:$task_id"
    return 0
  fi
  
  # Check for errors
  if echo "$output" | grep -qiE "(error:|failed:|FATAL|panic)"; then
    echo "ERROR:$task_id"
    return 1
  fi
  
  # Check for stall (prompt waiting for input)
  if echo "$output" | grep -qE "(\? |Continue\?|y/n|Press any key)"; then
    echo "STUCK:$task_id:waiting_for_input"
    return 2
  fi
  
  echo "RUNNING:$task_id"
  return 0
}

# Check all active sessions
for session in $(tmux -S "$SOCKET" list-sessions -F "#{session_name}" 2>/dev/null); do
  check_session "$session" "$session"
done
```

### Self-Healing Actions

When a task is stuck, the orchestrator should:

1. **Waiting for input** → Send appropriate response
   ```bash
   tmux -S "$SOCKET" send-keys -t "$session" "y" Enter
   ```

2. **Error/failure** → Capture logs, analyze, retry with fixes
   ```bash
   # Capture error context
   tmux -S "$SOCKET" capture-pane -p -t "$session" -S -100 > "$WORKDIR/logs/$task_id-error.log"
   
   # Kill and restart with error context
   tmux -S "$SOCKET" kill-session -t "$session"
   tmux -S "$SOCKET" new-session -d -s "$session"
   tmux -S "$SOCKET" send-keys -t "$session" \
     "cd $WORKDIR/$task_id && codex --model gpt-5.2-codex-high --yolo 'Previous attempt failed with: $(cat error.log | tail -20). Fix the issue and retry.'" Enter
   ```

3. **No progress for 20+ mins** → Nudge or restart
   ```bash
   # Check git log for recent commits
   cd "$WORKDIR/$task_id"
   LAST_COMMIT=$(git log -1 --format="%ar" 2>/dev/null)
   
   # If no commits in threshold, restart
   ```

### Heartbeat Cron Setup

```bash
# Add to cron (every 15 minutes)
cron action:add job:{
  "label": "orchestrator-heartbeat",
  "schedule": "*/15 * * * *",
  "prompt": "Check orchestration progress at WORKDIR. Read manifest, check all tmux sessions, self-heal any stuck tasks, advance to next phase if current is complete. Do NOT ping human - fix issues yourself."
}
```

---

## Workflow: Full Orchestration Run

### Step 1: Analyze & Plan

```bash
# 1. Fetch issues
gh issue list --repo OWNER/REPO --state open --json number,title,body > /tmp/issues.json

# 2. Analyze for dependencies (files mentioned, explicit deps)
# Group into phases:
# - Phase 1: Critical/blocking issues (no deps)
# - Phase 2: High priority (may depend on Phase 1)
# - Phase 3: Medium/low (depends on earlier phases)

# 3. Within each phase, identify:
# - Parallel batch: Different files, no deps → run simultaneously
# - Serial batch: Same files or explicit deps → run in order
```

### Step 2: Create Manifest

Write manifest.json with all tasks, dependencies, file mappings.

### Step 3: Launch Phase 1

```bash
# Create worktrees for Phase 1 tasks
for task in phase1_tasks; do
  git worktree add -b "fix/issue-$issue" "$WORKDIR/task-$id" main
done

# Launch tmux sessions
for task in phase1_parallel_batch; do
  tmux -S "$SOCKET" new-session -d -s "task-$id"
  tmux -S "$SOCKET" send-keys -t "task-$id" \
    "cd $WORKDIR/task-$id && codex --model gpt-5.2-codex-high --yolo '$PROMPT'" Enter
done
```

### Step 4: Monitor & Self-Heal

Heartbeat checks every 15 mins:
1. Poll all sessions
2. Update manifest with progress
3. Self-heal stuck tasks
4. When all Phase N tasks complete → launch Phase N+1

### Step 5: Create PRs

```bash
# When task completes successfully
cd "$WORKDIR/task-$id"
git push -u origin "fix/issue-$issue"
gh pr create --repo OWNER/REPO \
  --head "fix/issue-$issue" \
  --title "fix: Issue #$issue - $TITLE" \
  --body "Closes #$issue

## Changes
[Auto-generated by Codex orchestrator]

## Testing
- [ ] Unit tests pass
- [ ] Manual verification"
```

### Step 6: Cleanup

```bash
# After all PRs merged or work complete
tmux -S "$SOCKET" kill-server
cd "$WORKDIR/repo"
for task in all_tasks; do
  git worktree remove "$WORKDIR/task-$id" --force
done
rm -rf "$WORKDIR"
```

---

## Manifest Status Values

| Status | Meaning |
|--------|---------|
| `pending` | Not started yet |
| `blocked` | Waiting on dependency |
| `running` | Codex session active |
| `stuck` | Needs intervention (auto-heal) |
| `error` | Failed, needs retry |
| `complete` | Done, ready for PR |
| `pr_open` | PR created |
| `merged` | PR merged |

---

## Example: Security Framework Orchestration

```json
{
  "project": "nuri-security-framework",
  "repo": "jdrhyne/nuri-security-framework",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {"id": "t1", "issue": 1, "files": ["ceo_root_manager.js"], "dependsOn": []},
        {"id": "t2", "issue": 2, "files": ["ceo_root_manager.js"], "dependsOn": ["t1"]},
        {"id": "t3", "issue": 3, "files": ["workspace_validator.js"], "dependsOn": []}
      ]
    },
    {
      "name": "Phase 2: High",
      "tasks": [
        {"id": "t4", "issue": 4, "files": ["kill_switch.js", "container_executor.js"], "dependsOn": []},
        {"id": "t5", "issue": 5, "files": ["kill_switch.js"], "dependsOn": ["t4"]},
        {"id": "t6", "issue": 6, "files": ["ceo_root_manager.js"], "dependsOn": ["t2"]},
        {"id": "t7", "issue": 7, "files": ["container_executor.js"], "dependsOn": []},
        {"id": "t8", "issue": 8, "files": ["container_executor.js", "egress_proxy.js"], "dependsOn": ["t7"]}
      ]
    }
  ]
}
```

**Parallel execution in Phase 1:**
- t1 and t3 run in parallel (different files)
- t2 waits for t1 (same file)

**Parallel execution in Phase 2:**
- t4, t6, t7 can start together
- t5 waits for t4, t8 waits for t7

---

## Tips

1. **Always use GPT-5.2-codex high** for complex work: `--model gpt-5.2-codex-high`
2. **Clear prompts** — Include issue number, description, expected outcome, test instructions
3. **Atomic commits** — Tell Codex to commit after each logical change
4. **Push early** — Push to remote branch so progress isn't lost if session dies
5. **Checkpoint logs** — Capture tmux output periodically to files
6. **Phase gates** — Don't start Phase N+1 until Phase N is 100% complete
7. **Self-heal aggressively** — If stuck >10 mins, intervene automatically
8. **Browser relay limits** — If CDP automation is blocked, use iframe batch scraping or manual browser steps

---

## Integration with Other Skills

- **senior-engineering**: Load for build principles and quality gates
- **coding-agent**: Reference for Codex CLI patterns
- **github**: Use for PR creation, issue management

---

## Lessons Learned (2026-01-17)

### Codex Sandbox Limitations
When using `codex exec --full-auto`, the sandbox:
- **No network access** — `git push` fails with "Could not resolve host"
- **Limited filesystem** — Can't write to paths like `~/nuri_workspace`

### Heartbeat Detection Improvements
The heartbeat should check for:
1. **Shell prompt idle** — If tmux pane shows `username@hostname path %`, worker is done
2. **Unpushed commits** — `git log @{u}.. --oneline` shows commits not on remote
3. **Push failures** — Look for "Could not resolve host" in output

When detected, the orchestrator (not the worker) should:
1. Push the commit from outside the sandbox
2. Create the PR via `gh pr create`
3. Update manifest and notify

### Recommended Pattern
```bash
# In heartbeat, for each task:
cd /tmp/orchestrator-*/task-tN
if tmux capture-pane shows shell prompt; then
  # Worker finished, check for unpushed work
  if git log @{u}.. --oneline | grep -q .; then
    git push -u origin HEAD
    gh pr create --title "$(git log --format=%s -1)" --body "Closes #N" --base main
  fi
fi
```

© jdrhyne · MIT · jdrhyne/agent-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →
xcode-build-orchestrator AvdLee xcode-build-orchestrator runs Xcode build optimization in two phases: benchmark and plan first, apply approved fixes second, then re-measure. CX Codex +1 3,700installs edge-pipeline-orchestrator tradermonty edge-pipeline-orchestrator is a Claude Code skill that runs market-edge research from candidate discovery through strategy review and export. It starts multi-stage workflows end to end. CX Codex +1 3,500installs ccf-pipeline-orchestrator mikubaka88 The ccf-pipeline-orchestrator Claude Code skill plans research stages and coordinates specialist skills. It handles task breakdown, project tracking, and explicitly requested autonomous research. CX Codex +1 2,200installs planetscale-safe-orchestrator planetscale planetscale-safe-orchestrator — a Claude Code skill that runs the entire PlanetScale safe best-practices pack: inventory, engine review, Insights, Traffic Control, webhooks, schema, code instrumentation, and agent operating model. CX Codex +1 2,000installs tracelens-analysis-orchestrator amd tracelens-analysis-orchestrator orchestrates modular PyTorch profiler trace analysis with TraceLens, running parallel subagents and generating a prioritized report. Triggered when analyzing traces or running workflows. CX Codex +1 1,300installs marketing-orchestrator-skill reason-machines marketing-orchestrator-skill routes marketing work across six specialized sub-agents, tracks client profiles in markdown, and validates ad character counts. CX Codex +1 894installs

From the same set27

The whole set →
gallery-scraper gallery-scraper — a Claude skill that collects full-size image URLs from a gallery behind a login and downloads them in bulk through an attached browser tab. CX Codex +1 ★ 239repo stars gong Fetches call records, transcript snippets, and team stats via Gong API. Useful when inspecting customer conversations and sales activity directly in chat. CX Codex +1 ★ 239repo stars munger-observer The munger-observer skill reviews a concrete decision, plan, or artifact, separating evidence from interpretation and suggesting a check. Use it for a premortem or a blind-spot review. CX Codex +1 ★ 239repo stars context-recovery context-recovery rebuilds the state of your work after compaction or truncation, and shows where each recovered fact came from. CX Codex +1 ★ 239repo stars autoresearch-loop The autoresearch-loop skill helps an agent choose project metrics and test changes in a keep-or-revert cycle. Use it when progress can be measured against an objective. CX Codex +1 ★ 239repo stars google-ads A Claude skill that audits Google Ads accounts: spend, keywords, search terms, budgets, conversion tracking. Read-only until you approve a specific change. CX Codex +1 ★ 239repo stars nutrient-openclaw nutrient-openclaw governs document workflows through the Nutrient plugin in Claude Code. Manages DWS credit spending, secures credentials, and enforces confirmation before files are uploaded. CX Codex +1 ★ 239repo stars salesforce Wraps the Salesforce CLI so the agent can run SOQL and SOSL, read or edit records, and pull bulk exports without leaving the chat. CX Codex +1 ★ 239repo stars

Project sponsors

Companies that keep this analytics open