Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
58 changes: 19 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,59 @@
# tmux-pilot

A TUI for managing tmux sessions. One keybinding to see, create, rename, switch, and kill sessions.
A minimal TUI for managing tmux sessions. Pick → execute → done.

[![CI](https://github.com/blockful/tmux-pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/blockful/tmux-pilot/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

```
┌─ tmux-pilot ──────────────────────────────┐
│ │
│ ● main 3 windows attached │
│ ○ api-server 1 window detached │
│ ○ notes 2 windows detached │
│ ○ scratch 1 window detached │
│ │
│ [enter] switch [n] new [r] rename │
│ [x] kill [q] quit
│ [x] kill [d] detach [q] quit
│ │
│ tip: Ctrl-b d to detach from tmux
│ tip: Ctrl-b d to detach
└───────────────────────────────────────────┘
```

## Install

### Go

```bash
go install github.com/blockful/tmux-pilot/cmd@latest
```

### Download binary

Grab the latest from [Releases](https://github.com/blockful/tmux-pilot/releases) for your platform (Linux/macOS, amd64/arm64).

### Build from source

```bash
git clone https://github.com/blockful/tmux-pilot.git
cd tmux-pilot
go build -o tmux-pilot ./cmd
```
Or download from [Releases](https://github.com/blockful/tmux-pilot/releases).

## Setup

Automatic (adds keybinding to `~/.tmux.conf` and reloads):
Add to `~/.tmux.conf`:

```bash
tmux-pilot --setup
bind s display-popup -E -w 60% -h 50% "tmux-pilot"
```

Or manual — add to `~/.tmux.conf`:
Optional alias in `~/.bashrc` or `~/.zshrc`:

```bash
bind s display-popup -E -w 60% -h 50% "tmux-pilot"
alias tp="tmux-pilot"
```

Then reload: `tmux source-file ~/.tmux.conf`

Also works standalone outside tmux — it will `attach-session` instead of `switch-client`.

## Keybindings

| Key | Action |
|-----|--------|
| `↑`/`↓` `j`/`k` | Navigate |
| `enter` | Switch to session |
| `n` | New session |
| `r` | Rename session |
| `x` | Kill session (with confirmation) |
| `q` / `esc` | Quit |

## How it works

tmux-pilot shells out to the `tmux` binary for all operations. No library dependencies on tmux internals. When running inside tmux it uses `switch-client`; outside it uses `attach-session`.
tmux-pilot is a thin picker. It shows your sessions, you choose an action, it exits and runs the tmux command:

| Key | Runs |
|-----|------|
| `enter` | `tmux switch-client -t <name>` |
| `n` | `tmux new-session -d -s <name> && tmux switch-client -t <name>` |
| `r` | `tmux rename-session -t <old> <new>` |
| `x` | `tmux kill-session -t <name>` |
| `d` | `tmux detach-client` |
| `q`/`esc` | exit |

Built with [BubbleTea](https://github.com/charmbracelet/bubbletea) + [LipGloss](https://github.com/charmbracelet/lipgloss).
Navigation: `↑`/`↓` or `j`/`k`

## License

Expand Down
52 changes: 33 additions & 19 deletions cmd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@ import (
"fmt"
"os"

"github.com/blockful/tmux-pilot/internal/setup"
"github.com/blockful/tmux-pilot/internal/tmux"
"github.com/blockful/tmux-pilot/internal/tui"
tea "github.com/charmbracelet/bubbletea"
)

// Set by goreleaser ldflags.
var (
version = "dev"
commit = "unknown"
Expand All @@ -22,30 +20,46 @@ func main() {
switch os.Args[1] {
case "--version", "-v":
fmt.Printf("tmux-pilot %s (%s, %s)\n", version, commit, date)
os.Exit(0)
case "--setup":
if err := setup.Run(); err != nil {
fmt.Fprintf(os.Stderr, "Setup failed: %v\n", err)
os.Exit(1)
}
os.Exit(0)
return
}
}

client := tmux.NewRealClient()
model := tui.New(client, setup.NeedsSetup(), setup.Run)
// 1. Fetch sessions
sessions, err := tmux.ListSessions()
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}

opts := []tea.ProgramOption{
// WithInputTTY reads from /dev/tty directly, bypassing stdin.
// This prevents tmux from mangling escape sequences when
// running inside display-popup or nested terminals.
tea.WithInputTTY(),
tea.WithAltScreen(),
// 2. Show picker
model := tui.New(sessions)
p := tea.NewProgram(model, tea.WithAltScreen(), tea.WithInputTTY())
result, err := p.Run()
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}

p := tea.NewProgram(model, opts...)
if _, err := p.Run(); err != nil {
// 3. Execute action after TUI exits
action := result.(*tui.Model).Action()
if err := execute(action); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}

func execute(a tui.Action) error {
switch a.Kind {
case "switch":
return tmux.SwitchOrAttach(a.Target)
case "new":
return tmux.NewSession(a.Target)
case "rename":
return tmux.RenameSession(a.Target, a.NewName)
case "kill":
return tmux.KillSession(a.Target)
case "detach":
return tmux.Detach()
}
return nil // user quit without action
}
107 changes: 0 additions & 107 deletions internal/setup/setup.go

This file was deleted.

109 changes: 0 additions & 109 deletions internal/setup/setup_test.go

This file was deleted.

Loading
Loading