Async Shell

Manage background shells for parallel task execution and async agent coordination.

bash

chmod +x scripts/async_shell.sh
SCRIPT="scripts/async_shell.sh"

Run $SCRIPT help for command reference.

Scope

This skill provides:

•Background shell creation and termination
•Text input and key sending
•Screen output capture (full view and differential)

Out of scope (caller's responsibility):

•Task completion detection and waiting
•Result interpretation
•Polling strategies

Session Management

The script auto-creates a default session (async_shell) on first use. Override with:

bash

ASYNC_SHELL_SESSION=my_session $SCRIPT list

Patterns

fire_and_forget

goal: run independent task, check result when needed when: no interaction needed

bash

$SCRIPT new "your_command"              # → @N
$SCRIPT capture @N                      # check output when needed
$SCRIPT kill @N

batch_parallel

goal: run multiple independent tasks concurrently when: several unrelated tasks

bash

$SCRIPT new "task1" # → @1
$SCRIPT new "task2" # → @2
$SCRIPT new "task3" # → @3
# poll for completion
$SCRIPT capture-diff @1
$SCRIPT capture-diff @2
$SCRIPT capture-diff @3
$SCRIPT kill @1 && $SCRIPT kill @2 && $SCRIPT kill @3

interactive_agent

goal: coordinate with another Claude instance when: need fresh perspective, objective review, pair programming

bash

$SCRIPT new "bash"                          # → @N
$SCRIPT type @N "claude" && $SCRIPT submit @N
$SCRIPT capture @N                          # wait for prompt
$SCRIPT type @N "<message>" && $SCRIPT submit @N
$SCRIPT capture @N                          # read response
$SCRIPT kill @N

note: provide complete context in message; agent has no access to your conversation

parallel_agents

goal: multiple agents working concurrently when: need multiple independent perspectives or parallel subtasks

bash

$SCRIPT new "bash" # → @1
$SCRIPT new "bash" # → @2

$SCRIPT type @1 "claude" && $SCRIPT submit @1
$SCRIPT type @2 "claude" && $SCRIPT submit @2

# send tasks
$SCRIPT type @1 "<task A>" && $SCRIPT submit @1
$SCRIPT type @2 "<task B>" && $SCRIPT submit @2

# collect results
$SCRIPT capture @1
$SCRIPT capture @2

$SCRIPT kill @1 && $SCRIPT kill @2

Screen Operations

capture - View current screen

View the current screen state. For one-shot checks and interactive sessions.

bash

$SCRIPT capture @N              # visible screen with line numbers
$SCRIPT capture @N -h 100       # last 100 lines with line numbers

capture-diff - Monitor for changes

Detect and show changes since last capture-diff call. For polling loops. Uses unified diff format (-/+ prefixes). Returns (no change) when nothing happened.

bash

$SCRIPT capture-diff @N         # diff since last check

Output patterns:

•(initial) + full content: first call, baseline established
•(no change): no activity since last check
•(output detected, screen unchanged): activity detected but screen returned to same state
•Unified diff: content changed ( = context, - = removed, + = added)

When to use which:

•capture: view current state, interactive sessions, reading responses
•capture-diff: polling for completion, monitoring background tasks

Basic Operations

bash

$SCRIPT new "bash"              # create shell → @N
$SCRIPT list                    # list shells
$SCRIPT type @N "<text>"        # type text (no Enter)
$SCRIPT type @N "<text>" -s     # type text and submit (auto-Enter)
$SCRIPT submit @N               # send Enter
$SCRIPT capture @N              # view current screen
$SCRIPT capture @N -h 100       # last 100 lines
$SCRIPT capture-diff @N         # diff since last check
$SCRIPT kill @N                 # close shell
$SCRIPT current                 # get current shell ID

Chained operations:

bash

# Type then capture output
$SCRIPT type @N "ls -la" -s && $SCRIPT capture @N

# Type with menu selection
$SCRIPT type @N "1" && $SCRIPT capture @N

Important: Use -s flag only for commands that require Enter. For single-character menu inputs (e.g., 1, 2, q, y), omit -s as these accept input immediately.

Notes

•
When to use bash:
- •Use new "bash" for interactive sessions (multiple commands, cd, export, loops, pipes)
- •Use new "command" for single commands (e.g., npm test, make build)
- •Use new "VAR=val command" for environment variables (e.g., ENV=prod npm start)
•Completion detection: Poll with capture-diff (recommended) or check with capture
•capture: Returns visible screen with line numbers. -h N gets last N lines
•capture-diff: Returns unified diff since last check. Detects all activity via timestamps; (no change) is reliable
•submit: Sends Enter only, no capture

Implementation

Script: scripts/async_shell.sh Claude CLI patterns: references/cli--claude.md