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

ao send <session> [message...] [options]

Arguments

session · string · required

Session name to send the message to

message · string[]

Message text (space-separated words)

You must provide either a message argument or the --file option.

Options

-f, --file · string

Send contents of a file instead of a message

--no-wait · flag

Don’t wait for session to become idle before sending

--timeout · number · default: "600"

Max seconds to wait for idle (default: 600)

Basic Usage

# 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

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

Busy Detection

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

$ 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.

Busy detection prevents your message from interrupting ongoing work or being lost.

Delivery Confirmation

After sending, the command verifies delivery:

✓ Message sent and processing

Or if the agent is busy:

✓ Message queued (session finishing previous task)

Or if delivery can’t be confirmed:

⚠ 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:

# 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.

Large files may exceed the agent’s input limit. Keep files under a few thousand lines.

Skip Waiting

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

# Send urgent message
ao send ao-int-1234 --no-wait "urgent: stop the deployment"

Use --no-wait for urgent messages where you can’t afford to wait. The message may queue if the agent is busy.

Custom Timeout

Set a custom wait timeout:

# 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:

⚠ 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:

ao send ao-int-1234 "fix the build"

Long Messages

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

ao send ao-int-1234 "This is a very long message with detailed instructions..."

Multi-Line Messages

Messages with newlines:

ao send ao-int-1234 "First line
Second line
Third line"

Use --file for complex multi-line messages to preserve formatting:

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

Common Issues

Session Does Not Exist

Session 'ao-int-1234' does not exist

Solution: Check the session name:

ao session ls

No Message Provided

No message provided

Solution: Provide a message or use --file:

ao send ao-int-1234 "fix the issue"
# or
ao send ao-int-1234 --file message.txt

Cannot Read File

Cannot read file: instructions.txt (ENOENT: no such file or directory)

Solution: Verify the file exists:

ls -l instructions.txt

Timeout Waiting

⚠ 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

⚠ Message sent — could not confirm it was received

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

tmux attach -t ao-int-1234

The message may still be visible in the terminal history.

Examples

Simple Message

# Ask for status
ao send ao-int-1234 "what's the current status?"

Follow-Up Instruction

# After reviewing agent work
ao send ao-int-1234 "Good progress! Now add unit tests."

Send Review Feedback

# 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

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

Batch Messages

# 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

#!/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

#!/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

Status

Check if your message was processed

Session Management

List and manage sessions

Dashboard

Monitor sessions in real-time