agent-orchestration

Category: Tools & Productivity | Uploader: deepgram | Downloads: 0 | Version: v1.0（Latest）

Use when you need to launch and drive other AI agents (Claude Code, Aider, Codex, etc.) through their terminal interfaces via wsh. Examples: "run multiple Claude Code sessions in parallel on different tasks", "feed a task to an AI agent and handle its approval prompts", "coordinate several AI agents working on subtasks of a larger project". --- > **IMPORTANT: EXECUTION CONTEXT** > This skill describes *what to do* — domain patterns and decision-making. > It does NOT describe *how* to call the API. > > 1. **If you have `wsh_*` tools** (check your toolkit for `wsh_send_input`, > `wsh_get_screen`, etc.): use them directly. Operation names in this > skill generally map to tool names (e.g., "send input" → `wsh_send_input`). > When in doubt, list your available `wsh_*` tools. > 2. **If you do NOT have `wsh_*` tools**: you are in HTTP/curl fallback mode. > **DO NOT GUESS endpoints or CLI subcommands.** > Load the full API reference first: search your workspace for > `skills/core/` and read `SKILL.md`. It contains every endpoint > with working curl examples and a bootstrap sequence. > 3. **Quick bootstrap**: `curl -sf --unix-socket ${XDG_RUNTIME_DIR:-/tmp}/wsh/default.http.sock http://localhost/health` > — if that fails: `wsh server -L agent-$$ --ephemeral &` and retry. # wsh:agent-orchestration — Driving AI Agents You can use wsh to launch and drive other AI agents — Claude Code, Aider, Codex, or any AI tool with a terminal interface. This is not science fiction. You spawn the agent in a wsh session, feed it tasks, handle its approval prompts, and review its output. You become a manager of AI workers. ## Why? - **Parallelism.** You can run 5 Claude Code sessions simultaneously, each working on a different task. - **Delegation.** Break a large project into subtasks and assign each to an agent session. - **Specialization.** Different agents have different strengths. Orchestrate the right tool for each job. - **Automation.** Unattended workflows — an a

Changelog: Source: GitHub https://github.com/deepgram/wsh

Directory Structure

Current level: skills/agent-orchestration/

📄 SKILL.md 9.9 KB

SKILL.md

---
name: agent-orchestration
description: >
  Use when you need to launch and drive other AI agents (Claude Code, Aider,
  Codex, etc.) through their terminal interfaces via wsh. Examples: "run
  multiple Claude Code sessions in parallel on different tasks", "feed a task
  to an AI agent and handle its approval prompts", "coordinate several AI
  agents working on subtasks of a larger project".
---

> **IMPORTANT: EXECUTION CONTEXT**
> This skill describes *what to do* — domain patterns and decision-making.
> It does NOT describe *how* to call the API.
>
> 1. **If you have `wsh_*` tools** (check your toolkit for `wsh_send_input`,
>    `wsh_get_screen`, etc.): use them directly. Operation names in this
>    skill generally map to tool names (e.g., "send input" → `wsh_send_input`).
>    When in doubt, list your available `wsh_*` tools.
> 2. **If you do NOT have `wsh_*` tools**: you are in HTTP/curl fallback mode.
>    **DO NOT GUESS endpoints or CLI subcommands.**
>    Load the full API reference first: search your workspace for
>    `skills/core/` and read `SKILL.md`. It contains every endpoint
>    with working curl examples and a bootstrap sequence.
> 3. **Quick bootstrap**: `curl -sf --unix-socket ${XDG_RUNTIME_DIR:-/tmp}/wsh/default.http.sock http://localhost/health`
>    — if that fails: `wsh server -L agent-$$ --ephemeral &` and retry.

# wsh:agent-orchestration — Driving AI Agents

You can use wsh to launch and drive other AI agents — Claude
Code, Aider, Codex, or any AI tool with a terminal interface.
This is not science fiction. You spawn the agent in a wsh
session, feed it tasks, handle its approval prompts, and
review its output. You become a manager of AI workers.

## Why?

- **Parallelism.** You can run 5 Claude Code sessions
  simultaneously, each working on a different task.
- **Delegation.** Break a large project into subtasks and
  assign each to an agent session.
- **Specialization.** Different agents have different
  strengths. Orchestrate the right tool for each job.
- **Automation.** Unattended workflows — an agent that
  spawns agents, reviews their work, and merges the results.

## Launching an Agent

Create a session with the agent as its command:

    create session "agent-auth" with command: claude --print "Implement user auth in src/auth.rs"

Or start a shell and launch the agent interactively:

    create session "agent-auth"
    send: claude
    wait for idle
    read screen — verify Claude Code has started
    send: Implement user authentication in src/auth.rs\n

The interactive approach gives you more control — you can
set up the environment first, then launch the agent.

## Agent Interaction Patterns

AI agents aren't like regular CLI programs. They produce
long bursts of output, pause to think, ask for approval,
and sometimes wait indefinitely for human input. You need
to recognize these states.

### The Agent Lifecycle
Most AI terminal agents follow this pattern:

    1. Startup — banner, loading, initialization
    2. Thinking — reading files, planning (may be quiet
       for seconds or minutes)
    3. Working — producing output, writing code, running
       commands
    4. Approval — asking permission before a tool use or
       destructive action
    5. Waiting — idle, expecting the next task
    6. Repeat from 2

### Detecting Agent State

**Startup:** Look for the agent's banner or welcome message.
Each agent has a recognizable one. Wait for it before
sending input.

**Thinking:** The terminal may be silent for extended
periods. This is normal — don't assume it's stuck. Use
longer idle timeouts (10-30 seconds) and poll
patiently. Look for spinner characters or progress
indicators.

