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 Options 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 < sessio n >
Arguments Basic Usage # Kill a session ao session kill ao-int-1234
What Gets Removed
Runtime Session - tmux session is killedWorktree - Git worktree is removedSession 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-pat h > git status
ao session cleanup Automatically kill sessions where the PR is merged or the issue is closed.
Syntax ao session cleanup [options]
Options 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:
PR Merged - Pull request state is “merged”Issue Closed - Issue state is “closed” in the trackerRuntime 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 < sessio n >
Arguments 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
Validation - Checks if session can be restoredWorkspace Check - Verifies worktree still existsRuntime Recreation - Creates new tmux sessionAgent Relaunch - Starts the agent in the existing workspaceMetadata 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: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: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 - Success1 - Error (session not found, invalid project, restore failed)
Next Steps
Status Monitor session activity and PR status
Send Messages Interact with active sessions
