TUI SWE-Agent Harness Interface
Relevant source files
The following files were used as context for generating this wiki page:
The TUI SWE-Agent Harness Interface is a Go-based terminal-native system designed to orchestrate software engineering (SWE) agents. It provides a robust, stable core for repository exploration, code research, and automated refactoring while allowing for high extensibility through pluggable backends and extensions. The interface prioritizes operational simplicity and observability, ensuring that failures in automated agent workflows are visible and diagnosable.
A critical component of this harness is its extension architecture, which wraps specialized services like swe_distiller—a Rust-based content extraction pipeline. This allows the terminal interface to ingest web content, documentation, and source code in a normalized Markdown format, which is then processed by agents using tools like ast-grep and fff-mcp for structural analysis and search.
Sources: AGENTS.md:275-285, extensions/swe_distiller/ARCHITECTURE.md:3-8
Architecture and Core Principles
The harness follows a modular architecture where the primary Go-based TUI coordinates with various agent personas and toolsets. It is designed to be cloud-agnostic, supporting pluggable backends across providers like GCP, AWS, and Modal.
Decision Hierarchy
System decisions are governed by a strict hierarchy to ensure reliability:
- Correctness & User Intent: Adhering to specific requests.
- Safety & Blast Radius: Protecting production systems and data.
- Observability: Making failures visible and cheap to diagnose.
- Operational Simplicity: Ensuring systems are manageable under stress.
Sources: AGENTS.md:28-44, AGENTS.md:275-279
Component Relationship Diagram
The following diagram illustrates the relationship between the core TUI harness, its extensions, and the tool-based MCP (Model Context Protocol) layers.
The TUI acts as the orchestrator, delegating content processing to Rust extensions and code analysis to MCP tools.
Sources: AGENTS.md:144-159, extensions/swe_distiller/ARCHITECTURE.md:16-29
Content Distillation Pipeline
A core capability of the harness is the swe_distiller extension, which converts raw URLs into clean, agent-readable Markdown. This pipeline is deterministic by default but supports an optional LLM-based extraction override.
High-Level Content Flow
- Acquisition: HTTP acquisition with browser fallbacks for challenge pages (e.g., Cloudflare).
- Extraction: Heuristic-based selection of main content candidates.
- Cleanup: Multi-stage removal of navigation, footer, and newsletter chrome.
- Transformation: AST-based conversion from DOM to Markdown.
- Refinement: Post-processing to normalize metadata and headings.
Sources: extensions/swe_distiller/ARCHITECTURE.md:16-29, extensions/swe_distiller/src/lib.rs:136-224
Data Flow Sequence
The interaction between the user interface, the fetcher, and the extraction logic:
The sequence demonstrates the transition from a raw URL to structured data.
Sources: extensions/swe_distiller/src/lib.rs:27-52, extensions/swe_distiller/src/main.rs:59-67
Agent Tooling and Search
The harness integrates specialized tools for repository exploration and code modification, governed by a strict "Polyglot Principal Engineer" persona.
Tool Boundaries
| Tool Category | Primary Utility | Specific Tools Used |
|---|---|---|
| Text Streams | Logs, CSV, configs | grep, rg, sed, jq, yq |
| Source Code | Research, refactors | demongrep, ast-grep, semgrep, grit |
| Repo Exploration | Filename discovery | fff-mcp equivalents |
Sources: AGENTS.md:144-171
Structural Search with ast-grep
Agents use ast-grep rules defined in prompts.yaml to search the codebase. These rules leverage Abstract Syntax Trees rather than regex for higher precision.
# Example ast-grep rule structure
all:
- kind: call_expression
- pattern: console.log($ARG)
Sources: src/prompts.yaml:189-195
LLM Extraction Logic
When heuristic extraction is insufficient, the harness can invoke an LLM pipeline. This pipeline uses configured providers (e.g., Ollama, Jina) to perform the HTML-to-Markdown conversion.
LLM Safety and Quality Gates
To prevent hallucinations or data loss, the system applies safety checks before accepting LLM output:
- Word Count Check: The candidate must have a word count between 75% and 135% of the original heuristic baseline.
- Link Integrity: The candidate must preserve a significant percentage of links found in the original document.
- Noise Scoring: A
structure_noise_scoreis calculated based on UI chrome (e.g., "Sign up", "Follow" buttons). If the LLM output is noisier than the baseline, it is rejected.
Sources: extensions/swe_distiller/src/extraction/checks.rs:1-60, extensions/swe_distiller/src/extraction/llm.rs:43-65
LLM Pipeline Outcome Mapping
| Outcome | Condition |
|---|---|
Applied | LLM candidate passed all safety and noise checks. |
SkippedNoAcceptableCandidate | LLM failed checks or providers were unreachable. |
Sources: extensions/swe_distiller/src/extraction/llm.rs:69-75
Summary
The TUI SWE-Agent Harness Interface provides a structured environment for AI agents to operate on software repositories. By combining a terminal-native Go core with high-performance Rust extensions like swe_distiller and structural search tools like ast-grep, the system ensures that agents have access to clean, normalized data and precise code-navigation capabilities. The emphasis on safety checks and observability allows for automated workflows that remain under developer control even during complex refactoring tasks.