ao status

View all sessions with branch, activity, PR, and CI status

The status command provides a comprehensive overview of all agent sessions, including PR state, CI status, code review status, and activity monitoring.

Syntax

ao status [options]

Options

-p, --project · string

Filter by project ID

--json · flag

Output as JSON for scripting

Basic Usage

# Show all sessions across all projects
ao status

# Show sessions for a specific project
ao status --project my-project

# Output as JSON
ao status --json

Output Format

The status table shows:

Column	Description
Session	Session ID
Branch	Git branch name
PR	Pull request number
CI	CI/CD pipeline status
Rev	Code review decision
Thr	Pending review threads
Activity	Current agent activity state
Age	Time since last activity

Example Output

$ ao status

╔════════════════════════════════════════╗
║  AGENT ORCHESTRATOR STATUS             ║
╚════════════════════════════════════════╝

agent-orchestrator
──────────────────────────────────────────────────────────────────────────
  Session        Branch                    PR    CI    Rev   Thr  Activity  Age
  ──────────────────────────────────────────────────────────────────────────
  ao-int-1234    int-1234-fix-errors      #156  ✓     ✓     0    active    2m
                 Fixing TypeScript errors
  ao-int-1235    int-1235-add-tests       #157  ⏱     -     2    idle      15m
                 Adding test coverage
  ao-int-1236    int-1236-refactor        -     -     -     -    working   1h
                 Refactoring API layer

  3 active sessions across 1 project

Status Indicators

CI Status Icons

✓ · icon

All CI checks passed

✗ · icon

CI checks failed

⏱ · icon

CI checks pending/running

- · icon

No CI status (no PR or checks not configured)

Review Decision Icons

✓ · icon

Approved

⚠ · icon

Changes requested

- · icon

No review yet or no PR

Activity States

active · state

Agent is currently processing (prompt visible, spinner showing)

idle · state

Agent is waiting for user input (prompt hidden)

working · state

Agent is executing tools or commands

Activity state is detected by analyzing the terminal output using agent-specific patterns.

Age Format

Time since last activity in human-readable format:

• 2m - 2 minutes ago
• 15m - 15 minutes ago
• 1h - 1 hour ago
• 3h - 3 hours ago
• 2d - 2 days ago

JSON Output

Use --json for scripting:

ao status --json

JSON Schema

[
  {
    "name": "ao-int-1234",
    "branch": "int-1234-fix-errors",
    "status": "working",
    "summary": "Fixing TypeScript errors",
    "claudeSummary": "Fixed 5 type errors in utils module",
    "pr": "https://github.com/owner/repo/pull/156",
    "prNumber": 156,
    "issue": "INT-1234",
    "lastActivity": "2m",
    "project": "agent-orchestrator",
    "ciStatus": "success",
    "reviewDecision": "approved",
    "pendingThreads": 0,
    "activity": "active"
  }
]

Field Descriptions

name · string

Session ID

branch · string | null

Current git branch

status · string | null

Session status (working, idle, done, killed)

summary · string | null

User-provided or tracker-derived summary

claudeSummary · string | null

Agent-generated summary via introspection

pr · string | null

Pull request URL

prNumber · number | null

Pull request number

issue · string | null

Issue identifier

lastActivity · string

Human-readable time since last activity

project · string

Project ID

ciStatus · 'success' | 'failure' | 'pending' | null

CI pipeline status

reviewDecision · 'approved' | 'changes_requested' | null

Code review decision

pendingThreads · number | null

Number of unresolved review threads

activity · 'active' | 'idle' | 'working' | null

Current agent activity state

Filtering

By Project

# Show only sessions for my-project
ao status --project my-project

Combining with Shell Tools

# Count active sessions
ao status --json | jq 'length'

# List sessions with failing CI
ao status --json | jq '.[] | select(.ciStatus == "failure") | .name'

# Show sessions older than 1 hour
ao status --json | jq '.[] | select(.lastActivity | test("[0-9]+h")) | .name'

Activity Detection

The CLI detects agent activity by:

1. Terminal Capture - Reads last 5 lines from tmux pane
2. Pattern Matching - Uses agent-specific patterns to detect state
3. Timestamp Tracking - Records tmux activity timestamp

Claude Code Patterns

For claude-code agent:

• Active: Prompt visible (e.g., claude>, spinner)
• Idle: No prompt, waiting for input
• Working: Tool execution, command output

Activity detection works best when the agent is in interactive mode. Background tasks may not update activity state.

Session Summary

The status command shows two types of summaries:

1. User Summary - From session metadata or issue description
2. Agent Summary - Extracted from agent’s conversation history

Agent summaries are fetched via agent introspection:

const introspection = await agent.getSessionInfo(session);
console.log(introspection.summary);

Agent summaries are more accurate for long-running sessions because they reflect actual work done, not just the issue description.

Fallback Mode

If no config is found, status falls back to discovering sessions from tmux:

$ ao status

No config found. Run `ao init` first.
Falling back to session discovery...

╔════════════════════════════════════════╗
║  AGENT ORCHESTRATOR STATUS             ║
╚════════════════════════════════════════╝

  3 tmux sessions found

  ao-int-1234 (2m)
     Claude: Fixing TypeScript errors in utils module
  ao-int-1235 (15m)
  ao-orchestrator (1h)

Fallback mode has limited information. Create a config with ao init for full status reporting.

Common Issues

No Config Found

No config found. Run `ao init` first.

Solution: Create a configuration:

ao init

Unknown Project

Unknown project: my-project

Solution: Use a valid project ID:

ao status --project valid-project

No Sessions

agent-orchestrator
  (no active sessions)

  0 active sessions across 1 project

Solution: Spawn some sessions:

ao spawn my-project INT-1234

Examples

Monitor All Projects

# Show all sessions
ao status

Check Specific Project

# Filter by project
ao status --project my-project

Watch Status (Poll)

# Refresh every 5 seconds
watch -n 5 ao status

Find Failing Sessions

# Sessions with failing CI
ao status --json | jq '.[] | select(.ciStatus == "failure")'

List Stale Sessions

# Sessions inactive for over 1 hour
ao status --json | jq '.[] | select(.lastActivity | test("[0-9]+h"))'

Export Status

# Save to file
ao status --json > sessions.json

# Pretty print
ao status --json | jq '.' > sessions-pretty.json

Exit Codes

• 0 - Success
• 1 - Error (invalid project ID)

Next Steps

Session Management

List, kill, and cleanup sessions

Send Messages

Interact with active sessions

Dashboard

View status in the web interface