Agent Sessions
Relevant source files
The following files were used as context for generating this wiki page:
Agent Sessions represent the active, PTY-backed running environments for coding agents within a Linux Archductor workspace. They facilitate real-time interaction between the user and various AI-driven tools, such as Codex, Claude Code, and Cursor, as well as standard shell primitives.
Sessions are part of the "Running Environment" of a workspace, allowing multiple agent instances to run in parallel on the same codebase using isolated Git worktrees and stable port blocks. Sources: claude/CLAUDE.md:28-44, README.md:16-25
Architecture and Components
Agent Sessions are architected using a decoupled model where the core logic handles PTY (Pseudo-Terminal) interaction and parsing, while the GTK application or CLI provides the user interface.
Session Kinds
The system supports several types of sessions, defined by the SessionKind enumeration:
- Shell: Standard interactive terminal access.
- Codex: AI agent optimized for OpenAI Codex interaction.
- Claude: AI agent for Anthropic Claude Code.
- Cursor: Integration with the Cursor editor/agent.
Sources: crates/gtk-app/src/session_surface.rs:59-64, crates/cli/src/main.rs:253-257
Key Data Structures
| Structure | Description | Source |
|---|---|---|
ProcessRecord | Database record tracking session PID, status, and log paths. | crates/gtk-app/src/session_surface.rs:61 |
SessionHarnessOptions | Configuration for agent behavior (plan mode, reasoning, etc.). | crates/gtk-app/src/session_surface.rs:63 |
SessionEvent | Typed event representing a discrete action (tool call, user input, agent reply). | crates/core/tests/session_event_model.rs:11 |
ArchcarBridge | Async bridge facilitating communication between the GTK UI and background sessions. | crates/gtk-app/src/session_surface.rs:115 |
Session Lifecycle and State Machine
Sessions follow a strict state machine to manage the transition between starting, receiving input, and streaming output. This state is tracked by the SessionStateMachine.
This diagram illustrates the valid transitions within an agent's runtime lifecycle.
Sources: crates/core/tests/session_event_model.rs:188-237
State Definitions
- Starting: The process is being spawned by the
Archcarserver. - Running: The agent is active but not currently producing output.
- Streaming: The agent is actively sending text or data chunks.
- ToolRunning: The agent has invoked a local tool (e.g.,
cargo test) and is waiting for execution to complete. - WaitingForInput: The agent is idle and ready for the next user prompt.
- Interrupted/Failed: Terminal states resulting from manual stops or system errors.
Sources: crates/core/tests/session_event_model.rs:188-237
Data Pipeline and Output Parsing
Because agent sessions are PTY-backed, raw output often contains ANSI escape codes and TUI (Text User Interface) formatting. The codex_tui module is responsible for parsing this raw stream into structured CodexTranscriptEvent items.
Parsing Workflow
The parsing logic identifies specific markers in the agent's output to extract:
- Tool Calls: Identified by namespaces like
functions.exec_commandorweb.run. - Skill Announcements: Noted by "Using [skill] to [message]" patterns.
- File Changes: Parsing diff-like blocks into
Added,Edited, orDeletedactions with line numbers. - Context Usage: Extracting token fraction and percentage usage from the TUI footer.
Sources: crates/core/src/codex_tui.rs:150-200, crates/core/src/codex_tui.rs:480-550
The flow of raw terminal data being transformed into high-level UI components.
Sources: crates/core/src/codex_tui.rs:210-250, crates/gtk-app/src/session_surface.rs:1250-1300
GTK User Interface Integration
The session_surface.rs module provides the agent_session_panel, which serves as the primary interaction point in the GTK application. Sources: crates/gtk-app/src/session_surface.rs:114
Components of the Session Panel
- Composer: A text view for user input that handles multi-line prompts and
Ctrl+Enterto send. It includes a "Thinking" menu to set reasoning levels. - Transcript: A scrollable area that renders messages in bubbles and expands tool/skill events into interactive "chips".
- Provider Selector: Allows switching between Codex and Claude, persisting the choice per-repository.
- Status Indicators: Shows real-time "Working" timers and token usage percentages.
Sources: crates/gtk-app/src/session_surface.rs:136-220, crates/gtk-app/src/session_surface.rs:560-600
Staged Review Prompts
The UI allows "staging" context (like failing PR checks or review comments) directly into an agent session. These are wrapped in specific markers ([staged review prompt]) to ensure the agent processes them as technical context rather than direct user chatter. Sources: crates/gtk-app/src/session_surface.rs:1570-1580
Configuration and Settings
Session behavior is highly configurable through RepositorySettings (stored in .archductor/settings.toml).
Harness Options
Users can configure the "Harness" which builds the CLI arguments for the agent launch.
| Option | Command Flag | Description |
|---|---|---|
plan_mode | --plan | Forces the agent to create a plan before editing. |
fast_mode | --fast | Optimizes for speed over reasoning depth. |
reasoning_mode | --thinking | Sets reasoning levels (low, medium, high). |
auto_start_agent | N/A | Defines the default agent to launch in new workspaces. |
Sources: crates/core/src/settings.rs:135-155, crates/cli/src/main.rs:195-210
Summary
Agent Sessions are the core execution units of Linux Archductor. By leveraging PTY-backed harnesses and sophisticated TUI parsing, the system provides a structured, AI-assisted coding environment that remains grounded in standard Linux terminal primitives. This architecture ensures that agents can interact with local tools while providing the user with a clean, event-driven interface for reviewing and directing work.