termtap
Execute commands in tmux panes with intelligent state detection via pattern learning.
Features
- 🤖 Pattern Learning - Teach termtap process states (ready/busy) interactively
- 🎯 Smart Execution - Commands wait for processes to be ready before sending
- 🖥️ Companion UI - Visual pattern editor and queue management
- 📡 Daemon Architecture - Background process with RPC communication
- 🔌 MCP Support - Tools and resources for Claude/LLMs
- 📦 Terminal Emulation - Precise output capture with tmux streaming
Prerequisites
Required system dependencies:
- tmux - Terminal multiplexer
- gum - Interactive terminal UI components (for pattern editing)
# macOS
brew install tmux gum
# Arch Linux
sudo pacman -S tmux gum
# Ubuntu/Debian
sudo apt install tmux
# For gum: https://github.com/charmbracelet/gum#installation
Installation
# Install via uv tool (recommended)
uv tool install termtap
# Or with pipx
pipx install termtap
# Update to latest
uv tool upgrade termtap
Quick Start
1. Start Daemon
termtap daemon start
2. Launch Companion UI (optional but recommended)
termtap companion
The companion provides:
- Pattern editor with live preview
- Queue viewer for pending actions
- Pane selector for interactive workflows
3. Run REPL
termtap
4. Execute Commands
>>> execute("python3")
# First time: Companion asks if process is ready
# You teach the pattern once, termtap learns it
>>> pane() # View output
MCP Setup for Claude
# Quick setup with Claude CLI
claude mcp add termtap -- termtap --mcp
# Or manually edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"termtap": {
"command": "termtap",
"args": ["--mcp"]
}
}
}
Commands
| Command | Description |
|---|---|
execute(command, target=None) |
Run command in tmux pane, wait for ready state |
pane(target=None, offset=0, limit=100) |
Read pane output with pagination |
ls(filter=None) |
List tmux sessions |
interrupt(target=None) |
Send Ctrl+C to pane |
send_keystrokes(keys, target=None) |
Send raw keystrokes (for interactive programs) |
debug(code) |
Inspect daemon state (Python expressions) |
Pattern Learning Workflow
First Time Execution
>>> execute("python3")
# Companion shows: "Is this process ready? (y/n)"
# You press 'y' and mark the pattern: ">>> "
Pattern Storage
Patterns are saved to ~/.termtap/patterns.json:
{
"python": {
"ready": [">>> ", "\\.\\.\\. "]
}
}
Subsequent Executions
>>> execute("print('hello')")
# Automatically waits for ">>> " pattern
# Executes immediately when ready
Architecture
Components
- Daemon (
termtap daemon) - Background process managing pane state - Client - RPC client in REPL/MCP mode
- Companion (
termtap companion) - Textual UI for pattern management - Terminal Emulator - SlimScreen with pyte for output capture
Action Lifecycle
- SELECTING_PANE - Choose target pane (if not specified)
- READY_CHECK - Check if process matches learned patterns
- WATCHING - Command sent, waiting for completion
- COMPLETED - Process returned to ready state
Pattern Matching
Process Output Pattern State
---------------- -------- -------
>>> _ >>> $ ready
... \.\.\. $ ready
Executing... (any) busy
Development
# Clone repository
git clone https://github.com/angelsen/tap-tools
cd tap-tools/packages/termtap
# Install for development
uv sync
# Run checks
basedpyright # Type checking
ruff check --fix # Linting
# Run development version
uv run termtap
# Stop daemon
termtap daemon stop
Troubleshooting
Daemon not responding
termtap daemon status # Check daemon state
termtap daemon stop # Stop daemon
termtap daemon start # Restart
Pattern not matching
termtap companion # Open companion UI
# Navigate to Patterns → Edit pattern → Test with preview
Stuck in READY_CHECK
- Open companion UI
- Queue tab shows pending actions
- Mark pattern as ready/busy or cancel action
License
MIT - see LICENSE for details.
Metadata
Release files for termtap 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| termtap-0.14.0.tar.gz | 94.4 kB | Without provenance | Details for termtap-0.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| termtap-0.14.0-py3-none-any.whl | Python 3 | none | any | Details for termtap-0.14.0-py3-none-any.whl |
Total release size: 186.7 kB
Release files / termtap-0.14.0.tar.gz
| Download URL | termtap-0.14.0.tar.gz |
|---|---|
| Size | 94.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93dee93f7039e6fea8054205d6b33022e7a273139e7957e25f827213ec9bbbad
|
|
BLAKE2b-256 checksum How to use checksums |
d51f2565c9e1c890601dc086d1766349bf869e8912c8d6d84a5431f81431405b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / termtap-0.14.0-py3-none-any.whl
| Download URL | termtap-0.14.0-py3-none-any.whl |
|---|---|
| Size | 92.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4d30ab1f65a4a28ecf0d570bbc688e1c663ad38cb30e52f85508b21335a4f602
|
|
BLAKE2b-256 checksum How to use checksums |
b29a2ee7a6416860ca1d3854127de1e22e5d30aed9a2a3c1c2869e2621979976
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for termtap 0.14.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.