Managing Sessions

Sessions are isolated workspaces where agents work on issues. Each session has its own git worktree, tmux session, and metadata.

Listing Sessions

View all active sessions:

ao session ls

Output:

Frontend:
  fe-1  (2m ago)  feat/add-login  [working]  https://github.com/org/app/pull/42
  fe-2  (5m ago)  feat/dashboard  [pr_open]

Backend:
  api-1  (1h ago)  fix/auth-bug  [review_pending]  https://github.com/org/api/pull/15
  (no active sessions)

Each session shows:

Session ID (fe-1)
Last activity (2m ago)
Branch name (feat/add-login)
Status (working, pr_open, review_pending)
PR URL (if created)

Filter by Project

List sessions for a specific project:

ao session ls -p frontend

Session Status Codes

Status	Meaning
`spawning`	Session is being created
`working`	Agent is actively coding
`pr_open`	PR created, waiting for CI/review
`ci_failed`	CI checks failed
`review_pending`	Waiting for code review
`changes_requested`	Reviewers requested changes
`approved`	PR approved by reviewers
`mergeable`	Approved + CI green, ready to merge
`merged`	PR merged, session complete
`needs_input`	Agent is waiting for human input
`stuck`	Agent inactive for too long
`errored`	Agent encountered an error
`killed`	Session manually terminated

Comprehensive Status View

Get detailed status with PR, CI, and review info:

ao status

Output:

AGENT ORCHESTRATOR STATUS

Frontend:
  Session        Branch                  PR    CI     Rev   Thr  Activity  Age
  ─────────────────────────────────────────────────────────────────────────────
  fe-1           feat/add-login          #42   ✓      ✓     0    active    2m
                 Implementing OAuth login flow with session management
  fe-2           feat/dashboard          #43   ⋯      ⋯     2    ready     5m
                 Dashboard UI components with charts

Backend:
  Session        Branch                  PR    CI     Rev   Thr  Activity  Age
  ─────────────────────────────────────────────────────────────────────────────
  api-1          fix/auth-bug            #15   ✗      △     0    active    1h
                 Fixing JWT token validation

  3 active sessions across 2 projects

Columns:

PR: PR number or - if not created
CI: ✓ passing, ✗ failing, ⋯ pending, - no checks
Rev: ✓ approved, ✗ changes requested, △ pending
Thr: Number of unresolved comment threads
Activity: active, ready, idle, waiting_input, blocked, exited
Age: Time since last activity

Activity States

State	Meaning
`active`	Agent is thinking/writing code
`ready`	Agent finished, waiting for input
`idle`	No activity for >5 minutes
`waiting_input`	Agent is asking a question
`blocked`	Agent hit an error
`exited`	Agent process terminated

JSON Output

Get machine-readable output for scripting:

ao status --json

[
  {
    "name": "fe-1",
    "branch": "feat/add-login",
    "status": "working",
    "prNumber": 42,
    "ciStatus": "success",
    "reviewDecision": "approved",
    "pendingThreads": 0,
    "activity": "active",
    "lastActivity": "2m ago"
  }
]

Attaching to Sessions

Attach to a session’s terminal to watch the agent work:

tmux attach -t fe-1

Or use the open command:

ao open fe-1

Detach without killing: Press Ctrl+B, then D

Open Multiple Sessions

Open all sessions for a project:

ao open frontend

Open all sessions across all projects:

ao open all

Open in New Window

ao open fe-1 --new-window

This uses the Terminal plugin (default: iterm2) to create terminal tabs/windows.

Sending Messages

Send instructions to a running agent:

ao send fe-1 "Please address the review comments on your PR"

How It Works

Wait for idle

The command waits for the agent to become idle before sending (default: 600s timeout)

Clear partial input

Sends Ctrl+U to clear any partial command

Send message

Injects the message into the tmux session

Press Enter

Automatically submits the message

Verify delivery

Checks that the agent received and is processing the message

Send Without Waiting

Skip the idle wait:

ao send fe-1 "Your message" --no-wait

Sending while the agent is active may interrupt its current task. Use --no-wait only when necessary.

Send from File

Send long instructions from a file:

ao send fe-1 --file instructions.txt

Example instructions.txt:

The CI is failing with this error:

TypeError: Cannot read property 'id' of undefined
  at validateUser (auth.ts:42)

Please:
1. Add null checks for the user object
2. Add tests for the error case
3. Update the error message to be more descriptive

Custom Timeout

Change the idle wait timeout:

ao send fe-1 "Your message" --timeout 300  # 5 minutes

Delivery Confirmation

The command verifies delivery:

✓ Message sent and processing

Or:

✓ Message queued (session finishing previous task)

If delivery can’t be confirmed:

⚠ Message sent — could not confirm it was received

Killing Sessions

Terminate a session and remove its worktree:

ao session kill fe-1

This:

