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 < sessio n > [message...] [options]
Arguments Session name to send the message to
Message text (space-separated words)
You must provide either a message argument or the --file option.
Options Send contents of a file instead of a message
Don’t wait for session to become idle before sending
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:
Session Lookup - Resolves session name to tmux targetBusy Detection - Checks if agent is currently processingWait for Idle - Polls every 5 seconds until agent is idleClear Input - Clears any partial input (Ctrl+U)Send Message - Injects text into the tmux sessionSubmit - Sends Enter to submit the messageVerify 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 inputWorking - 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:
Wait 2 seconds
Send Enter again
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: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: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 successfully1 - 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
