chat-plugin-Claude Code Orchestration

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 sessions are garbage-collected after 1h but remain resumable via persisted IDs

Check the result after completion

When a session completes (completion wake event):

1. claude_output(session: "xxx", full: true) to read the result
2. Summarize the result to the user
3. If failed, analyze the error and decide: relaunch, fork, or escalate

---

5. Notifications

Routing

Notifications are routed automatically based on the session's workdir using the agentChannels plugin config. Each workspace directory maps to a specific channel (e.g., telegram:seo-bot:123456789). See Agent Channels for setup.

Events

Event	What happens
Session starts	Silent
Session in foreground	Real-time stream (text debounced 500ms + tool indicators)
Session completed	Notification to the originating channel
Session failed	Error notification to the originating channel
Waiting for input	openclaw system event to wake the orchestrator + "Claude asks:" in the channel
Response sent	"Responded:" echo in the channel
Session > 10 min	One-shot reminder
Session limit reached	Notification to the channel

Background visibility

Even without foreground, the user sees in their chat:

• Claude asks: when Claude asks a question
• Responded: when a follow-up is sent

This makes the conversation transparent without needing foregrounding.

---

6. Best practices

Launch checklist

1. agentChannels is configured for this workdir -> notifications arrive
2. multi_turn: true -> interaction is possible after launch
3. name is descriptive -> easy to identify in claude_sessions
4. workdir points to the correct project -> Claude Code works in the right directory
5. max_budget_usd is calibrated -> no waste

Parallel tasks

# Launch multiple sessions on independent tasks
claude_launch(prompt: "Build the frontend auth page", name: "frontend-auth", workdir: "/app/frontend", multi_turn: true, max_budget_usd: 5)
claude_launch(prompt: "Build the backend auth API", name: "backend-auth", workdir: "/app/backend", multi_turn: true, max_budget_usd: 5)

• Respect the maxSessions limit (default: 5)
• Each session must have a unique name
• Monitor each session individually via wake events
• Don't launch too many sessions in parallel: each session consumes resources and budget

Error handling

• If a session fails, read the full output to understand why
• Relaunch with a corrected prompt if the error is in the instruction
• Fork (fork_session: true) if you want to try a different approach without losing context
• Escalate to the user if the error is outside your control (permissions, network, missing dependencies)

Reporting results

When a session completes:

1. Read the full result with claude_output(session, full: true)
2. Summarize the changes made to the user
3. Mention the files modified/created
4. Flag any issues encountered or remaining TODOs

---

7. Anti-patterns

Anti-pattern	Consequence	Fix
Passing channel explicitly	Bypasses automatic routing, notifications may go to wrong bot	Let agentChannels handle routing automatically
Forgetting multi_turn: true	Unable to send follow-ups with claude_respond	Enable multi_turn except for explicit one-shots
Not checking the result of a completed session	The user doesn't know what happened	Always read claude_output and summarize
Launching too many sessions in parallel	maxSessions limit reached, sessions rejected, diluted attention	Respect the limit, prioritize, sequence if necessary
Using the agent's workdir instead of the project's	Claude Code works in the wrong directory	Always point to the target project directory
Not naming sessions	Hard to identify them in claude_sessions	Always use name in kebab-case
Auto-responding to critical questions	Decisions made without the user's approval	When in doubt, forward to the user
Ignoring wake events	Sessions stuck waiting indefinitely	Handle each wake event promptly
Not adjusting the budget	Waste (too high) or interruption (too low)	Calibrate max_budget_usd based on complexity

---

8. Quick tool reference

Tool	Usage	Key parameters
claude_launch	Launch a session	prompt, name, workdir, multi_turn, max_budget_usd
claude_sessions	List sessions	status (all/running/completed/failed)
claude_output	Read the output	session, full, lines
claude_fg	Foreground + live stream	session
claude_bg	Switch back to background	session
claude_kill	Kill a session	session
claude_respond	Send a follow-up	session, message, interrupt
claude_stats	Usage metrics	none