**Approval prompts:** These are critical. Look for patterns
like:
- "Allow?" "Approve?" "Proceed?" "Y/n"
- "Do you want to run this command?"
- A tool call description followed by a prompt
- Highlighted or bold text asking for confirmation

**Waiting for input:** After completing a task, the agent
shows a prompt for the next instruction. Look for an
input indicator — a cursor, a `>`, or an explicit
"What would you like to do?" message.

### Idle Detection Is Tricky with Agents
Agents think. Thinking produces no output. An idle
timeout of 2 seconds will trigger constantly during
thinking phases. Use longer timeouts (10-30 seconds) and
always read the screen to distinguish "thinking" from
"waiting for input."

When re-polling, use `last_generation` or `fresh=true` to
avoid busy-loop storms where the server responds immediately
because nothing has changed since the last check.

## Feeding Tasks

Keep instructions clear and self-contained. The agent can't
ask you clarifying questions — or rather, it can, but you
need to detect and answer them programmatically.

### Good Task Instructions
Be specific. Include context the agent needs:

    send: Add input validation to the POST /users endpoint. \
    Reject requests where email is missing or malformed. \
    Return 400 with a JSON error body.\n

Not:

    send: fix the users endpoint\n

### Scoping Tasks
Prefer small, well-defined tasks over large ambiguous ones.
An agent working on "implement the entire auth system" will
make many decisions you might disagree with. An agent working
on "add bcrypt password hashing to the User model" has less
room to go sideways.

## Handling Approvals

Many agents ask for permission before taking actions. You
have three strategies:

### Auto-Approve Everything
If you trust the agent and the task is low-risk, configure
it to skip approvals:

    send: claude --dangerously-skip-permissions\n

Only do this for isolated, low-stakes work. Never for
production systems.

### Selective Approval
Read the approval prompt, decide whether to approve:

    read screen
    # See: "Run command: npm install express?"
    # Looks safe.
    send: y\n

    read screen
    # See: "Run command: rm -rf /tmp/build"
    # Inspect further before approving.

### Reject and Redirect
If the agent proposes something wrong, reject and explain:

    send: n\n
    wait, read
    send: Don't delete that directory. Use a fresh \
    build directory at /tmp/build-new instead.\n

## Reviewing Output

After the agent finishes a task, review what it did:

    read screen — see the final status
    read scrollback — see the full conversation

Look for: files changed, commands run, errors encountered,
tests passed or failed. The scrollback is your audit trail.

## Multi-Agent Coordination

The real power is running multiple agents in parallel. Each
gets its own session, its own task, its own workspace.

### The Delegation Pattern

    1. Plan — break the project into independent subtasks
    2. Spawn — create a session for each subtask
    3. Launch — start an agent in each session with its task
    4. Monitor — poll sessions, handle approvals
    5. Review — read each agent's output when it finishes
    6. Integrate — merge the results

### Monitoring Multiple Agents

Poll round-robin with short idle timeouts. You're
looking for approval prompts that need your attention:

    for each agent session:
        await idle (timeout_ms=3000)
        read screen
        if approval prompt detected:
            evaluate and respond
        if task complete:
            review output, clean up session
        if still working:
            move to next session

Agents that are thinking or working need no intervention.
Focus your attention on agents that are blocked waiting
for approval or input.

### Workspace Isolation

Give each agent its own workspace to avoid conflicts.
Agents editing the same files simultaneously will corrupt
each other's work:

    # Use git worktrees for code tasks
    send to "setup": git worktree add /tmp/agent-auth feature/auth
    send to "setup": git worktree add /tmp/agent-api feature/api

    create session "agent-auth", cwd: /tmp/agent-auth
    create session "agent-api", cwd: /tmp/agent-api

Or use separate branches, separate directories, or
separate repositories. The key principle: agents that
might touch the same files must not run in parallel
without isolation.

### Passing Results Between Agents

Agents can't talk to each other directly. Use the
filesystem as the communication channel:

    # Agent 1 produces an artifact
    agent-1 writes to /tmp/api-spec.json

    # You read it and feed it to Agent 2
    read /tmp/api-spec.json
    send to agent-2: Implement the client based on the
    API spec at /tmp/api-spec.json\n

## Pitfalls

### Don't Over-Parallelize
More agents isn't always better. Each agent consumes
resources — API rate limits, CPU, memory. And each agent
you run is one more you need to monitor. Start with 2-3
agents and scale up once you're comfortable with the
monitoring rhythm.

### Watch for Agents Talking to Each Other Accidentally
If two agents are running in the same git repo without
workspace isolation, one agent's changes (file writes,
branch switches, dependency installs) will affect the
other. This causes bizarre failures that are hard to
diagnose. Always isolate.

### Infinite Loops
An agent can get stuck — retrying a failing command,
asking itself a question, or endlessly editing a file.
If you notice an agent producing repetitive output
without progress, intervene:

    send: Stop. The current approach isn't working. \
    Try a different strategy.\n

If it persists, Ctrl+C and give it a fresh start with
clearer instructions.

### Don't Forget Cleanup
Agent sessions with worktrees, temp files, and running
processes leave debris. When the orchestration is done:
- Exit or kill all agent sessions
- Remove worktrees: `git worktree remove /tmp/agent-auth`
- Clean up temp files
- Verify the main repo is in a clean state

### Know When Not to Orchestrate
If the task requires deep understanding of a complex
system, one focused agent with good context will
outperform three agents with shallow context.
Orchestration works best when tasks are genuinely
independent and well-specified. If tasks are tightly
coupled, work them sequentially in a single session.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

agent-orchestration

Directory Structure

SKILL.md

Report

Notice