> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# ao send

> Send messages to running agent sessions with busy detection and retry

The `send` command allows you to send text messages or files to running agent sessions. It includes smart busy detection, automatic retry, and delivery confirmation.

## Syntax

```bash theme={null}
ao send <session> [message...] [options]
```

## Arguments

<ParamField path="session" type="string" required>
  Session name to send the message to
</ParamField>

<ParamField path="message" type="string[]" optional>
  Message text (space-separated words)
</ParamField>

<Note>
  You must provide either a message argument or the `--file` option.
</Note>

## Options

<ParamField path="-f, --file" type="string">
  Send contents of a file instead of a message
</ParamField>

<ParamField path="--no-wait" type="flag">
  Don't wait for session to become idle before sending
</ParamField>

<ParamField path="--timeout" type="number" default="600">
  Max seconds to wait for idle (default: 600)
</ParamField>

## Basic Usage

```bash theme={null}
# Send a simple message
ao send ao-int-1234 "fix the type errors"

# Send a multi-word message
ao send ao-int-1234 Add tests for the validation module

# Send a file
ao send ao-int-1234 --file instructions.txt

# Send immediately without waiting
ao send ao-int-1234 --no-wait "urgent: revert last commit"

# Wait up to 5 minutes
ao send ao-int-1234 --timeout 300 "run the test suite"
```

## How It Works

The send command follows this workflow:

1. **Session Lookup** - Resolves session name to tmux target
2. **Busy Detection** - Checks if agent is currently processing
3. **Wait for Idle** - Polls every 5 seconds until agent is idle
4. **Clear Input** - Clears any partial input (`Ctrl+U`)
5. **Send Message** - Injects text into the tmux session
6. **Submit** - Sends `Enter` to submit the message
7. **Verify Delivery** - Confirms agent received and is processing

<Tip>
  The command uses agent-specific patterns to detect activity. For Claude Code, it looks for the prompt and spinner.
</Tip>

## Busy Detection

Before sending, the command checks if the agent is busy:

```bash theme={null}
$ ao send ao-int-1234 "run tests"

Waiting for ao-int-1234 to become idle...
```

Activity states:

* **Active** - Agent is processing (prompt visible, spinner)
* **Idle** - Agent is waiting for input
* **Working** - Agent is executing tools

The command waits for the agent to reach "idle" before sending.

<Note>
  Busy detection prevents your message from interrupting ongoing work or being lost.
</Note>

## Delivery Confirmation

After sending, the command verifies delivery:

```bash theme={null}
✓ Message sent and processing
```

Or if the agent is busy:

```bash theme={null}
✓ Message queued (session finishing previous task)
```

Or if delivery can't be confirmed:

```bash theme={null}
⚠ Message sent — could not confirm it was received
```

### Retry Logic

If the message isn't acknowledged:

1. Wait 2 seconds
2. Send `Enter` again
3. Repeat up to 3 times

This handles cases where the agent didn't see the message the first time.

## Sending Files

Use `--file` to send the contents of a file:

```bash theme={null}
# Send instructions from a file
ao send ao-int-1234 --file instructions.txt

# Send code review feedback
ao send ao-int-1234 --file review-comments.md
```

The entire file content is sent as a single message.

<Warning>
  Large files may exceed the agent's input limit. Keep files under a few thousand lines.
</Warning>

## Skip Waiting

Use `--no-wait` to send immediately without checking if the agent is busy:

```bash theme={null}
# Send urgent message
ao send ao-int-1234 --no-wait "urgent: stop the deployment"
```

<Note>
  Use `--no-wait` for urgent messages where you can't afford to wait. The message may queue if the agent is busy.
</Note>

## Custom Timeout

Set a custom wait timeout:

```bash theme={null}
# Wait up to 5 minutes
ao send ao-int-1234 --timeout 300 "run the full test suite"

# Wait up to 30 seconds
ao send ao-int-1234 --timeout 30 "status update?"
```

If the timeout expires:

```bash theme={null}
⚠ Timeout waiting for idle. Sending anyway.
```

The message is sent even if the agent is still busy.

## Message Handling

### Short Messages

Short single-line messages (under 200 characters) are sent directly:

