{"id":29616674,"url":"https://github.com/tizee/tmux-capture","last_synced_at":"2025-07-21T01:02:04.189Z","repository":{"id":303904409,"uuid":"1017069782","full_name":"tizee/tmux-capture","owner":"tizee","description":"tmux-capture is a modern Python-based hint-based text selection in tmux, offering easier setup, better maintenance, and advanced pattern detection.","archived":false,"fork":false,"pushed_at":"2025-07-19T14:43:28.000Z","size":205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T18:35:42.634Z","etag":null,"topics":["python","regex-match","terminal-based","tmux","vim-like"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tizee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T01:36:06.000Z","updated_at":"2025-07-19T14:40:39.000Z","dependencies_parsed_at":"2025-07-10T11:48:31.264Z","dependency_job_id":"10d1c9f6-9956-4c06-b81b-52d44cc72043","html_url":"https://github.com/tizee/tmux-capture","commit_stats":null,"previous_names":["tizee/tmux-capture"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tizee/tmux-capture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tizee%2Ftmux-capture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tizee%2Ftmux-capture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tizee%2Ftmux-capture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tizee%2Ftmux-capture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tizee","download_url":"https://codeload.github.com/tizee/tmux-capture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tizee%2Ftmux-capture/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266222295,"owners_count":23894992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","regex-match","terminal-based","tmux","vim-like"],"created_at":"2025-07-21T01:02:03.440Z","updated_at":"2025-07-21T01:02:04.186Z","avatar_url":"https://github.com/tizee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-capture\n\n[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Dependency manager: uv](https://img.shields.io/badge/dependency%20manager-uv-blue.svg)](https://github.com/astral-sh/uv)\n[![tmux](https://img.shields.io/badge/tmux-compatible-green.svg)](https://github.com/tmux/tmux)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/tizee/tmux-capture)\n\nA modern Python-based text selection tool for tmux, inspired by tmux-thumbs but designed for better usability and maintenance.\n\n\u003cvideo src=\"https://github.com/user-attachments/assets/a1b7d9fb-36c5-494d-8dca-8cc84d8e2196\" controls width=\"100%\"\u003e\u003c/video\u003e\n\n## Motivation\n\nWhile [tmux-thumbs](https://github.com/fcsonline/tmux-thumbs) pioneered the concept of hint-based text selection in tmux, it has several limitations:\n- Requires external Rust compilation and installation\n- Complex setup process\n- Hasn't been actively maintained\n- Limited customization options\n\ntmux-capture solves these issues by:\n- Using Python with minimal dependencies (just `blessed`)\n- Self-contained script with dependency management via `uv`\n- Simple installation and configuration\n\n## Features\n\n- **Pattern Detection**: Automatically finds URLs, git commits, email addresses, and GitHub repositories\n- **Optimal Keyboard Hints**: Advanced hint generation using greedy algorithm with optimal substructure\n- **Cross-platform**: Works on macOS and Linux\n- **Gruvbox Theme**: Beautiful color scheme for better visibility\n- **ANSI Support**: Preserves terminal colors and formatting\n- **Clipboard Integration**: Automatic copying to system clipboard\n\n## Installation\n\n1. Clone or download this repository\n2. Install uv if not already installed:\n   ```bash\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n   ```\n3. Run the installation script:\n   ```bash\n   ./install.sh\n   ```\n4. Reload tmux configuration:\n   ```bash\n   tmux source-file ~/.tmux.conf\n   ```\n\n## CLI Integration\n\n### Add to PATH (Optional)\n\nFor convenient CLI usage, add tmux-capture to your PATH:\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc\nexport PATH=\"/path/to/tmux-capture:$PATH\"\nalias tc='tmux-capture'\n```\n\n### Zsh Plugin (Optional)\n\nFor zsh users, enable command-line hotkey support:\n\n```bash\n# Add to ~/.zshrc\nsource \"/path/to/tmux-capture/tmux-capture.plugin.zsh\"\n```\n\nThis provides:\n- **Ctrl+E** - Launch tmux-capture from command line (configurable)\n- **tmux-capture-help** - Show plugin help\n\n### Customize Hotkey\n\nThe default hotkey is `Ctrl+E`, but you can customize it:\n\n```bash\n# Set custom hotkey before sourcing the plugin\nexport TMUX_CAPTURE_HOTKEY='^O'  # Ctrl+O\nsource \"/path/to/tmux-capture/tmux-capture.plugin.zsh\"\n```\n\nCommon hotkey formats:\n- `^E` - Ctrl+E\n- `^O` - Ctrl+O\n- `^X^E` - Ctrl+X, Ctrl+E\n- `\\e[` - Alt+key combinations\n\n## Usage\n\n### In tmux (Recommended)\n\n1. In any tmux pane, press `Prefix + y` (default tmux prefix is `Ctrl-b`)\n2. A new window opens showing the original pane content with highlighted matches\n3. Type the hint characters (a, b, c, etc.) to select text\n4. Selected text is automatically copied to clipboard\n5. Press any key to close the selection window\n\n### As CLI tool\n\nThe tool can also be used as a standalone CLI application:\n\n```bash\n# Capture content from current tmux pane\n./tmux-capture\n\n# Capture content from specific tmux pane\n./tmux-capture %1\n\n# Using uv (recommended)\nuv run tmux-capture\n\n# Works outside tmux too - will show error if no tmux session\npython3 tmux-capture\n```\n\n**Note**: While the tool can run outside tmux, it's designed for tmux environments and requires a tmux session to capture pane content.\n\n## Key Bindings\n\nDefault binding: `Prefix + y`\n\nTo customize, edit your `~/.tmux.conf`:\n```bash\n# Use different key combination\nbind-key C-y run-shell '/path/to/tmux-capture-window.sh'  # Prefix + Ctrl+y\nbind-key -n M-y run-shell '/path/to/tmux-capture-window.sh'  # Alt+y (no prefix)\n```\n\n## Pattern Recognition\n\ntmux-capture automatically detects and prioritizes 18 different text patterns:\n\n### Supported Patterns\n- **URLs**: `https://example.com/path`, `git@github.com:user/repo.git`\n- **Git commits**: `a1b2c3d4e5f6789` (7-40 hex characters)\n- **Email addresses**: `user@example.com`, `user+tag@domain.co.uk`\n- **GitHub repositories**: `https://github.com/user/repo`, `git@github.com:user/repo.git`\n- **IP addresses**: `192.168.1.1`, `10.0.0.1:8080` (with optional port)\n- **IPv6 addresses**: `2001:db8::1`, `::1`\n- **File paths**: `/home/user/file.txt`, `./relative/path`\n- **MAC addresses**: `aa:bb:cc:dd:ee:ff`, `AA-BB-CC-DD-EE-FF`\n- **UUIDs**: `550e8400-e29b-41d4-a716-446655440000`\n- **Hex colors**: `#ff0000`, `#1a2b3c`\n- **Docker SHA**: `sha256:abcd1234...` (64 hex characters)\n- **Memory addresses**: `0x7fff12345678`\n- **IPFS hashes**: `QmX1eWnvmPiYT...` (44 characters)\n- **Large numbers**: `12345` (4+ digits)\n- **Markdown links**: `[text](url)` (extracts URL)\n- **Git diff files**: `diff --git a/file b/file`, `--- a/file`, `+++ b/file`\n\n## Overlap Resolution Algorithm\n\nWhen multiple patterns match the same text region, tmux-capture uses an intelligent overlap resolution algorithm to ensure only the most relevant match is displayed and copied.\n\n### Priority Rules\n\nThe algorithm applies the following rules in order:\n\n1. **Length Priority**: Longer matches are preferred over shorter ones\n   ```\n   \"33030965+user@example.com\" → EMAIL (full match) wins over LARGE_NUMBER (partial)\n   ```\n\n2. **Pattern Specificity**: More specific patterns win over generic ones\n   ```\n   Priority levels (1 = highest, 20 = lowest):\n   - EMAIL, URL: 1 (highest priority)\n   - GITHUB_REPO: 2  \n   - GIT_COMMIT: 3\n   - UUID: 4\n   - IP_ADDRESS, IPV6: 5\n   - MAC_ADDRESS: 6\n   - HEX_COLOR: 7\n   - DOCKER_SHA: 8\n   - FILE_PATH: 9\n   - MARKDOWN_URL: 10\n   - DIFF_*: 11\n   - HEX_ADDRESS: 12\n   - IPFS_HASH: 13\n   - LARGE_NUMBER: 20 (lowest priority - very generic)\n   ```\n\n3. **Pattern Declaration Order**: Earlier patterns in the regex dictionary win ties\n\n### Algorithm Behavior\n\n- **Non-overlapping matches** are all preserved\n- **Cross-line matches** are handled independently (no interference between lines)\n- **Adjacent matches** (touching but not overlapping) are both kept\n- **Partial overlaps** are resolved using the priority rules above\n\n### Examples\n\n```text\nInput: \"Contact user@github.com or visit https://github.com/user\"\n\nWithout overlap resolution:\n- \"user@github.com\" (EMAIL)\n- \"github.com\" (partial GITHUB pattern)  \n- \"https://github.com/user\" (URL)\n\nWith overlap resolution:\n- \"user@github.com\" (EMAIL wins over partial GITHUB)\n- \"https://github.com/user\" (URL, no overlap with EMAIL)\n```\n\nThis ensures that users see intuitive, non-redundant matches where the highlighted text exactly matches what gets copied to the clipboard.\n\n## Requirements\n\n- **tmux with capture-panel support** (required for pane content capture)\n- **Python \u003e= 3.6+**\n- **uv** (for dependency management)\n- **System clipboard utility**:\n  - macOS: `pbcopy` (built-in)\n  - Linux: `xclip` or `xsel`\n\nThe tool is designed primarily for tmux environments but can be used as a standalone CLI application when a tmux session is available.\n\n## How It Works\n\n1. When triggered, the script captures the current pane ID\n2. Creates a new tmux window running the capture tool\n3. The tool captures content from the original pane (not the new window)\n4. Displays interactive hints overlaid on the captured content\n5. User selects text using keyboard hints\n6. Selected text is copied to clipboard\n7. Window closes after user confirmation\n\n## Supported Keyboard Layouts\n\ntmux-capture supports multiple keyboard layouts, maintaining compatibility with tmux-thumbs configurations to ease migration:\n\n- **vim-movement**: `hjklwbef` (default) - Vim navigation keys\n- **vim-homerow**: `hjklasdfg` - Vim keys + homerow\n- **qwerty-homerow**: `asdfjklgh` - QWERTY homerow keys\n- **dvorak**: `aoeuqjkx...` - Dvorak keyboard layout\n- **colemak**: `arstqwfp...` - Colemak keyboard layout\n- **numeric**: `1234567890` - Number keys only\n\nThese layouts are designed to be familiar to tmux-thumbs users, allowing for seamless migration while providing optimal hint generation using an advanced greedy algorithm.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Development\n\n### Prerequisites\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) package manager\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/user/tmux-capture.git\ncd tmux-capture\n\n# Install dependencies\nuv sync --group dev\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Run linting\nmake lint\n\n# Format code\nmake format\n\n# Run all checks\nmake check\n\n# Clean generated files\nmake clean\n```\n\nOr use uv directly:\n\n```bash\n# Install dev dependencies\nuv sync --group dev\n\n# Run tests\nuv run pytest tests\n\n# Run tests with coverage\nuv run pytest tests --cov=tmux-capture --cov-report=term-missing --cov-report=html:htmlcov\n\n# Run linting\nuv run ruff check .\n\n# Format code\nuv run ruff format .\n```\n\n### Test Coverage\n\nThe project maintains **100% test coverage** with 147 comprehensive tests covering:\n\n- **Regex pattern matching** - Tests for all 18 supported patterns\n- **Overlap resolution** - 15 tests covering priority rules, edge cases, and complex scenarios\n- **Hint generation** - Tests for optimal algorithm with all keyboard layouts\n- **Content grouping** - Tests for reducing hint count with duplicate content\n- **ANSI handling** - Tests for terminal escape sequence processing\n- **Tmux integration** - Mocked tests for tmux command execution\n- **Clipboard operations** - Cross-platform clipboard functionality tests\n- **Terminal control** - Tests for TTY detection and /dev/tty fallback logic\n- **Edge cases** - Comprehensive coverage of boundary conditions and error scenarios\n\n## Contributing\n\nIssues and pull requests are welcome. This project aims to be a simple, maintainable alternative to tmux-thumbs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftizee%2Ftmux-capture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftizee%2Ftmux-capture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftizee%2Ftmux-capture/lists"}