/claude-code-orchestration

name: Claude Code Orchestration
description: Skill for orchestrating Claude Code sessions from OpenClaw. Covers launching, monitoring, multi-turn interaction, lifecycle management, notifications, and parallel work patterns.
metadata: {"openclaw": {"requires": {"plugins": ["openclaw-claude-code-plugin"]}}}

Claude Code Orchestration

You orchestrate Claude Code sessions via the `openclaw-claude-code-plugin`. Each session is an autonomous agent that executes code tasks in the background.

---

1. Launching sessions

Mandatory rules

• **Notifications are routed automatically** via `agentChannels` config. Do NOT pass `channel` manually — it bypasses automatic routing.
• **Always pass `multi_turn: true`** unless the task is a guaranteed one-shot with no possible follow-up.
• **Name the sessions** with `name` in kebab-case, short and descriptive.
• **Set `workdir`** to the target project directory, not the agent's workspace.

Essential parameters

| Parameter | When to use | |---|---| | `prompt` | Always. Clear and complete instruction. | | `name` | Always. Descriptive kebab-case (`fix-auth-bug`, `add-dark-mode`). | | `channel` | **Do NOT pass.** Resolved automatically via `agentChannels`. | | `workdir` | Always when the project is not in the `defaultWorkdir`. | | `multi_turn` | `true` by default unless explicitly one-shot. | | `max_budget_usd` | Adjust accordingly: `1-2` for a small fix, `5` for a feature, `10+` for a major refactoring. | | `model` | When you want to force a specific model (`"sonnet"`, `"opus"`). | | `system_prompt` | To inject project-specific context. | | `permission_mode` | `"bypassPermissions"` by default. `"acceptEdits"` for more control. |

Examples

# Simple task
claude_launch(
  prompt: "Fix the null pointer in src/auth.ts line 42",
  name: "fix-null-auth",
  workdir: "/home/user/projects/myapp",
  multi_turn: true,
  max_budget_usd: 2
)

# Full feature
claude_launch(
  prompt: "Implement dark mode toggle in the settings page. Use the existing theme context in src/context/theme.tsx. Add a toggle switch component and persist the preference in localStorage.",
  name: "add-dark-mode",
  workdir: "/home/user/projects/myapp",
  multi_turn: true,
  max_budget_usd: 5
)

# Major refactoring
claude_launch(
  prompt: "Refactor the database layer to use the repository pattern. Migrate all direct Prisma calls in src/services/ to use repositories in src/repositories/.",
  name: "refactor-db-repositories",
  workdir: "/home/user/projects/myapp",
  multi_turn: true,
  max_budget_usd: 10,
  model: "opus"
)

Resume and fork

# Resume a completed session
claude_launch(
  prompt: "Continue. Also add error handling for the edge cases we discussed.",
  resume_session_id: "fix-null-auth",
  multi_turn: true
)

# Fork to try an alternative approach
claude_launch(
  prompt: "Try a completely different approach: use middleware instead of decorators.",
  resume_session_id: "refactor-db-repositories",
  fork_session: true,
  name: "refactor-db-middleware-approach",
  multi_turn: true
)

---

2. Monitoring sessions

List sessions

# All sessions
claude_sessions()

# Only running sessions
claude_sessions(status: "running")

# Completed sessions (for resume)
claude_sessions(status: "completed")

View output

# Summary (last 50 lines)
claude_output(session: "fix-null-auth")

# Full output (up to 200 blocks)
claude_output(session: "fix-null-auth", full: true)

# Specific last N lines
claude_output(session: "fix-null-auth", lines: 100)

Real-time streaming

# Switch to foreground (displays catchup of missed outputs + live stream)
claude_fg(session: "fix-null-auth")

# Switch back to background (stops the stream, session continues)
claude_bg(session: "fix-null-auth")

# Detach all foreground sessions from a channel
claude_bg()

**Note:** `claude_fg` first displays a catchup "Catchup (N missed outputs):" with everything that happened in the background, then starts live streaming.

---

3. Multi-turn interaction

Send a follow-up

# Reply to a Claude question
claude_respond(session: "add-dark-mode", message: "Yes, use CSS variables for the theme colors.")

# Redirect a running session (interrupts the current turn)
claude_respond(session: "add-dark-mode", message: "Stop. Use Tailwind dark: classes instead of CSS variables.", interrupt: true)

When to auto-respond vs forward to the user

**Auto-respond immediately with `claude_respond`:**

• Permission requests to read/write files or run bash commands -> `"Yes, proceed."`
• Confirmations like "Should I continue?" -> `"Yes, continue."`
• Questions about the approach when only one is reasonable -> Respond with the obvious choice
• Clarification requests about the codebase -> Respond if you know, otherwise `"Use your best judgment."`

**Forward to the user:**

• Architecture decisions (Redis vs PostgreSQL, REST vs GraphQL...)
• Destructive operations (deleting files, dropping tables...)
• Ambiguous requirements not covered by the initial prompt
• Scope or budget changes ("This will require refactoring 15 files")
• Anything involving credentials, secrets, or production environments
• When in doubt -> always forward to the user

Interaction cycle

1. Session launches -> runs in background 2. Wake event `openclaw system event` arrives when the session is waiting for input 3. Read the question with `claude_output(session, full: true)` 4. Decide: auto-respond or forward 5. If auto-respond: `claude_respond(session, answer)` 6. If forward: relay the question to the user, wait for their response, then `claude_respond`

---

4. Lifecycle management

Stop a session

claude_kill(session: "fix-null-auth")

Use when:

• The session is stuck or looping
• Budget is being wasted on the wrong approach
• The user requests a stop

Timeouts

• Idle multi-turn sessions are automatically killed after `idleTimeoutMinutes` (default: 30 min)
• Completed session