```bash theme={null}
ao send ao-int-1234 "fix the build"
```

### Long Messages

Long messages or multi-line messages are sent via tmux buffer:

```bash theme={null}
ao send ao-int-1234 "This is a very long message with detailed instructions..."
```

### Multi-Line Messages

Messages with newlines:

```bash theme={null}
ao send ao-int-1234 "First line
Second line
Third line"
```

<Tip>
  Use `--file` for complex multi-line messages to preserve formatting:

  ```bash theme={null}
  cat > message.txt << EOF
  Please:
  1. Fix the type errors
  2. Add tests
  3. Update the docs
  EOF

  ao send ao-int-1234 --file message.txt
  ```
</Tip>

## Common Issues

### Session Does Not Exist

```bash theme={null}
Session 'ao-int-1234' does not exist
```

**Solution**: Check the session name:

```bash theme={null}
ao session ls
```

### No Message Provided

```bash theme={null}
No message provided
```

**Solution**: Provide a message or use `--file`:

```bash theme={null}
ao send ao-int-1234 "fix the issue"
# or
ao send ao-int-1234 --file message.txt
```

### Cannot Read File

```bash theme={null}
Cannot read file: instructions.txt (ENOENT: no such file or directory)
```

**Solution**: Verify the file exists:

```bash theme={null}
ls -l instructions.txt
```

### Timeout Waiting

```bash theme={null}
⚠ Timeout waiting for idle. Sending anyway.
```

**Solution**: The agent is busy for longer than expected. Options:

* Increase timeout: `--timeout 1200` (20 minutes)
* Send anyway with `--no-wait`
* Check if agent is stuck: `tmux attach -t ao-int-1234`

### Message Not Confirmed

```bash theme={null}
⚠ Message sent — could not confirm it was received
```

**Solution**: The agent didn't acknowledge the message. Check manually:

```bash theme={null}
tmux attach -t ao-int-1234
```

The message may still be visible in the terminal history.

## Examples

### Simple Message

```bash theme={null}
# Ask for status
ao send ao-int-1234 "what's the current status?"
```

### Follow-Up Instruction

```bash theme={null}
# After reviewing agent work
ao send ao-int-1234 "Good progress! Now add unit tests."
```

### Send Review Feedback

```bash theme={null}
# Create feedback file
cat > feedback.md << EOF
Changes look good overall. A few suggestions:

1. Add error handling in line 45
2. Extract the validation logic to a helper
3. Add JSDoc comments for the new functions
EOF

# Send to agent
ao send ao-int-1234 --file feedback.md
```

### Urgent Message

```bash theme={null}
# Send immediately without waiting
ao send ao-int-1234 --no-wait "URGENT: revert the last commit"
```

### Batch Messages

```bash theme={null}
# Send to multiple sessions
for session in $(ao session ls | grep ma- | awk '{print $1}'); do
  ao send $session "please run pnpm typecheck"
done
```

### Interactive Script

```bash theme={null}
#!/bin/bash
# send-to-session.sh

SESSION=$1
shift
MESSAGE="$*"

if [ -z "$MESSAGE" ]; then
  echo "Usage: $0 <session> <message>"
  exit 1
fi

ao send "$SESSION" "$MESSAGE"
```

### Scripted Workflow

```bash theme={null}
#!/bin/bash
# review-and-send.sh

SESSION="ao-int-1234"

# Check PR status
PR=$(ao status --json | jq -r ".[] | select(.name==\"$SESSION\") | .prNumber")

if [ "$PR" != "null" ]; then
  # Fetch review comments
  gh pr view $PR --json reviewThreads > review.json
  
  # Send to agent
  ao send $SESSION --file review.json
fi
```

## Exit Codes

* `0` - Message sent successfully
* `1` - Error (session not found, no message, file not found)

## Next Steps

<CardGroup cols={2}>
  <Card title="Status" icon="chart-line" href="/cli/status">
    Check if your message was processed
  </Card>

  <Card title="Session Management" icon="terminal" href="/cli/session">
    List and manage sessions
  </Card>

  <Card title="Dashboard" icon="browser" href="/cli/dashboard">
    Monitor sessions in real-time
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.