AI Agent Integration

allman is designed as a CLI that AI agents can drive directly. Every command supports --json for structured output, and allman listen streams real-time events as NDJSON.

Agent workflow

A typical agent loop looks like:

# 1. Check for new messages
allman inbox --json

# 2. Read conversation context
allman messages jamie-rivera --limit 10 --json

# 3. Draft and send a reply
allman send jamie-rivera "Thanks for the update! I'll review the deck today."

Real-time event streaming

For continuous monitoring, pipe allman listen to your agent:

allman listen --json | while read -r event; do
  # Parse the JSON event and decide what to do
  echo "$event" | your-agent-handler
done

Events include message.received, message.sent, typing, reaction, and read_receipt.

Inbox polling

allman inbox uses a watermark so each call only returns messages you haven’t seen:

# First call: returns all messages from the last 24h
allman inbox --json

# Subsequent calls: only new messages since last check
allman inbox --json

# Don't advance the watermark (peek without consuming)
allman inbox --json --no-mark

Pre-send safety

allman send automatically checks for new inbound messages before sending. If the contact sent new messages since your last reply, the send is aborted and the new messages are printed. This prevents agents from sending replies without context.

To handle this in an agent:

# Send returns exit code 1 if aborted
if ! allman send jamie-rivera "$reply" 2>/dev/null; then
  # Re-read the conversation and reconsider
  allman messages jamie-rivera --limit 5 --json
fi

Rate limiting

Built-in rate limiting prevents agents from sending too fast:

• Default: 3000ms minimum between sends per account
• Configurable in .allman/{profileId}/config.json
• State persists across process restarts

You don’t need to implement your own rate limiting — allman handles it.

Search

Find contacts programmatically:

# Fuzzy search by name
allman search "jamie" --json

# Returns confidence scores (100 = exact match)

Full-text message search

Search across all stored messages:

allman grep "project proposal" --json
allman grep "contract" --since 3mo --json