‍🖥️

📡

🎨

⚗️ Experimental

Runtime SDK
& TUI Client

Building IDE integration for Amplifier: ACP protocol, multiple transports, and a terminal interface — with AI-assisted visual testing

Diego Colombo · January 29-30, 2026

Chapter 1: The Vision

One Runtime, Many Clients

Amplifier should work anywhere — IDEs, terminals, web apps, remote servers.

"I want to create a starting point for a TUI interface in Python... the TUI needs to either launch the amplifier-runtime and connect using stdio, or attach it to the HTTP and WS interface..."

— Diego, Jan 29 initial session

Client Applications

⚡

Zed

💻

VS Code

🧠

JetBrains

📝

Neovim

‍🖥️

TUI

↓ ACP Protocol (JSON-RPC 2.0) ↓

Amplifier Runtime

stdio · HTTP · WebSocket · SSE

The Standard

Agent Client Protocol (ACP)

What is ACP?

Standardized protocol for IDE ↔ AI agents
Created by Anthropic, adopted by Zed, JetBrains
JSON-RPC 2.0 based messaging
Bidirectional capability negotiation
Streaming updates via notifications

Protocol v2025-01-07

Key Methods

`initialize`	Handshake & capabilities
`session/new`	Create agent session
`session/prompt`	Send user message
`session/update`	Streaming responses
`session/cancel`	Stop execution

Official SDK: agent-client-protocol>=0.7.1 · Spec: agentclientprotocol.com

Architecture

Four Transport Modes

📥

Stdio

Default mode. IDEs spawn as subprocess.

✓ Working

🌐

HTTP

REST API for web apps and remote.

✓ Working

🔌

WebSocket

Full-duplex real-time communication.

✓ Working

📡

SSE

Server-Sent Events for streaming.

✓ Working

# Stdio mode (default) - for IDEs $ amplifier-runtime # HTTP mode with ACP endpoints $ amplifier-runtime --http --acp # Check health $ amplifier-runtime --health

Implementation

Transport-Agnostic SDK

Client Modes

class TransportMode(str, Enum): SSE = "sse" # HTTP/1.1, HTTP/2 WEBSOCKET = "websocket" # Full duplex STDIO = "stdio" # Subprocess/IPC

Factory Methods

# Launch as subprocess client = create_subprocess_client() # Connect to running server client = create_attach_client( url="http://localhost:4096" )

Project Structure

src/amplifier_app_runtime/ ├── acp/ # ACP implementation │ ├── agent.py # SDK-based agent │ ├── routes.py # HTTP/SSE/WS endpoints │ ├── tools.py # Client-side tools │ └── __main__.py # Stdio entry ├── sdk/ # Client SDK │ ├── client.py # TransportClient │ └── types.py # Type definitions ├── transport/ # Transport layer ├── routes/ # HTTP routes ├── session.py # Session management └── app.py # Starlette app

Capabilities

Client-Side Tools (ACP)

When clients advertise capabilities, the agent gains access to IDE-provided tools.

‍🖥️

Terminal

Run commands in IDE's integrated terminal

terminal: true

→ ide_terminal tool

📖

Read Files

Read files through IDE's file system

fs.read_text_file: true

→ ide_read_file tool

✍️

Write Files

Write files through IDE's file system

fs.write_text_file: true

→ ide_write_file tool

                    Capability Negotiation: Agent adapts to what the client can provide
                
                    Full IDE integration → More tools available → Better agent capabilities

Chapter 2: The TUI

Terminal User Interface

A rich terminal client built with Textual/Rich for Amplifier.

Features Implemented

✓ Transport agnostic (subprocess or HTTP)
✓ Event bridge routing to UI
✓ Status bar with connection status
✓ Message area for conversation
◐ Slash command completion
✗ @ agent completion
◐ Multi-line input (Ctrl+J)

Slash Commands

/help Show this help /bundle Bundle information /agents List available agents /tools List available tools /mode Activate a mode /session Session management /init Setup wizard /config Show configuration /quit Exit application

Pain Points

Visual Debugging is Hard

🔴 Completion UI Issues

"Completion for / works but is at the end and not fully visible, only 2 items showing..."

🔴 Tab Inserts Too Much

"Hitting tab brings in the input both command and description"

🔴 @ Completion Broken

"The @ is not working at all"

🔴 Can't See What's Wrong

"I need to see the screenshots of the terminal to see what is happening"

The Core Problem

"The main struggle is that I need it to be able to spin off a terminal and launch the TUI experience, drive it and then see the screenshots of the terminal to see what is happening and be able to fix it."

— Diego, creating tui-tester

Without visual feedback, Amplifier can't know what the TUI looks like, making it impossible to debug layout and rendering issues.

Chapter 3: The Solution

TUI Tester Bundle

AI-assisted visual testing for terminal interfaces.

Capabilities

✓ Spawn - Launch TUI in headless pseudo-terminal
✓ Drive - Send keystrokes (arrows, enter, special keys)
✓ Capture - Get text, ANSI, and PNG screenshots
✓ Analyze - AI vision for visual issues
✓ Headless - No X11/display required (CI/CD)

# Spawn a TUI application result = tui_terminal( operation="spawn", command="amplifier-tui run" ) session_id = result["session_id"] # Send keystrokes tui_terminal( operation="send_keys", session_id=session_id, keys="/help{ENTER}" ) # Capture screenshot for analysis capture = tui_terminal( operation="capture", session_id=session_id ) # → {text, ansi, image_path}

