> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```bash theme={null}
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
```bash theme={null}
ao session ls [options]
```
### Options
Filter by project ID
### Basic Usage
```bash theme={null}
# List all sessions
ao session ls
# List sessions for a specific project
ao session ls --project my-project
```
### Output Example
```bash theme={null}
$ 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
```bash theme={null}
ao session kill
```
### Arguments
Session name to kill
### Basic Usage
```bash theme={null}
# 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
```bash theme={null}
$ ao session kill ao-int-1234
Session ao-int-1234 killed.
```
### Before Killing
Check if there are uncommitted changes:
```bash theme={null}
# Find the worktree path
ao status --json | jq -r '.[] | select(.name=="ao-int-1234") | .workspacePath'
# Check git status
cd
git status
```
## ao session cleanup
Automatically kill sessions where the PR is merged or the issue is closed.
### Syntax
```bash theme={null}
ao session cleanup [options]
```
### Options
Filter by project ID
Show what would be cleaned up without doing it
### Basic Usage
```bash theme={null}
# 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
```bash theme={null}
$ 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
```bash theme={null}
$ 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:
```bash theme={null}
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:
```bash theme={null}
# Add to cron or run manually
ao session cleanup --dry-run
```
## ao session restore
Restore a terminated or crashed session in-place.
### Syntax
```bash theme={null}
ao session restore
```
### Arguments
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
```bash theme={null}
# Restore a crashed session
ao session restore ao-int-1234
```
### Output Example
```bash theme={null}
$ 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
```bash theme={null}
Cannot restore: Session is still running
```
**Solution**: Kill the session first if you want to restart it:
```bash theme={null}
ao session kill ao-int-1234
ao spawn my-project INT-1234 # Create fresh session
```
#### Workspace Missing
```bash theme={null}
Workspace missing: ~/.worktrees/my-project-int-1234
```
**Solution**: The worktree was deleted. Create a new session:
```bash theme={null}
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
```bash theme={null}
Error: No agent-orchestrator.yaml found
```
**Solution**: Create a configuration:
```bash theme={null}
ao init
```
### Unknown Project
```bash theme={null}
Unknown project: my-project
```
**Solution**: Use a valid project ID:
```bash theme={null}
ao session ls --project valid-project
```
### Session Not Found
```bash theme={null}
Failed to kill session ao-int-1234: Session not found
```
**Solution**: List sessions to find the correct name:
```bash theme={null}
ao session ls
```
## Examples
### List All Sessions
```bash theme={null}
# Show all active sessions
ao session ls
```
### List Filtered Sessions
```bash theme={null}
# Show sessions for a specific project
ao session ls --project my-project
```
### Kill Session
```bash theme={null}
# Terminate and remove worktree
ao session kill ao-int-1234
```
### Safe Cleanup
```bash theme={null}
# Preview cleanup
ao session cleanup --dry-run
# Execute if safe
ao session cleanup
```
### Restore Workflow
```bash theme={null}
# 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
```bash theme={null}
# 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
```bash theme={null}
#!/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
Monitor session activity and PR status
Interact with active sessions
Create new sessions
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.