term-wrapper 0.2.0

PTY-based terminal emulator with web backend for running TUI applications via HTTP/WebSocket APIs

Terminal Wrapper

A full-featured terminal emulator with web backend that can run any TUI (Text User Interface) application and control it via HTTP/WebSocket APIs.

Features

• PTY-based Terminal Emulation: Full pseudo-terminal support for running terminal applications
• FastAPI Backend: RESTful API and WebSocket endpoints for terminal control
• Session Management: Create, manage, and control multiple terminal sessions
• CLI Subcommands: Scriptable terminal control from bash/shell without writing Python
• Python Client Library: High-level primitives (wait_for_text, wait_for_quiet, get_text)
• Comprehensive Tests: 117 tests covering unit, integration, and e2e scenarios

What's Supported

✅ Fully Working

• Simple commands: ls, cat, echo, shell scripts
• Interactive programs: Python REPL, bash, interactive shells
• Complex TUI apps: vim, less, nano (tested with web frontend)
• AI CLI tools: claude CLI (tested with both print and interactive modes)
• Full-screen apps: Full support via xterm.js web frontend
• ANSI colors & formatting: Complete support for escape sequences
• Terminal resize: Dynamic window resizing with SIGWINCH
• Multiple sessions: Concurrent terminal sessions with session management

🔧 Backend Only (Raw Output)

When using the REST API without a terminal emulator frontend:

• Complex TUI apps output raw ANSI escape sequences
• Pair with a terminal emulator like xterm.js for rendering

Included: Our web frontend (frontend/) provides full xterm.js integration with mobile support.

Architecture

┌─────────────────┐
│   CLI Client    │ ← Python client for interactive control
└────────┬────────┘
         │ HTTP/WebSocket
         ↓
┌─────────────────┐
│  FastAPI Server │ ← Web backend with REST + WebSocket
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│ Session Manager │ ← Manages multiple terminal sessions
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│ PTY Terminal    │ ← Pseudo-terminal for running TUI apps
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   TUI App       │ ← Any terminal application (vim, htop, etc.)
└─────────────────┘

Installation

From PyPI (Recommended for Users)

pip install term-wrapper

This installs the package and makes the term-wrapper CLI command available:

term-wrapper --help
term-wrapper create htop

From Source (For Development)

git clone https://github.com/rom1504/term-wrapper.git
cd term-wrapper
uv sync

When developing with uv, prefix commands with uv run:

uv run term-wrapper --help
uv run term-wrapper create htop

Quick Start

1. Start the Server

uv run python main.py

Server will start on http://localhost:8000

3. Run a TUI App

Option A: Using CLI Subcommands (Recommended)

# Create a session
SESSION=$(term-wrapper create bash -c "cd /tmp && claude" | python3 -c "import sys, json; print(json.load(sys.stdin)['session_id'])")

# Wait for text to appear
term-wrapper wait-text $SESSION "Welcome" --timeout 10

# Send input (supports \n, \r, \t, \x1b escape sequences)
term-wrapper send $SESSION "create hello.py\r"

# Get clean text output (ANSI codes stripped)
term-wrapper get-text $SESSION

# Wait for output to stabilize
term-wrapper wait-quiet $SESSION --duration 2

# Delete session
term-wrapper delete $SESSION

See all available subcommands:

term-wrapper --help

Note: In development with uv, prefix commands with uv run, e.g., `uv run term-wrapper --help

#### Option B: Using Python Client Library

```python
from term_wrapper.cli import TerminalClient

client = TerminalClient()
session_id = client.create_session(command=["bash"], rows=40, cols=120)

# High-level primitives
client.wait_for_text(session_id, "Welcome", timeout=10)
client.write_input(session_id, "ls -la\r")
text = client.get_text(session_id)  # Clean text, ANSI stripped
client.wait_for_quiet(session_id, duration=2)  # Wait for stability

client.delete_session(session_id)
client.close()

Option C: Using HTTP API Directly

# Create a session
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"command": ["python3", "examples/simple_tui.py"], "rows": 24, "cols": 80}'

# Returns: {"session_id": "xxx-xxx-xxx"}

# Get output
curl http://localhost:8000/sessions/{session_id}/output

# Send input
curl -X POST http://localhost:8000/sessions/{session_id}/input \
  -H "Content-Type: application/json" \
  -d '{"data": "+"}'

# Delete session
curl -X DELETE http://localhost:8000/sessions/{session_id}

CLI Subcommands

The term-wrapper CLI command is installed automatically when you install the package via pip. It provides scriptable terminal control without writing Python code. All commands output JSON for easy parsing.

Installation: The CLI entry point is defined in pyproject.toml as:

[project.scripts]
term-wrapper = "term_wrapper.cli:sync_main"

After pip install term-wrapper, the term-wrapper command will be available in your PATH. During development with uv, use uv run term-wrapper.

Available Subcommands

# Session Management
term-wrapper create [--rows N] [--cols N] [--env JSON] COMMAND...
term-wrapper list
term-wrapper info SESSION_ID
term-wrapper delete SESSION_ID

# Input/Output
term-wrapper send SESSION_ID TEXT           # Supports \n, \r, \t, \x1b
term-wrapper get-output SESSION_ID          # Raw output with ANSI codes
term-wrapper get-text SESSION_ID            # Clean text (ANSI stripped)
term-wrapper get-screen SESSION_ID          # Parsed 2D screen buffer

# Waiting Primitives
term-wrapper wait-text SESSION_ID TEXT [--timeout SECS]
term-wrapper wait-quiet SESSION_ID [--duration SECS] [--timeout SECS]

