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

```bash theme={null}
ao status [options]
```

## Options

<ParamField path="-p, --project" type="string">
  Filter by project ID
</ParamField>

<ParamField path="--json" type="flag">
  Output as JSON for scripting
</ParamField>

## Basic Usage

```bash theme={null}
# 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

```bash theme={null}
$ 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

<ParamField path="✓" type="icon">
  All CI checks passed
</ParamField>

<ParamField path="✗" type="icon">
  CI checks failed
</ParamField>

<ParamField path="⏱" type="icon">
  CI checks pending/running
</ParamField>

<ParamField path="-" type="icon">
  No CI status (no PR or checks not configured)
</ParamField>

### Review Decision Icons

<ParamField path="✓" type="icon">
  Approved
</ParamField>

<ParamField path="⚠" type="icon">
  Changes requested
</ParamField>

<ParamField path="-" type="icon">
  No review yet or no PR
</ParamField>

### Activity States

<ParamField path="active" type="state">
  Agent is currently processing (prompt visible, spinner showing)
</ParamField>

<ParamField path="idle" type="state">
  Agent is waiting for user input (prompt hidden)
</ParamField>

<ParamField path="working" type="state">
  Agent is executing tools or commands
</ParamField>

<Note>
  Activity state is detected by analyzing the terminal output using agent-specific patterns.
</Note>

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

```bash theme={null}
ao status --json
```

### JSON Schema

```json theme={null}
[
  {
    "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

<ParamField path="name" type="string">
  Session ID
</ParamField>

<ParamField path="branch" type="string | null">
  Current git branch
</ParamField>

<ParamField path="status" type="string | null">
  Session status (working, idle, done, killed)
</ParamField>

<ParamField path="summary" type="string | null">
  User-provided or tracker-derived summary
</ParamField>

<ParamField path="claudeSummary" type="string | null">
  Agent-generated summary via introspection
</ParamField>

<ParamField path="pr" type="string | null">
  Pull request URL
</ParamField>

<ParamField path="prNumber" type="number | null">
  Pull request number
</ParamField>

<ParamField path="issue" type="string | null">
  Issue identifier
</ParamField>

<ParamField path="lastActivity" type="string">
  Human-readable time since last activity
</ParamField>

<ParamField path="project" type="string">
  Project ID
</ParamField>

<ParamField path="ciStatus" type="'success' | 'failure' | 'pending' | null">
  CI pipeline status
</ParamField>

<ParamField path="reviewDecision" type="'approved' | 'changes_requested' | null">
  Code review decision
</ParamField>

<ParamField path="pendingThreads" type="number | null">
  Number of unresolved review threads
</ParamField>

<ParamField path="activity" type="'active' | 'idle' | 'working' | null">
  Current agent activity state
</ParamField>

## Filtering

### By Project

```bash theme={null}
# Show only sessions for my-project
ao status --project my-project
```

### Combining with Shell Tools

```bash theme={null}
# 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

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

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

```typescript theme={null}
const introspection = await agent.getSessionInfo(session);
console.log(introspection.summary);
```

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

## Fallback Mode

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

```bash theme={null}
$ 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)
```

<Warning>
  Fallback mode has limited information. Create a config with `ao init` for full status reporting.
</Warning>

## Common Issues

### No Config Found

```bash theme={null}
No config found. Run `ao init` first.
```

**Solution**: Create a configuration:

```bash theme={null}
ao init
```

### Unknown Project

```bash theme={null}
Unknown project: my-project
```

**Solution**: Use a valid project ID:

```bash theme={null}
ao status --project valid-project
```

### No Sessions

```bash theme={null}
agent-orchestrator
  (no active sessions)

  0 active sessions across 1 project
```

**Solution**: Spawn some sessions:

```bash theme={null}
ao spawn my-project INT-1234
```

## Examples

### Monitor All Projects

```bash theme={null}
# Show all sessions
ao status
```

### Check Specific Project

```bash theme={null}
# Filter by project
ao status --project my-project
```

### Watch Status (Poll)

```bash theme={null}
# Refresh every 5 seconds
watch -n 5 ao status
```

### Find Failing Sessions

```bash theme={null}
# Sessions with failing CI
ao status --json | jq '.[] | select(.ciStatus == "failure")'
```

### List Stale Sessions

```bash theme={null}
# Sessions inactive for over 1 hour
ao status --json | jq '.[] | select(.lastActivity | test("[0-9]+h"))'
```

### Export Status

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Session Management" icon="terminal" href="/cli/session">
    List, kill, and cleanup sessions
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/cli/send">
    Interact with active sessions
  </Card>

  <Card title="Dashboard" icon="browser" href="/cli/dashboard">
    View status in the web interface
  </Card>
</CardGroup>


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