| Name | termtap JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | Process-native tmux session manager with MCP support |
| upload_time | 2025-08-13 23:48:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
mcp
session-manager
terminal
tmux
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "termtap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "mcp, session-manager, terminal, tmux",
"author": null,
"author_email": "Fredrik Angelsen <fredrikangelsen@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7e/0f/3d29596241395e51094a80982a840a1f24e0f1130c49c8acb8780bd6aafb/termtap-0.4.1.tar.gz",
"platform": null,
"description": "# termtap\n\nProcess-native tmux session manager with MCP support.\n\n## \u2728 Features\n\n- \ud83c\udfaf **Smart Detection** - Auto-detects Python, SSH, Claude processes\n- \ud83d\udcdd **Handler System** - Process-specific output filtering and caching\n- \ud83d\udd0c **MCP Ready** - Tools and resources for Claude/LLMs\n- \ud83d\ude80 **Service Orchestration** - Run multi-service environments\n- \ud83d\udd0d **Fuzzy Search** - Filter sessions with patterns\n- \ud83c\udfa8 **Rich Display** - Tables, boxes, and formatted output\n\n## \ud83d\udccb Prerequisites\n\nRequired system dependencies:\n- **tmux** - Terminal multiplexer\n- **gum** - Interactive terminal UI components\n\n```bash\n# macOS\nbrew install tmux gum\n\n# Arch Linux\nsudo pacman -S tmux gum\n\n# Ubuntu/Debian\nsudo apt install tmux\n# For gum, see: https://github.com/charmbracelet/gum#installation\n\n# Fedora\nsudo dnf install tmux\n# For gum, use: go install github.com/charmbracelet/gum@latest\n```\n\n## \ud83d\udce6 Installation\n\n```bash\n# Install via uv tool (recommended)\nuv tool install termtap\n\n# Or with pipx\npipx install termtap\n\n# Update to latest\nuv tool upgrade termtap\n\n# Uninstall\nuv tool uninstall termtap\n```\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# 1. Install termtap\nuv tool install \"git+https://github.com/angelsen/tap-tools.git#subdirectory=packages/termtap\"\n\n# 2. Add to Claude\nclaude mcp add termtap -- termtap --mcp\n\n# 3. Run REPL\ntermtap\n```\n\n## \ud83d\udd0c MCP Setup for Claude\n\n```bash\n# Quick setup with Claude CLI\nclaude mcp add termtap -- termtap --mcp\n```\n\nOr manually configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n \"mcpServers\": {\n \"termtap\": {\n \"command\": \"termtap\",\n \"args\": [\"--mcp\"]\n }\n }\n}\n```\n\n## \ud83c\udfae Usage\n\n### Interactive REPL\n```bash\ntermtap # Start REPL\ntermtap --mcp # Start as MCP server\n```\n\n### Commands\n```python\n>>> ls() # List all sessions with processes\n>>> execute(\"python3\") # Start Python REPL in tmux\n>>> read() # Read output with caching\n>>> interrupt() # Send Ctrl+C to current pane\n>>> run(\"demo\") # Run service group from config\n```\n\n### Command Reference\n\n| Command | Description |\n|---------|------------|\n| `execute(command, target=None)` | Run command in tmux pane |\n| `read(target=None, page=None)` | Read output with pagination |\n| `ls(filter=None)` | List sessions with optional filter |\n| `interrupt(target=None)` | Send interrupt signal |\n| `send_keys(keys, target=None)` | Send raw key sequences |\n| `run(group)` | Run service configuration |\n| `track(target=None, duration=10)` | Monitor pane state |\n\n## \ud83d\udee0\ufe0f Service Configuration\n\nDefine multi-service environments in `termtap.toml`:\n\n```toml\n[init.demo]\nlayout = \"even-horizontal\"\n\n[init.demo.backend]\npane = 0\ncommand = \"uv run python -m backend\"\npath = \"demo/backend\"\nready_pattern = \"Uvicorn running on\"\ntimeout = 10\n\n[init.demo.frontend]\npane = 1 \ncommand = \"npm run dev\"\npath = \"demo/frontend\"\nready_pattern = \"Local:.*localhost\"\ndepends_on = [\"backend\"]\n```\n\nRun with: `run(\"demo\")`\n\n## \ud83d\udcc1 Examples\n\nSee `examples/` directory for:\n- Basic usage patterns\n- Service orchestration setups\n- MCP integration examples\n\n## \ud83c\udfd7\ufe0f Architecture\n\nBuilt on [ReplKit2](https://github.com/angelsen/replkit2) for dual REPL/MCP functionality.\n\n**Key Design:**\n- **Pane-Centric** - Everything operates through `Pane` objects\n- **Process-Native** - Uses `/proc` and tmux state directly\n- **Handler System** - Process-specific capture and filtering\n- **0-Based Pagination** - Navigate cached output efficiently\n\n## \ud83d\udcda Documentation\n\n- [Architecture](docs/ARCHITECTURE.md) - System design\n- [Handlers](src/termtap/process/handlers/) - Process-specific handlers\n- [Commands](src/termtap/commands/) - Command implementations\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# Clone repository\ngit clone https://github.com/angelsen/tap-tools\ncd tap-tools\n\n# Install for development\nuv sync --package termtap\n\n# Run development version\nuv run --package termtap termtap\n\n# Run tests and checks\nmake check-termtap # Check build\nmake format # Format code\nmake lint # Fix linting\n```\n\n## \ud83d\udcc4 License\n\nMIT - see [LICENSE](../../LICENSE) for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Process-native tmux session manager with MCP support",
"version": "0.4.1",
"project_urls": {
"Repository": "https://github.com/angelsen/tap-tools"
},
"split_keywords": [
"mcp",
" session-manager",
" terminal",
" tmux"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5f8bc325de114cff6db08cae1bd5ccd46973df825cef629c7aaa13a1c007c7c9",
"md5": "6113607d7ec07f92086959ed57124764",
"sha256": "c785f51a9b5e0f07f1333c734496003f3531077cfcc3aabeee17cf4882b31c2d"
},
"downloads": -1,
"filename": "termtap-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6113607d7ec07f92086959ed57124764",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 64877,
"upload_time": "2025-08-13T23:48:29",
"upload_time_iso_8601": "2025-08-13T23:48:29.123828Z",
"url": "https://files.pythonhosted.org/packages/5f/8b/c325de114cff6db08cae1bd5ccd46973df825cef629c7aaa13a1c007c7c9/termtap-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7e0f3d29596241395e51094a80982a840a1f24e0f1130c49c8acb8780bd6aafb",
"md5": "ba6375956d9358577dfd6a65b80c950e",
"sha256": "afe6b631328da4130e7f7099be5d97b8805e2ac2fcf749e9955098202f9277cc"
},
"downloads": -1,
"filename": "termtap-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "ba6375956d9358577dfd6a65b80c950e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 16266689,
"upload_time": "2025-08-13T23:48:33",
"upload_time_iso_8601": "2025-08-13T23:48:33.524749Z",
"url": "https://files.pythonhosted.org/packages/7e/0f/3d29596241395e51094a80982a840a1f24e0f1130c49c8acb8780bd6aafb/termtap-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 23:48:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "angelsen",
"github_project": "tap-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "termtap"
}
