Session Management

How sessions are tracked, matched, and managed throughout their lifecycle.

Session State Machine

Every session moves through a set of statuses. Hook events drive the changes.

SessionStart                       → idle       (waits at the coffee lounge)
UserPromptSubmit                   → prompting  (walks to a desk)
PreToolUse                         → working    (sits at the desk, charging effect)
PostToolUse                        → working    (stays working)
[timer expires]                    → approval or input
PermissionRequest                  → approval   (direct signal, more reliable)
Notification (permission prompt)   → approval   (backstop)
Stop                               → waiting    (turn finished)
[5 minutes waiting]                → idle
SessionEnd                         → ended      (offline animation)

A terminal that AASC just started shows connecting until its first hook arrives.

Status Details

idle: the robot breathes gently and goes to the coffee lounge.
prompting: the robot tilts its head and walks to a desk in its room.
working: the robot sits at a desk with a charging effect and tool-specific motion.
waiting: the robot hops in place and goes to the coffee lounge.
approval: the visor flashes yellow and the body shakes. The robot freezes in place.
input: the visor turns purple and an arm goes up. The robot freezes in place.
ended: the robot slumps and its glow fades.
connecting: the robot boots up.

The 3D view is optional and off by default. The LIVE board and the session list show the same statuses as coloured chips.

Automatic Status Changes

AASC changes some statuses on its own, so a lost hook cannot leave a card stuck.

prompting to waiting: after 30 seconds with no hook events and no terminal output. This is a prompt that never ran. Pressing Esc fires a real Stop, so it does not take this path.
waiting to idle: after 5 minutes.
approval or input to idle: after 10 minutes. A dialog the CLI itself reported as open never expires.
working to idle: after 15 minutes. This is only a safety net for a lost Stop or PostToolUse.
connecting to idle: after 30 seconds for Claude Code and Codex.
Any status to ended: when the session's process disappears without a SessionEnd, for example when you close the terminal. AASC checks every 15 seconds. You can change this with processCheckInterval.

Approval Detection

Two mechanisms tell AASC that an agent needs you.

Timeout Heuristic

When PreToolUse fires, a timer starts. Its length depends on the tool:

fast, 3 seconds: Read, Write, Edit, Grep, Glob, NotebookEdit.
user input, 3 seconds: AskUserQuestion, EnterPlanMode, ExitPlanMode.
medium, 15 seconds: WebFetch, WebSearch.
slow, 8 seconds: Bash, Task.

If PostToolUse does not arrive before the timer ends, the session moves to approval. For the user input tools it moves to input.

For slow tools, AASC first checks whether the tool's process still has child processes. If it does, the command is still running and the timer does not report an approval.

The timers are a guess. An auto-approved command that runs for a long time, such as npm install or a build, can show as approval for about 8 seconds until PostToolUse arrives.

In bypassPermissions and dontAsk mode the timers are off for tools that need approval. A real dialog is still caught by the signals below.

PermissionRequest Signal

The PermissionRequest hook fires when Claude actually asks for approval. It is registered at every density level. It overrides the timers at once and is more reliable.

At medium and high density, AASC also reads the Notification hook for a permission prompt. It uses that as a backstop while a tool call is open.

When a hook event arrives for a session AASC does not know yet, the matcher tries to link it to a terminal AASC started. It tries these steps in order, from the most certain to the least, and stops at the first match:

A resume you asked for. A pending resume for that terminal.
The terminal id. AASC puts AGENT_MANAGER_TERMINAL_ID into the environment of every terminal it starts. The hook sends it as agent_terminal_id.
The same process with a new session id. This happens after /clear or a resume.
The working directory. A SessionStart from the folder of a terminal AASC created in the last minute.
A scan of connecting terminals for a matching folder.
The process parent. AASC checks whether the agent is a child of the terminal's shell. This is the least reliable step.
Terminal adoption. If a terminal already has exactly one session and a hook arrives from it with a new id, AASC re-keys that session. This covers a lost SessionStart and avoids a second card for one terminal.

