{"id":32657664,"url":"https://github.com/steipete/tmuxwatch","last_synced_at":"2026-05-29T16:31:28.196Z","repository":{"id":319783419,"uuid":"1079578265","full_name":"steipete/tmuxwatch","owner":"steipete","description":"A simple TUI to watch tmux sessions","archived":false,"fork":false,"pushed_at":"2026-05-15T04:02:47.000Z","size":350,"stargazers_count":200,"open_issues_count":0,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-15T05:46:57.472Z","etag":null,"topics":["go","tmux","tui"],"latest_commit_sha":null,"homepage":"https://tmuxwatch.com","language":"Go","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/steipete.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2025-10-20T03:46:31.000Z","updated_at":"2026-05-15T04:02:51.000Z","dependencies_parsed_at":"2025-12-20T05:03:35.037Z","dependency_job_id":null,"html_url":"https://github.com/steipete/tmuxwatch","commit_stats":null,"previous_names":["steipete/tmuxwatch"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/steipete/tmuxwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steipete%2Ftmuxwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steipete%2Ftmuxwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steipete%2Ftmuxwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steipete%2Ftmuxwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steipete","download_url":"https://codeload.github.com/steipete/tmuxwatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steipete%2Ftmuxwatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33662205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["go","tmux","tui"],"created_at":"2025-10-31T12:30:48.295Z","updated_at":"2026-05-29T16:31:28.187Z","avatar_url":"https://github.com/steipete.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmuxwatch 👀 - Lightweight TUI to watch tmux sessions\n\n`tmuxwatch` is a Charmbracelet-powered dashboard that keeps eyes on every tmux session, window, and pane without ever leaving the terminal.\n\n## Highlights\n- **Live tmux snapshot**: Polls `list-sessions`, `list-windows`, and `list-panes`, stitches the hierarchy together, and shows the latest capture-pane output per session.\n- **Tab-aware layout**: The strip lists the grid plus every visible tmux session; click or `shift+left/right` to jump tabs, `ctrl+m` toggles full-screen, and `esc` returns to the grid.\n- **Keyboard \u0026 mouse aware**: `/` to search, arrow/PageUp/PageDown to scroll, collapse cards with `z`/`Z`, maximise via `ctrl+m` or the `[^]` control, `X` to kill a focused stale session, `ctrl+X` to clean *all* stale sessions, and mouse clicks/scrolls to focus, collapse, close cards, or switch tabs.\n- **Command palette (`ctrl+P`)**: Run actions (refresh, show hidden, clean stale) from a centered overlay.\n- **Automation friendly**: `--dump` prints the current tmux topology as JSON for scripts or debugging.\n\n## Install \u0026 Run\n```sh\n# Homebrew (recommended)\nbrew tap steipete/tap\nbrew install tmuxwatch\ntmuxwatch --version  # should print tmuxwatch 0.9\n\n# Updating later\nbrew update\nbrew upgrade tmuxwatch\n\n# Or install directly with Go tooling\ngo install github.com/steipete/tmuxwatch/cmd/tmuxwatch@latest\n\n# Nix/NixOS\nnix run github:steipete/tmuxwatch\n\n# Or add to your flake inputs for system integration\n# inputs.tmuxwatch.url = \"github:steipete/tmuxwatch\";\n# Then use: inputs.tmuxwatch.packages.${system}.default\n\n# best practice: spawn inside tmux so key bindings work as expected\ntmux new-session -d -s watch './gorunfresh --trace-mouse'\ntmux attach -t watch\n\n# prefer to run outside tmux?\n./gorunfresh --dump   # runs directly unless TMUXWATCH_FORCE_TMUX=1 is set\n./gorunfresh --watch  # starts poltergeist + polter --watch to auto-restart after successful builds\n./scripts/run-hot.sh  # single command that starts daemon in the background and launches tmuxwatch with hot reload\n```\nPress `q` (or double `ctrl+c`) to exit. Prefer running tmuxwatch in its own tmux session to keep the UI isolated from your workspaces. For local development you can substitute `./gorunfresh --debug-click 30,10 --trace-mouse` inside the session to replay a mouse event while inspecting BubbleZone logs.\n\n## CLI Flags\n- `--interval \u003cduration\u003e`: tmux poll frequency (default `1s`).\n- `--tmux \u003cpath\u003e`: tmux binary to execute (defaults to `$PATH`).\n- `--dump`: emit the current snapshot as indented JSON and exit.\n- `--version`: print the build/version string.\n\n## Keyboard \u0026 Mouse Cheat Sheet\n```\n/ or ctrl+f        open search; type to filter sessions/windows/panes\nesc                clear search, close palette, or leave detail view\nshift+left/right   switch tabs\nH                  show hidden sessions\nX                  kill the focused stale session\nctrl+X             kill every stale session\nctrl+P             open/close the command palette\nctrl+m             maximise/restore the focused session\nz / Z              collapse focused session / expand all sessions\nq / ctrl+c         quit (double ctrl+c quits even if pane is alive)\nmouse              click `[^]/[v]` to maximise/restore, `[-]/[+]` to collapse/expand, `[x]` to hide; scroll to browse logs\n```\n\n## Architecture\n- `cmd/tmuxwatch/`: CLI entry point, flag parsing, Bubble Tea program setup.\n- `internal/tmux/`: thin wrapper over the tmux binary (snapshot capture, capture-pane, send-keys, kill-session, option queries).\n- `internal/ui/`: Bubble Tea model split into focused files (`model`, `update`, `handlers`, `cards`, `status`, `palette`, `overlay`, etc.).\n- `docs/`: contributor docs (`AGENTS.md`, `idiomatic-go.md`).\n\nThe UI intentionally avoids third-party “magic”; it leans on Bubble Tea + Lip Gloss primitives so behaviour is explicit.\n\n## Development Workflow\nUse the pnpm scripts to mirror the Go tooling:\n```sh\npnpm format  # gofumpt -w .\npnpm lint    # golangci-lint run\npnpm test    # go test ./...\npnpm build   # go build ./cmd/tmuxwatch\npnpm start   # runs ./gorunfresh (prefer inside tmux)\n```\n\nYou can still call the Go targets directly:\n```sh\n# format + lint\nmake fmt\nmake lint\n\n# run tests (includes table-driven/unit tests in internal/ui and internal/tmux)\ngo test ./...\n\n# fresh rebuild \u0026 run inside tmux (guards against outside usage)\n./gorunfresh --dump  # validate tmux JSON snapshot; respects TMUXWATCH_FORCE_TMUX\n\ngo run ./cmd/tmuxwatch --dump  # (inside tmux) validate tmux JSON snapshot for debugging\n```\nGuidelines live in `docs/idiomatic-go.md`; treat it as required reading. Key points:\n- Always run the app inside tmux; tests that touch tmux spawn/destroy their own sessions.\n- Run `gofumpt`, `golangci-lint`, and `govulncheck` before opening a PR.\n- Table-driven tests go beside their packages (`*_test.go`); fixtures live under `testdata/`.\n- The `gorunfresh` helper clears cache and re-runs the app but refuses to execute unless you launch it from within tmux.\n\n## Roadmap (short list)\n- Theming + palette customization (Catppuccin/Dracula).\n- Configurable capture depth \u0026 poll interval via config file.\n- Pane interaction history and saved layouts.\n\n## License\nReleased under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteipete%2Ftmuxwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteipete%2Ftmuxwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteipete%2Ftmuxwatch/lists"}