PTY Harness & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The PTY Harness & Logging system provides the foundational infrastructure for executing parallel coding agents and shell sessions within isolated Git worktrees. It manages the lifecycle of pseudo-terminal (PTY) processes, builds complex command-line arguments for agent providers like Codex and Claude, and captures raw output for structured logging and real-time UI updates.
The system ensures that each workspace remains isolated while providing a unified interface for the GTK application and CLI to interact with running environments. This includes specialized handling for terminal transcripts, ANSI escape sequence parsing, and the extraction of structured events from raw agent output.
Sources: README.md, crates/core/src/harness.rs:1-40
Session Harness Architecture
The session harness is responsible for planning and executing various types of sessions, primarily Shell, Codex, and Claude. It translates high-level user preferences—such as plan mode, reasoning effort, and personality—into environment variables and command-line arguments specific to each agent provider.
Harness Launch Planning
A SessionHarnessLaunchPlan is generated to define how a session should start. This plan includes arguments, environment variables (like ARCHDUCTOR_SESSION_BOOTSTRAP), and metadata used for session tracking.
The logic differentiates between a fresh start and a session resume. For instance, Claude sessions generate a unique session_resume_id using a UUID v4 when starting fresh.
Sources: crates/core/src/harness.rs:7-60
Provider-Specific Configurations
Each provider has specific flags and environment requirements mapped within the harness:
| Provider | Key Arguments / Logic | Bootstrap Payload |
|---|---|---|
| Codex | --no-alt-screen, --dangerously-bypass-approvals-and-sandbox, trust level config | None (uses direct CLI flags) |
| Claude | --permission-mode, --effort, --session-id | Detailed multi-line system prompt |
| Shell | Standard shell execution | Minimal mode status |
Sources: crates/core/src/harness.rs:125-240
Terminal Logging & Transcript Processing
The project employs a multi-layered approach to logging. Raw PTY output is captured into log files on disk, while a processing pipeline sanitizes and structures this data for the UI.
Transcript Sanitization
Raw terminal output containing ANSI escape codes is processed via terminal_display_text to handle common redraw sequences and cursor movements. The system also implements "alternate-screen" restoration to ensure that TUI-based agents (like Codex) do not leave the terminal in a broken state after execution.
Sources: crates/gtk-app/src/terminal.rs:20-50, crates/gtk-app/src/session_surface.rs:1140-1160
Structured Event Extraction
For agent sessions, the logging system goes beyond raw text. It identifies specific markers in the transcript to segment the log into "Transcript Events" with assigned roles.
The roles identified during parsing include:
- System: Lifecycle events like session start/stop and checkpoints.
- User/Review: Explicit inputs sent by the user or staged review prompts.
- Agent: The prose responses from the AI.
- Tool/Skill: Specific actions performed by the agent, such as
Ran cargo testorEdited file.rs.
Sources: crates/gtk-app/src/session_surface.rs:1185-1260, crates/core/src/codex_tui.rs:110-150
Codex TUI & Screen Parsing
Because Codex operates as a terminal-based UI (TUI), the system includes specialized logic to parse "screen snapshots" captured from the PTY. This allows the application to present a chat-like interface even when the underlying process is a full-screen terminal application.
Screen Ready Detection
The system monitors the PTY screen to determine when Codex is ready for new input. It checks for the presence of the › prompt and filters out transient states like "Booting MCP server" or "Thinking".
Sources: crates/core/src/codex_tui.rs:152-175
Inline Event Parsing
The parser identifies specific tool calls and skill announcements embedded within the TUI stream. For example, patterns like functions.exec_command or Using superpowers:brainstorming are extracted as inline events.
| Event Type | Pattern | UI Representation |
|---|---|---|
| Tool Call | Calling namespace.tool_name | Compact chip with execution status |
| File Change | Edited path/to/file (+A -D) | Diff summary with expandable details |
| Context Usage | Context window: X% | Token usage progress indicator |
Sources: crates/core/src/codex_tui.rs:10-90, crates/gtk-app/src/session_surface.rs:560-650
Log Persistence and Recovery
Logs are stored in workspace-specific directories within ~/.local/state/linux-archductor/logs/.
Process Reconciliation
On startup, the system performs "Runtime Reconciliation." It inspects the process table against recorded SQLite state to identify stale sessions (e.g., if the app crashed) and marks them as exited in the database.
Sources: crates/gtk-app/src/workspace_command_center.rs:1250-1300, README.md
Linked Directory Logging
When workspaces are linked for multi-repository tasks, the harness injects absolute paths into the environment (e.g., ARCHDUCTOR_LINKED_DIRECTORY_<NAME>). The logging system tracks these links to provide context for agents working across multiple worktrees.
Sources: crates/gtk-app/src/workspace_command_center.rs:1060-1090
Summary
The PTY Harness & Logging system acts as the bridge between the high-level Linux Archductor UI and the low-level execution of CLI-based AI agents. By wrapping agents in a managed PTY harness, the project achieves isolation, detailed audit trails via raw logs, and a rich, interactive experience through structured event parsing. This architecture supports complex workflows like session resumption, multi-turn tool use, and cross-workspace directory linking.