If nothing matches, AASC treats the session as one it did not launch. It makes an external card and labels it with where it runs: VS Code, JetBrains, iTerm, Warp, Kitty, Ghostty, Alacritty, WezTerm, Hyper, tmux or Terminal. On macOS and Linux, AASC also scans for running interactive claude processes every 20 seconds and shows them as external cards.

A few rules keep the matcher honest:

A process with no terminal, such as claude -p, a CI run or an MCP-started agent, never makes a card. It also never claims a terminal by id or by folder.
Subagent events, and a Stop or SessionEnd for an unknown session, are dropped. They never make a card.
Matching is a best guess. Two sessions in one folder can occasionally cross-link.

Team & Subagent Tracking

Two kinds of multi-agent work show up in the dashboard.

Agent teams. Each teammate is a session of its own. AASC links a teammate to its leader in one of two ways:

Direct linking. The CLAUDE_CODE_PARENT_SESSION_ID environment variable gives an instant link.
Folder-based detection. A SubagentStart on the parent, then a new SessionStart from a matching folder within 10 seconds.

The 3D view draws animated beams between a leader and its teammates. When every member has ended, AASC removes the team after 15 seconds.

Subagents. A subagent started with Claude Code's Agent tool runs inside the leader's process and reports through the leader's hooks. AASC follows each run from those hooks: its type, its task, its status and how many tools it used. The leader's AGENTS tab shows a live diagram and a log of what each agent did. Click a subagent card to read that subagent's conversation. Click a teammate card to switch to the teammate's session.

Session Resume

When a session has ended, click Resume in its control bar. In HISTORY, each row has a Resume button too.

AASC types a line like claude --resume 'session-id' || claude into the terminal. For Codex the line is like codex resume 'session-id' || codex.
It uses the session's old terminal if that is still open. Otherwise it opens a new terminal in the project folder.
The new SessionStart is matched to the pending resume. If the CLI does not report in within 2 minutes, the card goes back to idle.
The card keeps its title and room. Prompts from the earlier run stay in the CONVERSATION tab as earlier runs. AASC keeps up to 5.

If the old conversation cannot be resumed, a fresh agent starts in the same card. AASC never falls back to --continue, because that could pick up an unrelated conversation in the same folder.

Two related buttons are in the terminal toolbar:

Reconnect opens a new terminal for an ended session that has a stored launch command.
Restart session quits the agent and reconnects the same session in a fresh terminal. The card keeps its id, name, model, effort and permission mode, and it never shows as ended on the way.

Memory and Idle Sleep

On your computer's dashboard, the header shows how much memory your sessions hold, and each LIVE card shows its own, such as ≈ 312 MB. The figure covers a session's terminal and everything running in it: the CLI and its MCP servers.

Sleep idle sessions, in Settings, ADVANCED, is off by default. Pick a time from 15 minutes to 4 hours. A session that has been quiet that long has its terminal closed, so its CLI and MCP servers stop and free their memory. The card stays, marked Asleep. Open it and AASC resumes the conversation in a new terminal. On the phone, tap Resume.

A session does not sleep while it works or waits for your answer, while its queue has prompts armed or shells run in the background, or when it is pinned, a central, on Hands off, running over SSH or inside tmux. Only a Claude Code or Codex session that can be resumed goes to sleep.

Labels & Organization

A session has these controls:

Label. One label per session, shown as a coloured chip next to the title. The built-in labels are ONEOFF, HEAVY and IMPORTANT. You can add up to 30 of your own, each with a colour. Labels are only a tag. They live in your browser and do not sync to other devices.
Room. Rooms group sessions into frames in the session list, and into rooms in the 3D view. Pick a room in the session's control bar or in the New Session form.
Pin. Pinned sessions sort first.
Mute and Alert. Mute silences sound alerts for that session only. Alert gives you sound and visual alerts when the session needs your attention.
Share. Shows or hides the session on your other devices. See Configuration.
Hands off. Stops central sessions from steering a session. See Central Sessions.