Skip to main content
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

StatusMeaning
spawningSession is being created
workingAgent is actively coding
pr_openPR created, waiting for CI/review
ci_failedCI checks failed
review_pendingWaiting for code review
changes_requestedReviewers requested changes
approvedPR approved by reviewers
mergeableApproved + CI green, ready to merge
mergedPR merged, session complete
needs_inputAgent is waiting for human input
stuckAgent inactive for too long
erroredAgent encountered an error
killedSession 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

StateMeaning
activeAgent is thinking/writing code
readyAgent finished, waiting for input
idleNo activity for >5 minutes
waiting_inputAgent is asking a question
blockedAgent hit an error
exitedAgent 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

1

Wait for idle

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

Clear partial input

Sends Ctrl+U to clear any partial command
3

Send message

Injects the message into the tmux session
4

Press Enter

Automatically submits the message
5

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:
  1. Kills the tmux session
  2. Removes the git worktree
  3. Updates session status to killed
  4. 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:
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";

​
Restoring Sessions

Restore a crashed or terminated session in-place: 
ao session restore fe-1
This:
  1. Verifies the worktree still exists
  2. Checks that the session is restorable (not merged)
  3. Creates a new tmux session
  4. Relaunches the agent in the same workspace
  5. 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'

​
Next Steps

Auto-Reactions

Automate CI failure handling and review responses

Multi-Project Setup

Manage multiple repositories simultaneously

Build docs developers (and LLMs) love

Get started for freeTalk to us