headless-terminal

Original：🇺🇸 English

Translated

This skill provides guidance for implementing headless terminal interfaces that programmatically control shell sessions. Use this skill when implementing terminal emulation, pseudo-terminal wrappers, or interfaces like BaseTerminal that require sending keystrokes and reading output from shell processes.

2installs

Sourceletta-ai/skills

Added on2026-02-15

NPX Install

npx skill4agent add letta-ai/skills headless-terminal

SKILL.md Content

View Translation Comparison →

Headless Terminal Implementation

Overview

This skill guides the implementation of headless terminal interfaces—programmatic wrappers that control shell sessions without a visible terminal UI. These implementations typically involve spawning shell processes, sending input (keystrokes, commands), and capturing output.

Approach

Step 1: Understand the Interface Contract

Before implementing, thoroughly read and understand the interface to be implemented:

Identify all required methods and their signatures
Note return types and expected behaviors
Check for optional methods or features
Look for existing implementations or tests that clarify expected behavior

Step 2: Select the Underlying Library

Common libraries for terminal emulation in Python:

Library	Best For	Trade-offs
`pexpect`	Interactive terminal emulation, pattern matching	Higher-level API, good for expect/send patterns
`pty`	Low-level pseudo-terminal control	More control, but more boilerplate
`subprocess`	Simple non-interactive commands	Limited for true terminal emulation

Decision criteria to document:

Does the task require interactive input (passwords, prompts)? →
```
pexpect
```
Does the task need low-level terminal control? →
```
pty
```
Is it purely non-interactive command execution? →
```
subprocess
```
may suffice

Document the choice explicitly with reasoning for future maintainability.

Step 3: Handle Shell Configuration

When spawning a shell process, consider these configuration options:

Interactive mode (
-i
flag):

Ensures startup files (
```
.bashrc
```
,
```
.bash_profile
```
) are sourced
Affects signal handling behavior
Required if tests verify startup file sourcing

Echo behavior:

```
echo=False
```
in pexpect prevents input from appearing in output
Consider whether the use case needs to see echoed input

Terminal dimensions:

Default
```
(24, 80)
```
is standard terminal size
May affect output formatting for commands that detect terminal width
Document why specific dimensions are chosen

Step 4: Implement Core Functionality

Focus on implementing exactly what the interface requires:

Process lifecycle management - Spawn, check liveness, terminate
Input handling - Send keystrokes, handle special keys (Ctrl+C, etc.)
Output capture - Read available output, handle buffering
Resource cleanup - Proper termination, context manager support

Step 5: Address Edge Cases

Explicitly handle these scenarios:

Edge Case	Handling Strategy
Shell exits unexpectedly	Check process liveness before operations
Long-running commands	Configurable timeouts, background execution support
Non-ASCII characters	Explicit encoding handling (UTF-8 typically)
Race conditions	Appropriate delays between send and read operations
Command cancellation	Proper signal handling (SIGINT for Ctrl+C)

Verification Strategies

Testing Approach

Create focused tests for each capability:

Basic functionality - Import, instantiation
Non-interactive commands - Simple command execution and output
Interactive commands - Commands requiring input
Signal handling - Ctrl+C cancellation
Shell state - Variable persistence, environment
Startup configuration - Verify startup files are sourced
Background execution - Long-running command handling

Verification Guidelines

Run the test suite to verify all functionality
Avoid redundant manual verification after tests pass
If a single comprehensive test file exists, use it rather than creating separate verification scripts

Common Pitfalls

Scope Management

Implement only what is required - Avoid adding unrequested features like extra utility methods
If additional methods seem useful, note them but don't implement unless asked
Context manager support is often expected but verify it's in the interface

Efficiency

Avoid redundant searches - If searching for a class, one targeted search is sufficient
Don't duplicate verification - If tests pass, additional manual checks are unnecessary
Don't create example files unless explicitly requested

Documentation Gaps

Common decisions that should be documented but often aren't:

Why the chosen library over alternatives
Why specific shell flags are used
Why specific default values were selected
Thread safety considerations (or explicit statement that it's not thread-safe)

Error Handling

Consider and document handling for:

Invalid keystroke sequences
Terminal process termination
Timeout scenarios
Permission issues

Implementation Checklist

Before considering the implementation complete:

All interface methods are implemented
Library choice is documented with reasoning
Configuration decisions are justified
Edge cases are explicitly handled or documented as out of scope
Tests cover all required functionality
No unrequested features were added
Resource cleanup is properly implemented