# Interactive
term-wrapper attach SESSION_ID              # WebSocket interactive mode

Shell Script Example

#!/bin/bash
# Automate vim file editing

SESSION=$(uv run python -m term_wrapper.cli create vim myfile.txt | \
          python3 -c "import sys, json; print(json.load(sys.stdin)['session_id'])")

# Enter insert mode
uv run python -m term_wrapper.cli send $SESSION "i"
sleep 0.3

# Type content
uv run python -m term_wrapper.cli send $SESSION "Hello World\nLine 2"
sleep 0.5

# Save and quit (ESC + :wq)
uv run python -m term_wrapper.cli send $SESSION "\x1b"
uv run python -m term_wrapper.cli send $SESSION ":wq\r"
sleep 0.5

# Cleanup
uv run python -m term_wrapper.cli delete $SESSION

See examples/ directory for more examples with vim, htop, and Claude Code.

Python Client Library

The TerminalClient class provides high-level primitives for terminal control:

from term_wrapper.cli import TerminalClient

client = TerminalClient(base_url="http://localhost:8000")

# Session management
session_id = client.create_session(command=["bash"], rows=40, cols=120)
sessions = client.list_sessions()
info = client.get_session_info(session_id)
client.delete_session(session_id)

# Input/Output
client.write_input(session_id, "ls -la\r")
output = client.get_output(session_id, clear=True)
text = client.get_text(session_id, strip_ansi_codes=True)
screen = client.get_screen(session_id)  # 2D screen buffer

# Waiting primitives
client.wait_for_text(session_id, "username:", timeout=10)
client.wait_for_condition(session_id, lambda text: "done" in text, timeout=30)
client.wait_for_quiet(session_id, duration=2.0, timeout=30)

# Incremental reading
new_lines = client.get_new_lines(session_id)
client.mark_read(session_id)

client.close()

API Reference

REST Endpoints

• POST /sessions - Create a new terminal session
• GET /sessions - List all active sessions
• GET /sessions/{id} - Get session information
• DELETE /sessions/{id} - Delete a session
• POST /sessions/{id}/input - Send input to terminal
• POST /sessions/{id}/resize - Resize terminal window
• GET /sessions/{id}/output - Get raw terminal output
• GET /sessions/{id}/screen - Get parsed 2D screen buffer (clean text)

WebSocket Endpoint

• WS /sessions/{id}/ws - Real-time bidirectional terminal I/O

Testing

Run all tests:

uv run pytest tests/ -v

Run specific test suites:

# Unit tests
uv run pytest tests/test_terminal.py tests/test_api.py -v

# End-to-end tests
uv run pytest tests/test_e2e.py -v

# Integration tests with TUI apps
uv run pytest tests/test_ink_integration.py -v

# Vim tests
uv run pytest tests/test_vim.py -v

Application Reports

We've tested various TUI applications with detailed reports:

Application	Status	Report	Tests
vim	✅ Fully Functional	reports/vim_report.md	tests/test_vim.py
htop	✅ Fully Functional	reports/htop_report.md	tests/test_htop.py
Claude CLI	✅ Fully Functional	reports/claude_report.md	tests/test_claude.py

Each report includes:

• Test methodology and results
• Usage examples (HTTP & WebSocket)
• Technical details (escape sequences, commands)
• Performance metrics
• Best practices

Want to add a new application? See reports/TESTING_GUIDE.md for a comprehensive step-by-step guide on testing and documenting new TUI applications.

Claude Code Skills

Want to use term-wrapper with Claude Code? Check out the /term-wrapper skill!

/term-wrapper htop              # Launch system monitor
/term-wrapper vim myfile.txt    # Edit files
/term-wrapper python            # Python REPL

See skills/README.md for full documentation.

Example TUI Apps

Interactive htop Demo (examples/htop_demo.py)

Demonstrates full interaction with htop system monitor:

uv run python examples/htop_demo.py

Features:

• Navigate process list with arrow keys
• Toggle tree view
• Change sort order
• Interactive command mode
• Live system monitoring through the API

Python TUI App (examples/simple_tui.py)

A simple counter application demonstrating:

• Terminal control codes
• Raw mode input handling
• Interactive key bindings

Controls:

• + : Increment counter
• - : Decrement counter
• r : Reset counter
• q : Quit

Project Structure

term_wrapper/
├── term_wrapper/      # Main package
│   ├── terminal.py        # PTY-based terminal emulator
│   ├── session_manager.py # Session management
│   ├── api.py            # FastAPI backend
│   └── cli.py            # CLI client
├── tests/                 # Test suite
│   ├── test_terminal.py   # Terminal emulator tests
│   ├── test_api.py        # API tests
│   ├── test_e2e.py       # End-to-end tests
│   └── test_ink_integration.py # TUI app tests
├── examples/             # Example applications
│   ├── simple_example.py # Simple HTTP API usage
│   ├── vim_example.py    # Vim automation example
│   ├── htop_demo.py      # Interactive htop demonstration
│   └── simple_tui.py     # Python TUI demo
├── skills/               # Claude Code skills
│   ├── tui.md            # /term-wrapper skill for running TUI apps
│   └── README.md         # Skills documentation
├── frontend/             # Web frontend with xterm.js
├── docs/                 # Documentation
├── scripts/              # Utility scripts
├── main.py              # Server entry point
└── pyproject.toml       # Project configuration

Development

Built with:

• uv - Fast Python package manager
• FastAPI - Modern web framework
• uvicorn - ASGI server
• pytest - Testing framework
• websockets - WebSocket support

License

ISC