Terminal Sessions
Persistent PTY sessions, agent attention detection, and recovery behaviour in the Implementation Plans terminal.
The plan terminal lets you run commands without leaving the app. Sessions are backed by the desktop PTY service, which records output in the local database, monitors agent activity, and integrates with voice transcription for hands-free input.
Session lifecycle
When a terminal opens, the UI component creates a PTY session and streams output through a buffered view. The component shows immediate connection status, forwards keystrokes to the PTY, and automatically retries if the session fails. Session metadata is stored in SQLite with timestamps, exit codes, working directories, and the full output log so that restarts can resume previous context.
Dependency checks
Before launching commands, the terminal checks for the presence of supported CLI tools such as claude, cursor, codex, and gemini. The same command also reports the default shell so users know which environment will run. This prevents launching into a session that cannot find the required binary.
Agent attention detection
The terminal monitors agent activity through a two-level inactivity detection system. When an agent stops producing output, the system progressively alerts you to check what has happened:
- Level 1 (30 seconds): "Agent idle - may have completed task" with yellow indicator
- Level 2 (2 minutes): "Agent requires attention - check terminal" with red indicator and desktop notification
This approach helps you track when agents have finished tasks or need guidance, without trying to guess why they stopped. Attention indicators clear automatically when new output is received.
Voice transcription and recovery
Inside the terminal modal, voice transcription can capture speech and paste it into the terminal input area. The recording hook looks up project-level transcription settings, keeps track of recording state, and streams recognised text into the active plan session.
If a PTY session disconnects, the terminal surface displays recovery controls and retries the connection with exponential backoff. Health checks continue monitoring session state and provide automatic recovery actions when connection issues are detected.