Quick Start

Launch the TUI

aoe

This opens the dashboard. You’ll see an empty session list on first run.

Create Your First Session

From the TUI: Press n to open the new session dialog. Fill in the path to your project (or leave it as . for the current directory) and press Enter.

From the CLI:

aoe add /path/to/project

The session appears in the dashboard with status Idle.

Attach to a Session

Select a session and press Enter to attach. You’re now inside a tmux session running your AI agent (Claude Code by default).

To return to the TUI, press Ctrl+b d (the standard tmux detach shortcut).

Use the Terminal View

Press t to toggle between Agent View and Terminal View. Each agent session has a paired shell terminal where you can run builds, tests, and git commands without interrupting the agent.

Review Changes with Diff View

Press D to open the diff view. This shows changes between your working directory and the base branch. Navigate files with j/k, press e to edit, and Esc to close.

Create a Worktree Session

To work on a new branch with its own directory:

# CLI
aoe add . -w feat/my-feature -b

# TUI: press n, fill in the worktree branch field

This creates a new git branch, a worktree directory, and a session pointing at it. When you delete the session, AoE offers to clean up the worktree too.

Create a Sandboxed Session

To run an agent inside a Docker container:

aoe add --sandbox .

In the TUI, toggle the sandbox checkbox when creating a session. The agent runs in an isolated container with your project mounted at /workspace and authentication credentials shared via persistent Docker volumes.

Requires Docker to be installed.

Choose a Different Agent

By default, AoE uses Claude Code. To use a different tool:

aoe add -c opencode .   # or any other supported agent

In the TUI, select the tool from the dropdown in the new session dialog.

TUI Keyboard Reference

KeyAction
nNew session
EnterAttach to session
dDelete session
tToggle Agent/Terminal view
DOpen diff view
/Search sessions
?Show help
qQuit
Ctrl+b dDetach from tmux session

Use the Web Dashboard (experimental)

The web dashboard is included in release binaries and the install script but not yet in the Homebrew formula. If you installed via brew install aoe, see the installation docs for alternatives.

Prefer a browser? Run aoe serve to start the web dashboard:

aoe serve                         # localhost only
aoe serve --host 0.0.0.0          # accessible from other devices (use with VPN)
aoe serve --daemon                # run in background

Open the printed URL in any browser — your phone, tablet, or another computer. You get the same session list, live terminal streaming, and session controls. Install it as a PWA for an app-like experience.

See the Web Dashboard Guide for details.

Next Steps