ao session

Manage agent sessions with ls, kill, cleanup, and restore commands

The session command provides granular control over agent sessions, including listing, terminating, cleaning up completed work, and restoring crashed sessions.

Overview

Session management commands:

ao session ls          # List all sessions
ao session kill        # Kill a session and remove worktree
ao session cleanup     # Kill sessions where PR is merged or issue is closed
ao session restore     # Restore a terminated/crashed session

ao session ls

List all sessions with branch and activity information.

Syntax

ao session ls [options]

Options

-p, --project · string

Filter by project ID

Basic Usage

# List all sessions
ao session ls

# List sessions for a specific project
ao session ls --project my-project

Output Example

$ ao session ls

agent-orchestrator:
  ao-int-1234  (2m)  int-1234-fix-errors  [working]  https://github.com/owner/repo/pull/156
  ao-int-1235  (15m)  int-1235-add-tests  [idle]
  ao-int-1236  (1h)  int-1236-refactor  [working]

my-app:
  ma-int-456  (5m)  int-456-ui-update  [active]  https://github.com/owner/my-app/pull/89

Field Descriptions

• Session ID - Session name (green)
• Age - Time since last activity (dim)
• Branch - Current git branch (cyan)
• Status - Session status in brackets (dim)
• PR URL - Pull request link if created (blue)

The branch shown is the live branch from the worktree, not the cached value. If the agent switched branches, you’ll see the updated branch name.

ao session kill

Kill a session and remove its worktree.

Syntax

ao session kill <session>

Arguments

session · string · required

Session name to kill

Basic Usage

# Kill a session
ao session kill ao-int-1234

What Gets Removed

1. Runtime Session - tmux session is killed
2. Worktree - Git worktree is removed
3. Session Metadata - Session file is updated (status set to “killed”)

This is a destructive operation. Any uncommitted changes in the worktree will be lost.

Output Example

$ ao session kill ao-int-1234

Session ao-int-1234 killed.

Before Killing

Check if there are uncommitted changes:

# Find the worktree path
ao status --json | jq -r '.[] | select(.name=="ao-int-1234") | .workspacePath'

# Check git status
cd <worktree-path>
git status

ao session cleanup

Automatically kill sessions where the PR is merged or the issue is closed.

Syntax

ao session cleanup [options]

Options

-p, --project · string

Filter by project ID

--dry-run · flag

Show what would be cleaned up without doing it

Basic Usage

# Cleanup all completed sessions
ao session cleanup

# Cleanup for a specific project
ao session cleanup --project my-project

# Preview cleanup without executing
ao session cleanup --dry-run

Cleanup Criteria

A session is considered completed if any of these are true:

1. PR Merged - Pull request state is “merged”
2. Issue Closed - Issue state is “closed” in the tracker
3. Runtime Dead - tmux session no longer exists

Sessions with status “killed”, “done”, or “exited” are skipped. The cleanup only targets active sessions that have completed work.

Dry Run Example

$ ao session cleanup --dry-run

Checking for completed sessions...

  Would kill ao-int-1234
  Would kill ao-int-1235

Dry run complete. 2 sessions would be cleaned.

Actual Cleanup Example

$ ao session cleanup

Checking for completed sessions...

  Cleaned: ao-int-1234
  Cleaned: ao-int-1235

Cleanup complete. 2 sessions cleaned.

Error Handling

If cleanup fails for some sessions:

  Cleaned: ao-int-1234
  Error cleaning ao-int-1235: Worktree not found

Cleanup complete. 1 session cleaned.

Run cleanup regularly to free disk space and keep your worktree directory tidy:

# Add to cron or run manually
ao session cleanup --dry-run

ao session restore

Restore a terminated or crashed session in-place.

Syntax

ao session restore <session>

Arguments

session · string · required

Session name to restore

When to Use Restore

Use restore when:

• tmux session crashed or was accidentally killed
• Terminal disconnected and session was lost
• Machine rebooted with sessions still registered

Restore recreates the runtime session (tmux) while preserving the workspace and session metadata. It’s like “respawning” without creating a new worktree.

Basic Usage

# Restore a crashed session
ao session restore ao-int-1234

Output Example

$ ao session restore ao-int-1234

Session ao-int-1234 restored.
  Worktree: ~/.worktrees/my-project-int-1234
  Branch:   int-1234-fix-errors
  Attach:   tmux attach -t ao-int-1234

What Happens During Restore

1. Validation - Checks if session can be restored
2. Workspace Check - Verifies worktree still exists
3. Runtime Recreation - Creates new tmux session
4. Agent Relaunch - Starts the agent in the existing workspace
5. Metadata Update - Updates session status to “working”

Restore Errors

Session Not Restorable

Cannot restore: Session is still running

Solution: Kill the session first if you want to restart it:

ao session kill ao-int-1234
ao spawn my-project INT-1234  # Create fresh session

Workspace Missing

Workspace missing: ~/.worktrees/my-project-int-1234

Solution: The worktree was deleted. Create a new session:

ao spawn my-project INT-1234

Restore only works if the worktree still exists. If you deleted the worktree, you must create a new session instead.

Common Issues

No Config Found

Error: No agent-orchestrator.yaml found

Solution: Create a configuration:

ao init

Unknown Project

Unknown project: my-project

Solution: Use a valid project ID:

ao session ls --project valid-project

Session Not Found

Failed to kill session ao-int-1234: Session not found

Solution: List sessions to find the correct name:

ao session ls

Examples

List All Sessions

# Show all active sessions
ao session ls

List Filtered Sessions

# Show sessions for a specific project
ao session ls --project my-project

Kill Session

# Terminate and remove worktree
ao session kill ao-int-1234

Safe Cleanup

# Preview cleanup
ao session cleanup --dry-run

# Execute if safe
ao session cleanup

Restore Workflow

# Machine rebooted, sessions lost
ao session ls  # Shows sessions but can't attach

# Restore a specific session
ao session restore ao-int-1234

# Attach
tmux attach -t ao-int-1234

Batch Kill

# Kill all sessions for a project (shell script)
for session in $(ao session ls --project my-project | grep my-project | awk '{print $1}'); do
  ao session kill $session
done

Cleanup Script

#!/bin/bash
# cleanup-old-sessions.sh

# Preview
ao session cleanup --dry-run

# Ask for confirmation
read -p "Proceed with cleanup? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
  ao session cleanup
fi

Exit Codes

• 0 - Success
• 1 - Error (session not found, invalid project, restore failed)

Next Steps

Status

Monitor session activity and PR status

Send Messages

Interact with active sessions

Spawn

Create new sessions