Managing Sessions

List active sessions, attach to terminals, send messages to agents, and clean up completed work

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

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:

PR Merged

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";

Issue Closed

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";

Runtime Dead

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:

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