TUI Tester

Driving TUI Interactions

Navigation Keys

{UP} Arrow up {DOWN} Arrow down {LEFT} Arrow left {RIGHT} Arrow right {HOME} Home key {END} End key {PGUP} Page up {PGDN} Page down

Action Keys

{ENTER} Enter/Return {TAB} Tab key {ESC} Escape {BACKSPACE} Backspace {DELETE} Delete

Control Keys

{CTRL+C} Interrupt {CTRL+D} EOF {CTRL+Z} Suspend {CTRL+L} Clear {F1} - {F12} Function keys

                    Uses pyte for VT100 terminal emulation + PIL for rendering
                
                    Works in CI/CD without display — perfect for automated visual testing

Workflow

Visual Testing with AI

1️⃣

Spawn TUI

Launch in headless terminal

→

2️⃣

Drive Interactions

Send keystrokes

↓

3️⃣

Capture Screenshot

Text + ANSI + PNG

→

4️⃣

AI Vision Analysis

Identify issues

↓

5️⃣

Fix & Iterate

Until visual tests pass

Status Report

What's Fully Working

✓ Amplifier Runtime

✓ All 4 transports (stdio, HTTP, WS, SSE)
✓ ACP protocol v2025-01-07
✓ Session management (create, resume, list)
✓ Bundle & provider management
✓ Client capability negotiation
✓ Init command wizard
✓ End-to-end tests passing

✓ TUI Tester Bundle

✓ PTY-based terminal emulation
✓ All special key support
✓ Text and ANSI capture
✓ PNG screenshot rendering
✓ Session management
✓ Headless operation
✓ Agent for visual analysis

4

transports working

258

tests passing

15+

CLI commands

Work in Progress

What Needs Completion

◐ TUI Client Issues

@ agent completion	Not Working
Completion visibility	2 items only
Tab completion	Inserts too much
Thinking events display	Not shown
Multi-turn with agents	Second turn fails

Next Steps

Use TUI Tester to capture visual state
Fix @ completion - agent suggestions not showing
Fix completion UI - show more items, better positioning
Fix tab behavior - only insert command, not description
Add thinking display - show agent reasoning
Create automated tests - visual regression suite

Compatibility

IDE Integration Ready

⚡

Zed

Native ACP support

Documented

💻

VS Code

Via stdio subprocess

Supported

🧠

JetBrains

AI Assistant ACP

Supported

📝

Neovim

Via ACP adapters

Supported

~/.config/zed/settings.json

{ "assistant": { "provider": "acp", "acp": { "command": ["amplifier-runtime"] } } }

The Amplifier Effect

What Amplifier Took Off My Plate

Before: Manual Everything

Write transport abstractions by hand
Debug protocol mismatches manually
Test TUI by running and watching
Parse and implement ACP from scratch
No way to "see" terminal output in agent

After: Amplifier Assists

zen-architect designed SDK architecture
modular-builder implemented transports
design-intelligence laid out TUI
Created tui-tester bundle for visual testing
Agents can now "see" and fix TUI issues

The Meta-Achievement

                    Built a bundle (tui-tester) that enables Amplifier to help me build the TUI client for Amplifier
                
                    🔄 Self-improving development loop

By The Numbers

Two Days of Building

2

repos created

1

bundle created

4

transport modes

15+

CLI commands

78

turns in main TUI session

258

tests passing

1

ACP protocol implemented

Methodology

Sources & Methodology

Data Collection

Data as of: February 20, 2026
Feature status: Experimental
Primary contributor: Diego Colombo (sole author)
Timeline: January 29-30, 2026

Sources

amplifier-tui repo (found locally at ~/dev/ANext/amplifier-tui)
amplifier-app-runtime repo (referenced in deck, not found locally)
Session narratives from development work
ACP protocol specification v2025-01-07

Verified Stats

4 transport modes (verified from deck content)
258 tests passing (from deck narrative)
15+ CLI commands (from deck narrative)
78 session turns (from deck narrative)
2 repos created, 1 bundle created

Known Gaps

Test count and session turn count from session narrative, not independently verified
Runtime repo not available locally for line count verification
TUI client has known issues (experimental status)

Looking Forward

The Path Ahead

Runtime is solid. TUI Tester is ready. Now: fix the TUI client with visual AI assistance.

🔧

Fix TUI Issues

Use tui-tester to debug completion, @ mentions, display

🧪

Visual Test Suite

Automated regression testing with screenshots

🚀

IDE Integration

Test with Zed, VS Code, JetBrains

Runtime SDK: ✓ Ready · TUI Tester: ✓ Ready · TUI Client: 🚧 In Progress

Runtime SDK& TUI Client

One Runtime, Many Clients

Agent Client Protocol (ACP)

Four Transport Modes

Transport-Agnostic SDK

Client-Side Tools (ACP)

Terminal User Interface

Visual Debugging is Hard

TUI Tester Bundle

Driving TUI Interactions

Visual Testing with AI

What's Fully Working

What Needs Completion

IDE Integration Ready

What Amplifier Took Off My Plate

Two Days of Building

Sources & Methodology

The Path Ahead

Runtime SDK
& TUI Client