From b8d59f7e8d042b67eca3f1aa3fb7081f9b7c98ee Mon Sep 17 00:00:00 2001 From: hmmhmmhm Date: Sun, 19 Jul 2026 21:01:20 +0900 Subject: [PATCH 1/2] docs: modernize the README --- README.md | 190 ++++++++++++++++++++---------------------------------- 1 file changed, 71 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index 2da5d65..b4e39c2 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,132 @@ -# tmux-attach-browser - -[![CI](https://github.com/hmmhmmhm/tmux-attach-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/hmmhmmhm/tmux-attach-browser/actions/workflows/ci.yml) -[![Release](https://img.shields.io/github/v/release/hmmhmmhm/tmux-attach-browser)](https://github.com/hmmhmmhm/tmux-attach-browser/releases) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) - -Browse, create, and enter tmux sessions with one command: `tab`. - -```text -tmux sessions - -> work - 3 windows | 1 attached | active 2026-07-19 14:03:00 - - api - 2 windows | detached | active 2026-07-19 11:42:00 - - ↑/k up ↓/j down / filter n new session r refresh ? more -``` - -`tab` is a focused terminal UI built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and the Bubbles [list](https://github.com/charmbracelet/bubbles/tree/main/list) and [textinput](https://github.com/charmbracelet/bubbles/tree/main/textinput) components. - -## Features - -- Fuzzy-search current tmux sessions. -- See window count, attached clients, and recent activity. -- Attach with Enter. -- Create a session in the current directory with `n`. -- Refresh without leaving the browser. -- Switch clients when already inside tmux, avoiding nested sessions. -- Install verified release binaries on macOS, Linux, and Windows. - -## Requirements - -`tab` controls an existing tmux installation. Install tmux first: - -```sh -# macOS -brew install tmux - -# Ubuntu or Debian -sudo apt update && sudo apt install tmux +
-# Fedora -sudo dnf install tmux +# tmux-attach-browser -# Arch Linux -sudo pacman -S tmux -``` +**Choose or create a tmux session with one command.** -Windows 10 and 11 are supported through WSL2. Run `wsl --install`, open the installed Linux distribution, install tmux there, and then use the Linux installation command below. +[![CI](https://github.com/hmmhmmhm/tmux-attach-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/hmmhmmhm/tmux-attach-browser/actions/workflows/ci.yml) +[![Release](https://img.shields.io/badge/release-v0.1.0-blue)](https://github.com/hmmhmmhm/tmux-attach-browser/releases/latest) +[![Go](https://img.shields.io/badge/go-1.25-blue)](go.mod) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -The native Windows binary is provided for advanced MSYS2 or Cygwin environments where `tmux.exe` is already on PATH. WSL2 is the tested and recommended Windows setup. +
## Install -### macOS, Linux, and Windows WSL2 +Already have [tmux](https://github.com/tmux/tmux) on your `PATH`? Install the latest release on macOS, Linux, or Windows WSL2: ```sh curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | sh ``` -The installer downloads the latest release, verifies its SHA-256 checksum, and places `tab` in `$HOME/.local/bin`. Choose another directory with `TAB_INSTALL_DIR`: +The installer verifies the release checksum and places `tab` in `~/.local/bin`. It never runs `sudo`. -```sh -curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR=/usr/local/bin sh -``` +## Run `tab` -The installer never runs `sudo` automatically. +```text +$ tab -### Native Windows PowerShell + tmux sessions -Use this only when tmux is already available in the same environment: + 4 sessions -```powershell -curl.exe -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command - -``` +│ work +│ 3 windows | 1 attached | active 2026-07-19 18:32:26 -The default destination is `$HOME\.local\bin\tab.exe`. Set `TAB_INSTALL_DIR` before running the command to change it. + personal-agent + 2 windows | detached | active 2026-07-19 18:31:07 -### Go + api + 2 windows | detached | active 2026-07-19 18:27:44 -With Go 1.25 or newer: + docs + 1 window | detached | active 2026-07-19 18:20:03 -```sh -go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest + ↑/k up • ↓/j down • / filter • n new session • r refresh • q quit • ? more ``` -## Usage +That is the whole workflow: -```sh -# Open the session browser -tab +1. Run `tab` to see your tmux sessions. +2. Select a session and press Enter to enter it. +3. Press `n` to create a session in the current directory. -# Attach directly without opening the browser -tab work +To skip the browser and open a named session directly: -# Print version or help -tab --version -tab --help +```sh +tab work ``` -### Keys +When `tab` runs inside tmux, it switches the current client to your chosen session instead of nesting another tmux client. + +## Keys | Key | Action | | --- | --- | -| Up, Down, `j`, `k` | Move through sessions | -| Enter | Attach to the selected session | -| `n` | Create a new session in the current directory | +| Up, Down, `j`, `k` | Select a session | +| Enter | Enter the selected session | +| `n` | Create a session in the current directory | | `/` | Filter sessions by name | | `r` | Refresh the session list | -| `?` | Expand or collapse help | +| `?` | Show or hide expanded help | | Esc | Cancel filtering or session creation | | `q`, Ctrl+C | Quit | -Session names cannot be blank or contain `:` or `.`. tmux rewrites or interprets these characters in target names, so `tab` rejects them before creating a session. +
+Install tmux -## How it works +```sh +# macOS +brew install tmux -`tab` asks tmux for a tab-separated session list, then renders it through the Bubbles list component. Selecting an existing session exits Bubble Tea before starting the interactive tmux client, so the terminal is restored correctly. +# Ubuntu or Debian, including WSL2 +sudo apt update && sudo apt install tmux -Outside tmux, selection runs: +# Fedora +sudo dnf install tmux -```sh -tmux attach-session -t SESSION +# Arch Linux +sudo pacman -S tmux ``` -Inside tmux, it runs: +
-```sh -tmux switch-client -t SESSION -``` +
+Other installation options -New sessions are created detached with `tmux new-session -d -s SESSION -c CURRENT_DIRECTORY` and attached after the UI exits. - -## Build and test +Choose a different installation directory: ```sh -git clone https://github.com/hmmhmmhm/tmux-attach-browser.git -cd tmux-attach-browser -go test ./... -go test -race ./... -go vet ./... -go build -o tab ./cmd/tab +curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR=/usr/local/bin sh ``` -Additional checks: +Install with Go 1.25 or newer: ```sh -sh scripts/test-install.sh -sh scripts/tmux-smoke.sh -goreleaser check -goreleaser release --snapshot --clean +go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest ``` -## Troubleshooting - -### `tmux is not installed or is not on PATH` +Native Windows PowerShell is intended for MSYS2 or Cygwin environments where `tmux.exe` is already available: -Install tmux using the platform instructions above, then confirm `tmux -V` works in the same terminal where you run `tab`. - -### `tab: connect to session: exit status 1` +```powershell +curl.exe -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command - +``` -The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting. +WSL2 remains the recommended Windows setup. -### `$HOME/.local/bin` is not on PATH +
-Add this line to your shell profile: +
+Build and verify ```sh -export PATH="$HOME/.local/bin:$PATH" +git clone https://github.com/hmmhmmhm/tmux-attach-browser.git +cd tmux-attach-browser +go test -race ./... +go vet ./... +go build -o tab ./cmd/tab ``` -## Contributing - -See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and focused feature proposals are welcome. - -## License +
-[MIT](LICENSE) +Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea). Contributions are described in [CONTRIBUTING.md](CONTRIBUTING.md). Licensed under the [MIT License](LICENSE). From 7fe2c8419ad6233c995b23037cbaeff3e4fbc07e Mon Sep 17 00:00:00 2001 From: hmmhmmhm Date: Sun, 19 Jul 2026 21:12:10 +0900 Subject: [PATCH 2/2] docs: clarify setup troubleshooting --- README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b4e39c2..363229c 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ When `tab` runs inside tmux, it switches the current client to your chosen sessi | `/` | Filter sessions by name | | `r` | Refresh the session list | | `?` | Show or hide expanded help | -| Esc | Cancel filtering or session creation | +| Esc | Cancel filtering or session creation; quit from the session list | | `q`, Ctrl+C | Quit |
@@ -94,12 +94,14 @@ sudo pacman -S tmux
Other installation options -Choose a different installation directory: +Choose another writable installation directory: ```sh -curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR=/usr/local/bin sh +curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR="$HOME/bin" sh ``` +Add the directory to your `PATH` if your shell does not already include it. + Install with Go 1.25 or newer: ```sh @@ -116,6 +118,27 @@ WSL2 remains the recommended Windows setup.
+
+Troubleshooting + +### `tab: command not found` + +The default installer destination is `~/.local/bin`. Add it to your shell profile, then open a new terminal: + +```sh +export PATH="$HOME/.local/bin:$PATH" +``` + +### `tmux is not installed or is not on PATH` + +Install tmux using the commands above, then confirm that `tmux -V` works in the same terminal. + +### `tab: connect to session: exit status 1` + +The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting. + +
+
Build and verify