{"id":47828210,"url":"https://github.com/cristianoliveira/tmux-intray","last_synced_at":"2026-04-03T20:04:34.782Z","repository":{"id":335848338,"uuid":"1146846219","full_name":"cristianoliveira/tmux-intray","owner":"cristianoliveira","description":"A notification inbox solution for tmux, because things happen while you're not looking now. Put in the intray and check at your own pace. 🤖 📨 👨‍💻","archived":false,"fork":false,"pushed_at":"2026-03-29T10:48:49.000Z","size":7830,"stargazers_count":5,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T10:59:17.821Z","etag":null,"topics":["agentic-ai","agentic-coding","claude-code","event-management","inbox","mail","multi-agent","notifications","opencode","tmux"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cristianoliveira.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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-31T19:20:22.000Z","updated_at":"2026-03-29T09:55:39.000Z","dependencies_parsed_at":"2026-03-02T20:05:54.107Z","dependency_job_id":null,"html_url":"https://github.com/cristianoliveira/tmux-intray","commit_stats":null,"previous_names":["cristianoliveira/tmux-intray"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cristianoliveira/tmux-intray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Ftmux-intray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Ftmux-intray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Ftmux-intray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Ftmux-intray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cristianoliveira","download_url":"https://codeload.github.com/cristianoliveira/tmux-intray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Ftmux-intray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31374059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["agentic-ai","agentic-coding","claude-code","event-management","inbox","mail","multi-agent","notifications","opencode","tmux"],"created_at":"2026-04-03T20:04:33.997Z","updated_at":"2026-04-03T20:04:34.773Z","avatar_url":"https://github.com/cristianoliveira.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-intray\n[![CI](https://github.com/cristianoliveira/tmux-intray/actions/workflows/ci.yml/badge.svg)](https://github.com/cristianoliveira/tmux-intray/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/cristianoliveira/tmux-intray/branch/main/graph/badge.svg)](https://codecov.io/gh/cristianoliveira/tmux-intray)\n\n\u003cdiv style=\"display:flex\"\u003e\n    \u003cdiv\u003e\n        A quiet inbox for things that happen while you're not looking.\n        tmux-intray provides a persistent in-tmux in-tray where panes, windows, and scripts can drop messages and events without interrupting your flow. Instead of loud notifications or forced context switching.\n    \u003c/div\u003e\n    \u003cdiv\u003e\n      \u003cimg width=\"300\" height=\"300\" alt=\"tmux-intray-300\" src=\"https://github.com/user-attachments/assets/4fd9f030-9bb3-43a7-b800-c0d0f479e2a5\" align=\"right\" /\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\u003c/br\u003e\n\u003c/br\u003e\n\n**Work in Progress**\n\n\u003e [!WARNING]\n\u003e 🚧 This plugin is in active development at the moment. It started as an opencode plugin but grew into its own project.\nI use it on a daily basis, I'm a heavy tmux user and so far it works great! At this stage of development I can't promise there won't be\nbreaking changes.\n\nFor the guiding principles that inform all design decisions, see [Project Philosophy](docs/philosophy.md).\n\n## Summary\n\nQuick links to key sections:\n\n### Main Sections\n- [Installation Options](#installation-options)\n- [CLI Installation](#cli-installation)\n- [Tmux Plugin Installation](#tmux-plugin-installation)\n- [Hooks system](#hooks-system)\n- [Fzf Integration](#fzf-integration)\n- [Architecture Overview](#architecture-overview)\n- [Debugging](#debugging)\n- [Testing](#testing)\n- [Linting](#linting)\n- [License](#license)\n\n### Quick Start\n- **Full Setup (Recommended)**: Install CLI + Tmux Plugin via [One-click installation](#one-click-installation)\n- **CLI Only**: Install via [npm](#npm) or [Go](#go) for tmux-integrated use\n- **Plugin Only**: Install via [Tmux Plugin Manager](#using-tmux-plugin-manager-recommended) if CLI already installed\n\n## Basic Usage\n\n```bash\ntmux-intray add \"my message!\"\ntmux-intray list\ntmux-intray jump \u003cid\u003e\n\n```\n\n### Managing Notifications\nOnce messages arrive you can manage them with the following commands:\n```bash\ntmux-intray tui\n# or using fzf\ntmux-intray list | fzf | awk '{ print $1 }' | xargs -I {} tmux-intray jump {}\n```\n\n### Tmux Integration\nWe recommend attaching \u003cprefix\u003e + J to open TUI in popup window\n\n```bash\nbind-key -T prefix J run-shell \"tmux popup -E -h 50% -w 70% 'tmux-intray tui'\"\n```\n\nUsing `tmux-intray status` create a status bar in `.tmux.conf`:\n\n```bash\n# Shows the tmux-intray status panel\nset -g status-right \"#(tmux-intray status --format='📨 {{unread-count}}/{{total-count}}') %H:%M %a %d-%b-%y\"\n```\n\nSee [tmux.conf](tmux-intray.tmux) for a full example.\n\n## Installation Options\n\ntmux-intray has two main components that can be installed separately or together:\n\n1. **CLI (Command Line Interface)**: The core notification system that can be installed via package managers\n2. **Tmux Plugin**: Integration layer that provides key bindings, status bar updates, and pane tracking\n\n### Option 1: CLI + Tmux Plugin (Recommended)\n\nFor full functionality with tmux integration, install both components:\n\n#### One-click installation (curl/bash)\n\n```bash\n# Installs both CLI and tmux plugin\ncurl -fsSL https://raw.githubusercontent.com/cristianoliveira/tmux-intray/main/install.sh | bash\n```\n\nThis installs the CLI to `~/.local/bin` (or custom prefix) and the tmux plugin to `~/.local/share/tmux-plugins/tmux-intray`.\n\n#### Manual Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/cristianoliveira/tmux-intray.git ~/.local/share/tmux-plugins/tmux-intray\n\n# Add to your .tmux.conf\necho \"run '~/.local/share/tmux-plugins/tmux-intray/tmux-intray.tmux'\" \u003e\u003e ~/.tmux.conf\n\n# Reload tmux configuration\ntmux source-file ~/.tmux.conf\n```\n\n### Option 2: CLI Only\n\nInstall just the command-line interface for use within tmux sessions:\n\n#### Go (Recommended for Go users)\n\n```bash\ngo install github.com/cristianoliveira/tmux-intray@latest\n```\n\n#### Nix (Flakes)\n\n```bash\n# Run directly from the flake\nnix run github:cristianoliveira/tmux-intray\n\n# Or build and install locally\nnix build .#\nnix run .# -- --version\n\n# Install tmux-intray globally\nnix profile install github:cristianoliveira/tmux-intray\n```\n\n#### From Source\n\n```bash\ngit clone https://github.com/cristianoliveira/tmux-intray.git\ncd tmux-intray\nmake install\n```\n\n#### Manual Plugin Installation\n\n```bash\n# Clone just the plugin files\ngit clone https://github.com/cristianoliveira/tmux-intray.git ~/.local/share/tmux-plugins/tmux-intray\n\n# Add to .tmux.conf\necho \"run '~/.local/share/tmux-plugins/tmux-intray/tmux-intray.tmux'\" \u003e\u003e ~/.tmux.conf\n\n# Reload tmux\ntmux source-file ~/.tmux.conf\n```\n\n### Integrations With Code Agents\n\n- [OpenCode](opencode/plugins/opencode-tmux-intray) - See the readme\n- [Pi](pi/agent/extensions/tmux-intray) - See the Readme\n\n### CLI Commands\n\n```bash\n$ tmux-intray --help\n```\n\nSee the [CLI Reference](docs/cli/CLI_REFERENCE.md) for a complete list of commands and options.\n\n## Documentation\n\nComprehensive documentation is available:\n\n- [CLI Reference](docs/cli/CLI_REFERENCE.md) - Complete command reference\n- [Status Guide](docs/status-guide.md) - Template variables, presets, real-world examples, and troubleshooting\n- [Configuration Guide](docs/configuration.md) - All environment variables and settings (including TUI settings persistence)\n- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions\n- [Advanced Filtering Example](examples/advanced-filtering.sh) - Complex filter combinations\n- [Man page](man/man1/tmux-intray.1) - Traditional manual page (view with `man -l man/man1/tmux-intray.1`)\n\nDocumentation is automatically generated from the command-line help texts.\n\n### TUI Settings Persistence\n\nThe TUI automatically saves your preferences on exit:\n- **Settings file**: `~/.config/tmux-intray/tui.toml`\n- **Auto-save**: Settings are saved when you quit (q, :q, Ctrl+C)\n- **Reset settings**: Run `tmux-intray settings reset`\n- **View settings**: Run `tmux-intray settings show`\n\nSee [Configuration Guide](docs/configuration.md) for details on available settings.\n\nFor a comprehensive list of filters and detailed examples, see the [CLI Reference](docs/cli/CLI_REFERENCE.md) and the [advanced filtering example](examples/advanced-filtering.sh).\n\n### Hooks system\n\ntmux-intray supports a hooks system that allows you to execute custom scripts before and after notification events. This makes tmux-intray extensible and integratable with other systems.\n\n**Key features:**\n- **Hook points**: `pre-add`, `post-add`, `pre-dismiss`, `post-dismiss`, `cleanup`\n- **Configurable failure modes**: ignore, warn, or abort on hook failure\n- **Environment variables**: Provide notification context to hook scripts\n\n**Example hook script** (`~/.config/tmux-intray/hooks/post-add.sh`):\n```bash\n#!/bin/bash\n# Send notification to external system\ncurl -X POST https://api.example.com/notifications \\\n  -d \"message=$TMUX_INTRAY_MESSAGE\u0026level=$TMUX_INTRAY_LEVEL\"\n```\n\nSee more in the [hooks guide](docs/hooks.md)\n\n### Debugging\n\nEnable debug logging:\n```bash\nexport TMUX_INTRAY_LOG_LEVEL=debug\ntmux-intray add \"Test notification\"\n```\n\nLogs are written to stderr. For detailed debugging guidance, see the [Debugging Guide](./docs/debugging.md).\n\n### Getting More Help\n\nFor detailed troubleshooting and debugging scenarios:\n- **[Debugging Guide](./docs/debugging.md)** - Complete guide with examples for all common issues\n- **[Configuration Guide](./docs/configuration.md)** - All environment variables and config options\n- **[Troubleshooting Guide](./docs/troubleshooting.md)** - Additional solutions and tips\n\n## Fzf Integration\n\ntmux-intray works well with [fzf](https://github.com/junegunn/fzf) for interactive notification management. The `--format=table` output is structured and easy to parse.\n\n### Basic fzf Examples\n\n#### Interactive Notification Dismissal\nSelect a notification with fzf and dismiss it:\n```bash\ntmux-intray list --format=table | tail -n +4 | fzf --header-lines=0 --with-nth=2.. | awk '{print $1}' | xargs -I {} tmux-intray dismiss {}\n```\n\n#### Multi-Select Batch Dismissal\nSelect multiple notifications and dismiss them all:\n```bash\ntmux-intray list --format=table | tail -n +3 | fzf --multi --header-lines=0 --with-nth=2.. | awk '{print $1}' | xargs tmux-intray dismiss\n```\n\n#### Jump to Notification Pane\nSelect a notification and jump to its source pane:\n```bash\ntmux-intray list --format=table | tail -n +3 | fzf --header-lines=0 --with-nth=2.. | awk '{print $1}' | xargs -I {} tmux-intray jump {}\n```\n\n#### Fzf Preview with tmux Pane Context\nPreview the pane metadata and recent pane output (inside tmux):\n```bash\ntmux-intray list --format=table | tail -n +3 | fzf --header-lines=0 \\\n  --with-nth=2.. \\\n  --preview='tmux display-message -p -t {3} \"#{session_name}:#{window_index}.#{pane_index} #{pane_current_command} #{pane_current_path}\"; echo; tmux capture-pane -pt {3} -S -20' \\\n  --preview-window=right:60%:wrap \\\n  | awk '{print $1}' | xargs -I {} tmux-intray jump {}\n```\n\n## Architecture Overview\n\ntmux-intray is built with a modular architecture that separates concerns:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     tmux-intray System                       │\n├─────────────────┬───────────────────────────────────────────┤\n│   CLI Core      │           Tmux Integration                │\n│   (Go-based)    │        (tmux-intray.tmux)                 │\n├─────────────────┼───────────────────────────────────────────┤\n│ • Storage       │ • Key bindings (prefix+I, prefix+J)       │\n│ • Commands      │ • Status bar updates                      │\n│ • Hooks system  │ • Pane context capture                    │\n│ • Configuration │ • Environment setup                       │\n└─────────────────┴───────────────────────────────────────────┘\n                            │\n                     ┌──────┴──────┐\n                     │   tmux      │\n                     │  session    │\n                     └─────────────┘\n```\n\n### Core Components\n\n1. **Storage Layer**: SQLite database with transactional storage in `~/.local/state/tmux-intray/notifications.db`\n2. **Command Layer**: Individual command implementations in `cmd/*.go`\n3. **Tmux Integration**: Plugin loader in `tmux-intray.tmux` and status command (`tmux-intray status`)\n\n### Data Flow\n\n1. **Notification Creation**: `tmux-intray add` → storage layer → hooks execution\n2. **Notification Retrieval**: `tmux-intray list` → storage query → formatted output\n3. **Tmux Integration**: Plugin updates status bar via `@tmux_intray_active_count`\n4. **Pane Navigation**: `tmux-intray jump` uses captured pane IDs to navigate\n\n## Testing\n\nRun the test suite:\n```bash\nmake test\n# or directly\nbats tests/\n```\n\nPlugin tests (OpenCode integration) are located in `opencode/plugins/opencode-tmux-intray/` and can be run with:\n```bash\ncd opencode/plugins/opencode-tmux-intray \u0026\u0026 npm test\n```\n\n## Linting\n\nCheck code style:\n```bash\nmake lint\n```\n\n## License\n\ntmux-intray is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Additional Resources\n\n- [GitHub Repository](https://github.com/cristianoliveira/tmux-intray)\n- [Issue Tracker](https://github.com/cristianoliveira/tmux-intray/issues)\n- [Contributing Guidelines](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianoliveira%2Ftmux-intray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcristianoliveira%2Ftmux-intray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianoliveira%2Ftmux-intray/lists"}