Skip to content

docs: modernize the README #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hmmhmmhm merged 2 commits into from
Jul 19, 2026
Merged

docs: modernize the README #1

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b8d59f7
docs: modernize the README
hmmhmmhm Jul 19, 2026
7fe2c84
docs: clarify setup troubleshooting
hmmhmmhm Jul 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 87 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,85 @@
<div align="center">

# tmux-attach-browser

**Choose or create a tmux session with one command.**

[![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)
[![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)

</div>

## Install

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
```

Browse, create, and enter tmux sessions with one command: `tab`.
The installer verifies the release checksum and places `tab` in `~/.local/bin`. It never runs `sudo`.

## Run `tab`

```text
tmux sessions
$ tab

tmux sessions

4 sessions

> work
3 windows | 1 attached | active 2026-07-19 14:03:00
│ work
│ 3 windows | 1 attached | active 2026-07-19 18:32:26

personal-agent
2 windows | detached | active 2026-07-19 18:31:07

api
2 windows | detached | active 2026-07-19 11:42:00
2 windows | detached | active 2026-07-19 18:27:44

docs
1 window | detached | active 2026-07-19 18:20:03

↑/k up ↓/j down / filter n new session r refresh ? more
↑/k up • ↓/j down • / filter • n new session • r refresh • q quit • ? 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.
That is the whole workflow:

## Features
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.

- 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.
To skip the browser and open a named session directly:

## Requirements
```sh
tab work
```

`tab` controls an existing tmux installation. Install tmux first:
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` | 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 |
| `?` | Show or hide expanded help |
| Esc | Cancel filtering or session creation; quit from the session list |
| `q`, Ctrl+C | Quit |

<details>
<summary><strong>Install tmux</strong></summary>

```sh
# macOS
brew install tmux

# Ubuntu or Debian
# Ubuntu or Debian, including WSL2
sudo apt update && sudo apt install tmux

# Fedora
Expand All @@ -48,133 +89,67 @@ sudo dnf install tmux
sudo pacman -S tmux
```

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.

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.
</details>

## Install
<details>
<summary><strong>Other installation options</strong></summary>

### macOS, Linux, and Windows WSL2
Choose another writable installation directory:

```sh
curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR="$HOME/bin" 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`:
Add the directory to your `PATH` if your shell does not already include it.

Install with Go 1.25 or newer:

```sh
curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR=/usr/local/bin sh
go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest
```

The installer never runs `sudo` automatically.

### Native Windows PowerShell

Use this only when tmux is already available in the same environment:
Native Windows PowerShell is intended for MSYS2 or Cygwin environments where `tmux.exe` is already available:

```powershell
curl.exe -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```

The default destination is `$HOME\.local\bin\tab.exe`. Set `TAB_INSTALL_DIR` before running the command to change it.
WSL2 remains the recommended Windows setup.

### Go
</details>

With Go 1.25 or newer:
<details>
<summary><strong>Troubleshooting</strong></summary>

```sh
go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest
```
### `tab: command not found`

## Usage
The default installer destination is `~/.local/bin`. Add it to your shell profile, then open a new terminal:

```sh
# Open the session browser
tab

# Attach directly without opening the browser
tab work

# Print version or help
tab --version
tab --help
export PATH="$HOME/.local/bin:$PATH"
```

### 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 |
| `/` | Filter sessions by name |
| `r` | Refresh the session list |
| `?` | Expand or collapse 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.

## How it works

`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.
### `tmux is not installed or is not on PATH`

Outside tmux, selection runs:
Install tmux using the commands above, then confirm that `tmux -V` works in the same terminal.

```sh
tmux attach-session -t SESSION
```

Inside tmux, it runs:
### `tab: connect to session: exit status 1`

```sh
tmux switch-client -t SESSION
```
The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting.

New sessions are created detached with `tmux new-session -d -s SESSION -c CURRENT_DIRECTORY` and attached after the UI exits.
</details>

## Build and test
<details>
<summary><strong>Build and verify</strong></summary>

```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
```

Additional checks:

```sh
sh scripts/test-install.sh
sh scripts/tmux-smoke.sh
goreleaser check
goreleaser release --snapshot --clean
```

## Troubleshooting

### `tmux is not installed or is not on PATH`

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`

The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting.

### `$HOME/.local/bin` is not on PATH

Add this line to your shell profile:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and focused feature proposals are welcome.

## License
</details>

[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).