Kills the tmux session
Removes the git worktree
Updates session status to killed
Preserves metadata for audit trail

Killing a session does NOT close or delete the PR. The PR remains open on GitHub/GitLab.

When to Kill Sessions

✅ Good reasons to kill:

PR merged, work is complete
Agent is stuck and unrecoverable
Duplicate session for the same issue
Issue was closed/canceled

❌ Don’t kill if:

Agent is just slow (give it time)
CI is failing (let auto-reactions handle it)
You just want to pause (detach instead)

Automatic Cleanup

Remove completed sessions automatically:

ao session cleanup

This kills sessions where:

PR is merged
Issue is closed (in tracker)
Runtime is no longer alive

Dry run to preview:

ao session cleanup --dry-run

Output:

Checking for completed sessions...

  Would kill fe-2
  Would kill api-5

Dry run complete. 2 sessions would be cleaned.

Cleanup specific project:

ao session cleanup -p frontend

Cleanup Criteria

A session is cleaned if:

PR Merged
Issue Closed
Runtime Dead

The PR associated with the session has been merged to the default branch.Detected via SCM plugin:

const pr = await scm.detectPR(session, project);
const merged = pr && pr.state === "merged";

The issue in the tracker (GitHub Issues, Linear) is closed or done.Detected via Tracker plugin:

const issue = await tracker.getIssue(session.issueId);
const closed = issue && issue.status === "closed";

The tmux session or container is no longer running.Detected via Runtime plugin:

const alive = await runtime.isAlive(session.runtimeHandle);

Restoring Sessions

Restore a crashed or terminated session in-place:

ao session restore fe-1

This:

Verifies the worktree still exists
Checks that the session is restorable (not merged)
Creates a new tmux session
Relaunches the agent in the same workspace
Updates metadata with restore timestamp

When to restore:

tmux session crashed but worktree is intact
Agent exited unexpectedly
You manually killed tmux but want to resume

Cannot restore if:

Session status is merged (work is complete)
Worktree was deleted
Branch was deleted from the repo

Restore output:

✓ Session fe-1 restored.
  Worktree: /Users/you/.worktrees/fe-1
  Branch:   feat/add-login
  Attach:   tmux attach -t fe-1

Session Metadata

Each session stores metadata in flat files:

~/.agent-orchestrator/sessions/my-app/
  fe-1/
    id=fe-1
    projectId=frontend
    status=working
    branch=feat/add-login
    issueId=123
    pr=https://github.com/org/app/pull/42
    createdAt=2024-03-04T10:30:00Z
    lastActivityAt=2024-03-04T10:32:00Z

Metadata is:

Flat key=value format (backwards compatible)
Human-readable (edit with any text editor)
Tracked in event log (full audit trail)

Scripting Examples

Kill all merged sessions

ao session cleanup --dry-run | grep "Would kill" | awk '{print $3}' | xargs -I {} ao session kill {}

Send message to all sessions

for session in $(ao session ls --json | jq -r '.[].name'); do
  ao send $session "Please check if your PR is ready for review"
done

Monitor session status

watch -n 30 'ao status'

Get Started

Core Concepts

Configuration

Guides

Listing Sessions

Filter by Project

Session Status Codes

Comprehensive Status View

Activity States

JSON Output

Attaching to Sessions

Open Multiple Sessions

Open in New Window

Sending Messages

How It Works

Send Without Waiting

Send from File

Custom Timeout

Delivery Confirmation

Killing Sessions

When to Kill Sessions

Automatic Cleanup

Cleanup Criteria

Restoring Sessions

Session Metadata

Scripting Examples

Kill all merged sessions

Send message to all sessions

Monitor session status

Next Steps

Auto-Reactions

Multi-Project Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Documentation Index

​Listing Sessions

​Filter by Project

​Session Status Codes

​Comprehensive Status View

​Activity States

​JSON Output

​Attaching to Sessions

​Open Multiple Sessions

​Open in New Window

​Sending Messages

​How It Works

​Send Without Waiting

​Send from File

​Custom Timeout

​Delivery Confirmation

​Killing Sessions

​When to Kill Sessions

​Automatic Cleanup

​Cleanup Criteria

​Restoring Sessions

​Session Metadata

​Scripting Examples

​Kill all merged sessions

​Send message to all sessions

​Monitor session status

​Next Steps

Auto-Reactions

Multi-Project Setup

Build docs developers (and LLMs) love

Listing Sessions

Filter by Project

Session Status Codes

Comprehensive Status View

Activity States

JSON Output

Attaching to Sessions

Open Multiple Sessions

Open in New Window

Sending Messages

How It Works

Send Without Waiting

Send from File

Custom Timeout

Delivery Confirmation

Killing Sessions

When to Kill Sessions

Automatic Cleanup

Cleanup Criteria

Restoring Sessions

Session Metadata

Scripting Examples

Kill all merged sessions

Send message to all sessions

Monitor session status

Next Steps