termtap 0.4.1__tar.gz

termtap-0.4.1/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Debug-bridge artifacts
+bugs/
+tasks/
+
+# Local development files
+.context-search.json
+CLAUDE.md
+DEPLOYMENT.md
+
+# External resources
+_resources/

termtap-0.4.1/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.4.1] - 2025-08-14
+
+### Added
+- Published to PyPI for public availability
+- Support for standard tool installation via `uv tool install` and `pipx`
+
+### Changed
+- Removed private classifier to enable PyPI publishing
+- Updated installation documentation for PyPI distribution
+
+### Fixed
+<!-- Example: - Memory leak in worker process -->
+<!-- Example: - Incorrect handling of UTF-8 file names -->
+
+### Removed
+<!-- Example: - Deprecated legacy API endpoints -->
+<!-- Example: - Support for Python 3.7 -->
+
+<!-- 
+When you run 'relkit bump', the [Unreleased] section will automatically 
+become the new version section. Make sure to add your changes above!
+-->

termtap-0.4.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: termtap
+Version: 0.4.1
+Summary: Process-native tmux session manager with MCP support
+Project-URL: Repository, https://github.com/angelsen/tap-tools
+Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
+License: MIT
+Keywords: mcp,session-manager,terminal,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.12
+Requires-Dist: replkit2[all]>=0.7.2
+Requires-Dist: tmux-popup
+Provides-Extra: examples
+Requires-Dist: fastapi>=0.116.1; extra == 'examples'
+Requires-Dist: uvicorn>=0.35.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# termtap
+
+Process-native tmux session manager with MCP support.
+
+## ✨ Features
+
+- 🎯 **Smart Detection** - Auto-detects Python, SSH, Claude processes
+- 📝 **Handler System** - Process-specific output filtering and caching
+- 🔌 **MCP Ready** - Tools and resources for Claude/LLMs
+- 🚀 **Service Orchestration** - Run multi-service environments
+- 🔍 **Fuzzy Search** - Filter sessions with patterns
+- 🎨 **Rich Display** - Tables, boxes, and formatted output
+
+## 📋 Prerequisites
+
+Required system dependencies:
+- **tmux** - Terminal multiplexer
+- **gum** - Interactive terminal UI components
+
+```bash
+# macOS
+brew install tmux gum
+
+# Arch Linux
+sudo pacman -S tmux gum
+
+# Ubuntu/Debian
+sudo apt install tmux
+# For gum, see: https://github.com/charmbracelet/gum#installation
+
+# Fedora
+sudo dnf install tmux
+# For gum, use: go install github.com/charmbracelet/gum@latest
+```
+
+## 📦 Installation
+
+```bash
+# Install via uv tool (recommended)
+uv tool install termtap
+
+# Or with pipx
+pipx install termtap
+
+# Update to latest
+uv tool upgrade termtap
+
+# Uninstall
+uv tool uninstall termtap
+```
+
+## 🚀 Quick Start
+
+```bash
+# 1. Install termtap
+uv tool install "git+https://github.com/angelsen/tap-tools.git#subdirectory=packages/termtap"
+
+# 2. Add to Claude
+claude mcp add termtap -- termtap --mcp
+
+# 3. Run REPL
+termtap
+```
+
+## 🔌 MCP Setup for Claude
+
+```bash
+# Quick setup with Claude CLI
+claude mcp add termtap -- termtap --mcp
+```
+
+Or manually configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "termtap": {
+      "command": "termtap",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+## 🎮 Usage
+
+### Interactive REPL
+```bash
+termtap                     # Start REPL
+termtap --mcp               # Start as MCP server
+```
+
+### Commands
+```python
+>>> ls()                    # List all sessions with processes
+>>> execute("python3")      # Start Python REPL in tmux
+>>> read()                  # Read output with caching
+>>> interrupt()             # Send Ctrl+C to current pane
+>>> run("demo")             # Run service group from config
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|------------|
+| `execute(command, target=None)` | Run command in tmux pane |
+| `read(target=None, page=None)` | Read output with pagination |
+| `ls(filter=None)` | List sessions with optional filter |
+| `interrupt(target=None)` | Send interrupt signal |
+| `send_keys(keys, target=None)` | Send raw key sequences |
+| `run(group)` | Run service configuration |
+| `track(target=None, duration=10)` | Monitor pane state |
+
+## 🛠️ Service Configuration
+
+Define multi-service environments in `termtap.toml`:
+
+```toml
+[init.demo]
+layout = "even-horizontal"
+
+[init.demo.backend]
+pane = 0
+command = "uv run python -m backend"
+path = "demo/backend"
+ready_pattern = "Uvicorn running on"
+timeout = 10
+
+[init.demo.frontend]
+pane = 1  
+command = "npm run dev"
+path = "demo/frontend"
+ready_pattern = "Local:.*localhost"
+depends_on = ["backend"]
+```
+
+Run with: `run("demo")`
+
+## 📁 Examples
+
+See `examples/` directory for:
+- Basic usage patterns
+- Service orchestration setups
+- MCP integration examples
+
+## 🏗️ Architecture
+
+Built on [ReplKit2](https://github.com/angelsen/replkit2) for dual REPL/MCP functionality.
+
+**Key Design:**
+- **Pane-Centric** - Everything operates through `Pane` objects
+- **Process-Native** - Uses `/proc` and tmux state directly
+- **Handler System** - Process-specific capture and filtering
+- **0-Based Pagination** - Navigate cached output efficiently
+
+## 📚 Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) - System design
+- [Handlers](src/termtap/process/handlers/) - Process-specific handlers
+- [Commands](src/termtap/commands/) - Command implementations
+
+## 🛠️ Development
+
+```bash
+# Clone repository
+git clone https://github.com/angelsen/tap-tools
+cd tap-tools
+
+# Install for development
+uv sync --package termtap
+
+# Run development version
+uv run --package termtap termtap
+
+# Run tests and checks
+make check-termtap  # Check build
+make format         # Format code
+make lint           # Fix linting
+```
+
+## 📄 License
+
+MIT - see [LICENSE](../../LICENSE) for details.

termtap-0.4.1/PLAN.md

@@ -0,0 +1,158 @@
+# termtap Architecture
+
+## Overview
+Process-native tmux session manager with MCP support. Built on ReplKit2 for dual REPL/MCP functionality, featuring a pane-centric architecture with tmux-native popup interactions.
+
+## Core Design Principles
+
+1. **Pane-Centric**: Everything operates through `Pane` objects with lazy-loaded properties
+2. **Process-Native**: Leverage OS-level information from /proc instead of pattern matching
+3. **Direct tmux Integration**: Work with tmux's native concepts (panes and popups)
+4. **Handler Lifecycle**: Process-specific handlers control execution behavior
+5. **Interactive Safety**: Popup confirmations for dangerous operations (SSH, etc.)
+
+## Current Architecture
+
+### Module Structure
+```
+packages/termtap/src/termtap/
+├── __init__.py          # Package exports (app, __version__)
+├── __main__.py          # Entry point for python -m termtap
+├── app.py               # ReplKit2 app with MCP tools/resources
+├── config.py            # Configuration management
+├── types.py             # Core type definitions
+├── errors.py            # Error response formatters
+├── utils.py             # Utility functions (truncate_command, etc.)
+├── pane/                # Pane-centric core with optimized execution
+│   ├── __init__.py      # Public API exports
+│   ├── core.py          # Pure data Pane class with lazy properties
+│   ├── execution.py     # Command execution with handler lifecycle
+│   ├── inspection.py    # Output reading and process info
+│   └── streaming.py     # Stream-based output tracking
+├── commands/            # REPL/MCP commands using pane API
+│   ├── __init__.py      # Command registration
+│   ├── execute.py       # execute() - execute commands with streaming
+│   ├── read.py          # read() - MCP resource for output
+│   ├── ls.py            # ls() - MCP resource for session list
+│   ├── interrupt.py     # interrupt() - send Ctrl+C
+│   ├── send_keys.py     # send_keys() - raw keystroke input
+│   ├── track.py         # track() - handler development tool
+│   └── run.py           # run() - service group management
+├── tmux/                # Pure tmux operations (no shell logic)
+│   ├── __init__.py      # Public tmux API
+│   ├── core.py          # Core tmux operations (run_tmux)
+│   ├── resolution.py    # Target resolution logic
+│   ├── structure.py     # Session/window/pane creation
+│   ├── session.py       # Session management
+│   ├── pane.py          # Pane primitives (capture, send_keys)
+│   ├── stream.py        # Stream capture via pipes
+│   └── names.py         # Docker-style session names
+├── process/             # Process detection with pstree algorithm
+│   ├── __init__.py      # Process API exports
+│   ├── tree.py          # Process tree from /proc/*/stat
+│   └── handlers/        # Process-specific handlers
+│       ├── __init__.py  # Handler registry and selection
+│       ├── default.py   # Default handler
+│       ├── python.py    # Python REPL detection
+│       ├── ssh.py       # SSH with popup confirmations
+│       └── claude.py    # Claude-specific handling
+├── popup/               # Tmux-native popup system with gum
+│   ├── __init__.py      # Popup API exports
+│   ├── builder.py       # Popup builder with theme support
+│   ├── examples.py      # Usage examples
+│   └── llms.txt         # LLM documentation
+└── filters.py           # Output filtering functions
+```
+
+### Key Architecture Features
+
+1. **Pane-Centric Core**: All operations through `Pane` objects with lazy-loaded properties
+2. **Unified Streaming**: Single handler-controlled interface for output capture
+3. **Popup System**: Tmux-native popups using gum for rich terminal UIs
+4. **Handler Lifecycle**: Process-specific handlers with before/after hooks
+5. **Performance**: Optimized process scanning with minimal syscalls
+
+### Command Patterns
+
+Each command uses the pane-centric API:
+```python
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown"}
+)
+def execute(state, command: str, target: Target = "default"):
+    """Execute command in target pane."""
+    try:
+        pane_id, session_window_pane = resolve_or_create_target(target)
+    except RuntimeError as e:
+        return {"elements": [{"type": "text", "content": f"Error: {e}"}], 
+                "frontmatter": {"status": "error"}}
+    
+    pane = Pane(pane_id)
+    result = send_command(pane, command, wait=True)
+    
+    # Format result for markdown display
+    return {"elements": [...], "frontmatter": {"status": result["status"]}}
+```
+
+### Error Handling Architecture
+
+- **Modules raise**: Descriptive RuntimeError or domain exceptions
+- **Commands catch**: Transform to user-friendly messages
+- **No raw tracebacks**: All errors are formatted for users
+- **Consistent format**: `{"elements": [...], "frontmatter": {"status": "error"}}`
+
+### Target Resolution
+
+Supports multiple target formats:
+- **Pane ID**: `%42` - Direct tmux pane reference
+- **Session:Window.Pane**: `demo:0.0` - Full specification
+- **Session**: `demo` - May resolve to multiple panes
+- **Service**: `demo.backend` - Resolves via config
+
+### Process Detection
+
+Uses pstree algorithm scanning `/proc/*/stat`:
+- Builds complete process tree from PPID relationships
+- Selects first non-shell process for display
+- Returns sensible defaults on failure
+- No exceptions for non-critical operations
+
+## Testing & Development
+
+```bash
+# Run termtap REPL
+uv run termtap
+
+# Run linting and type checking
+ruff check packages/termtap/ --fix
+basedpyright packages/termtap/
+
+# Test with ReplKit2 Termtap
+mcp__termtap-dev__bash(command="uv run termtap")
+help()  # In REPL for command list
+```
+
+## Recent Improvements
+
+1. **Pane-Centric Refactor**: Optimized execution with lazy-loaded properties
+2. **Popup System**: Tmux-native popups with gum for interactive confirmations
+3. **Unified Streaming**: Handler-controlled output capture with command IDs
+4. **SSH Safety**: Interactive command editing before remote execution
+5. **Issue Tracking**: Comprehensive documentation in `/docs/issues/`
+
+## Future Considerations
+
+1. **More Handlers**: Container, database, notebook process handlers
+2. **Better Process Info**: Enhanced metadata from /proc
+3. **Session Templates**: Pre-configured multi-service setups
+4. **Performance**: Batch operations for large session counts
+5. **Testing**: Comprehensive test suite for error paths
+
+## Philosophy
+
+- **Simplicity over cleverness**: Direct, obvious implementations
+- **User experience first**: Clear errors, helpful messages
+- **Leverage the OS**: Use /proc, tmux state, system tools
+- **Fail gracefully**: Return defaults, not exceptions
+- **Progressive disclosure**: Simple commands, powerful options

termtap-0.4.1/README.md

@@ -0,0 +1,182 @@
+# termtap
+
+Process-native tmux session manager with MCP support.
+
+## ✨ Features
+
+- 🎯 **Smart Detection** - Auto-detects Python, SSH, Claude processes
+- 📝 **Handler System** - Process-specific output filtering and caching
+- 🔌 **MCP Ready** - Tools and resources for Claude/LLMs
+- 🚀 **Service Orchestration** - Run multi-service environments
+- 🔍 **Fuzzy Search** - Filter sessions with patterns
+- 🎨 **Rich Display** - Tables, boxes, and formatted output
+
+## 📋 Prerequisites
+
+Required system dependencies:
+- **tmux** - Terminal multiplexer
+- **gum** - Interactive terminal UI components
+
+```bash
+# macOS
+brew install tmux gum
+
+# Arch Linux
+sudo pacman -S tmux gum
+
+# Ubuntu/Debian
+sudo apt install tmux
+# For gum, see: https://github.com/charmbracelet/gum#installation
+
+# Fedora
+sudo dnf install tmux
+# For gum, use: go install github.com/charmbracelet/gum@latest
+```
+
+## 📦 Installation
+
+```bash
+# Install via uv tool (recommended)
+uv tool install termtap
+
+# Or with pipx
+pipx install termtap
+
+# Update to latest
+uv tool upgrade termtap
+
+# Uninstall
+uv tool uninstall termtap
+```
+
+## 🚀 Quick Start
+
+```bash
+# 1. Install termtap
+uv tool install "git+https://github.com/angelsen/tap-tools.git#subdirectory=packages/termtap"
+
+# 2. Add to Claude
+claude mcp add termtap -- termtap --mcp
+
+# 3. Run REPL
+termtap
+```
+
+## 🔌 MCP Setup for Claude
+
+```bash
+# Quick setup with Claude CLI
+claude mcp add termtap -- termtap --mcp
+```
+
+Or manually configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "termtap": {
+      "command": "termtap",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+## 🎮 Usage
+
+### Interactive REPL
+```bash
+termtap                     # Start REPL
+termtap --mcp               # Start as MCP server
+```
+
+### Commands
+```python
+>>> ls()                    # List all sessions with processes
+>>> execute("python3")      # Start Python REPL in tmux
+>>> read()                  # Read output with caching
+>>> interrupt()             # Send Ctrl+C to current pane
+>>> run("demo")             # Run service group from config
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|------------|
+| `execute(command, target=None)` | Run command in tmux pane |
+| `read(target=None, page=None)` | Read output with pagination |
+| `ls(filter=None)` | List sessions with optional filter |
+| `interrupt(target=None)` | Send interrupt signal |
+| `send_keys(keys, target=None)` | Send raw key sequences |
+| `run(group)` | Run service configuration |
+| `track(target=None, duration=10)` | Monitor pane state |
+
+## 🛠️ Service Configuration
+
+Define multi-service environments in `termtap.toml`:
+
+```toml
+[init.demo]
+layout = "even-horizontal"
+
+[init.demo.backend]
+pane = 0
+command = "uv run python -m backend"
+path = "demo/backend"
+ready_pattern = "Uvicorn running on"
+timeout = 10
+
+[init.demo.frontend]
+pane = 1  
+command = "npm run dev"
+path = "demo/frontend"
+ready_pattern = "Local:.*localhost"
+depends_on = ["backend"]
+```
+
+Run with: `run("demo")`
+
+## 📁 Examples
+
+See `examples/` directory for:
+- Basic usage patterns
+- Service orchestration setups
+- MCP integration examples
+
+## 🏗️ Architecture
+
+Built on [ReplKit2](https://github.com/angelsen/replkit2) for dual REPL/MCP functionality.
+
+**Key Design:**
+- **Pane-Centric** - Everything operates through `Pane` objects
+- **Process-Native** - Uses `/proc` and tmux state directly
+- **Handler System** - Process-specific capture and filtering
+- **0-Based Pagination** - Navigate cached output efficiently
+
+## 📚 Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) - System design
+- [Handlers](src/termtap/process/handlers/) - Process-specific handlers
+- [Commands](src/termtap/commands/) - Command implementations
+
+## 🛠️ Development
+
+```bash
+# Clone repository
+git clone https://github.com/angelsen/tap-tools
+cd tap-tools
+
+# Install for development
+uv sync --package termtap
+
+# Run development version
+uv run --package termtap termtap
+
+# Run tests and checks
+make check-termtap  # Check build
+make format         # Format code
+make lint           # Fix linting
+```
+
+## 📄 License
+
+MIT - see [LICENSE](../../LICENSE) for details.

termtap-0.4.1/docs/ARCHITECTURE.md

@@ -0,0 +1,103 @@
+# termtap Architecture
+
+## Core Design Principles
+
+**Process-Native**: Don't recreate what the OS already knows.
+- Use `/proc` for process information
+- Query tmux state directly (no shadow state)
+- First non-shell process for meaningful display
+
+**Pane-Centric**: Everything operates through `Pane` objects.
+- Lazy-loaded properties for efficiency
+- Unified execution path
+- Consistent return formats
+
+**Handler-Centric Caching**: Process handlers own output management.
+- Process-specific filtering (SSH aggressive, Python minimal)
+- Centralized caching logic
+- ~30-40% code reduction in commands
+
+## Module Structure
+
+```
+termtap/
+├── pane/               # Pane abstraction (core)
+│   ├── core.py        # Pane class with lazy properties
+│   ├── execution.py   # Command execution with handler lifecycle
+│   └── inspection.py  # Output reading and process info
+│
+├── process/           # Process detection and handling
+│   ├── tree.py       # pstree algorithm using /proc
+│   └── handlers/     # Process-specific handlers
+│       ├── __init__.py    # Handler registry and base class
+│       ├── python.py      # Python REPL handler
+│       ├── ssh.py         # SSH session handler
+│       └── claude.py      # Claude CLI handler
+│
+├── tmux/              # Pure tmux operations
+│   ├── core.py       # Basic tmux commands
+│   ├── session.py    # Session management
+│   └── stream.py     # Output streaming
+│
+├── commands/          # REPL/MCP commands
+│   ├── execute.py    # Run commands in panes
+│   ├── read.py       # Read output with caching
+│   └── interrupt.py  # Send signals
+│
+└── app.py            # ReplKit2 app definition
+```
+
+## Key Flows
+
+### Command Execution
+```python
+execute(command, target) 
+  → resolve_pane(target)
+  → get_handler(pane)
+  → handler.before_send(command)
+  → send_command(pane, command)
+  → handler.capture_output(pane, state)
+```
+
+### Process Detection
+```python
+Pane(pane_id)
+  → get_process_tree()     # From /proc
+  → find_first_non_shell()  # Skip bash/zsh
+  → get_handler()          # Match handler
+```
+
+### Output Caching
+```python
+read(target, page)
+  → get_handler(pane)
+  → handler.capture_output(pane, state)  # Uses cache
+  → paginate(output, page)               # 0-based pages
+```
+
+## Handler System
+
+Each handler implements:
+- `can_handle(pane)` - Process detection
+- `is_ready(pane)` - State detection (ready/busy/unknown)
+- `capture_output(pane, state)` - Caching and filtering
+- `before_send(pane, command)` - Command preprocessing
+
+### Handler Selection
+1. Check active process name
+2. Match against handler's `_handles` list
+3. Fall back to DefaultHandler
+
+### Cache Strategy
+- Commands use stream capture (partial output)
+- Reads use full buffer capture
+- Cache stored in handler state dict
+- Pages are 0-based with negative indexing
+
+## Dependencies
+
+Built on [ReplKit2](https://github.com/angelsen/replkit2):
+- Dual REPL/MCP functionality
+- Rich display formatting
+- State management
+- MCP protocol support