| Name | termtap JSON |
| Version |
0.9.2
JSON |
| download |
| home_page | None |
| Summary | Process-native tmux session manager with MCP support |
| upload_time | 2025-09-19 06:36:51 |
| 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
- 🍎 **macOS Support** - Works on systems without /proc filesystem
- 📝 **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
>>> pane() # Read output with caching and interaction hints
>>> 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 |
| `pane(target=None, page=None)` | Read output with pagination and interaction hints |
| `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/b8/3a/a4e96d87cde52c76e73a17dd96310f0fa3ef8d9592a3aed588d5f10dc6fc/termtap-0.9.2.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- \ud83c\udf4e **macOS Support** - Works on systems without /proc filesystem\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>>> pane() # Read output with caching and interaction hints\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| `pane(target=None, page=None)` | Read output with pagination and interaction hints |\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.9.2",
"project_urls": {
"Repository": "https://github.com/angelsen/tap-tools"
},
"split_keywords": [
"mcp",
" session-manager",
" terminal",
" tmux"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "23ac71a43029a53b4f70cca39a8e961b9245090385f025ae1c8e98f67ca17994",
"md5": "e13cb9286cf733824d9d95a814476972",
"sha256": "2b0b790ee98a983451ec1764868e50b4ca1a79366d8da51a714e38b8f6b1cbae"
},
"downloads": -1,
"filename": "termtap-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e13cb9286cf733824d9d95a814476972",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 70614,
"upload_time": "2025-09-19T06:36:50",
"upload_time_iso_8601": "2025-09-19T06:36:50.489325Z",
"url": "https://files.pythonhosted.org/packages/23/ac/71a43029a53b4f70cca39a8e961b9245090385f025ae1c8e98f67ca17994/termtap-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b83aa4e96d87cde52c76e73a17dd96310f0fa3ef8d9592a3aed588d5f10dc6fc",
"md5": "214fa467cbb3aea393af966a7ff65e5a",
"sha256": "f12ff3d727e8a92e1f2454006fee6255b3b87a7ef2f6c82952b937e2514e13a3"
},
"downloads": -1,
"filename": "termtap-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "214fa467cbb3aea393af966a7ff65e5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 81043,
"upload_time": "2025-09-19T06:36:51",
"upload_time_iso_8601": "2025-09-19T06:36:51.747641Z",
"url": "https://files.pythonhosted.org/packages/b8/3a/a4e96d87cde52c76e73a17dd96310f0fa3ef8d9592a3aed588d5f10dc6fc/termtap-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-19 06:36:51",
"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"
}
