Session Picker

A simple, configurable terminal session picker TUI

---

sp is a minimal TUI for quickly selecting and launching shell sessions. Perfect for developers who work across multiple remote hosts daily and want a fast, keyboard-driven way to pick their session when opening a new terminal.

Why not just bash + fzf?

Look, this whole thing could've been a 5-line bash script with fzf. But I spent 40 minutes digging through fzf flags trying to get the exact look I wanted (centered, minimal, right colors, no chrome). Then I said "screw it" and vibe-coded this entire project from an empty directory in about 10 minutes with Claude Code. Sometimes the "proper" tool isn't the fastest path.

Features

• Centered, minimal TUI with fuzzy search
• Configure multiple shells/sessions via YAML
• Set a default session (always appears first)
• Keyboard-driven navigation
• Hidden search box by default (just start typing) - optionally visible via config
• XDG Base Directory compliant config

Installation

Using Go

go install github.com/arch-err/sp@latest

Manual Installation

git clone https://github.com/arch-err/sp.git
cd sp
go build -o sp .
mv sp ~/.local/bin/  # or anywhere in your PATH

From Releases

Download the latest binary from the releases page.

Usage

sp              # Launch the session picker
sp help         # Show help
sp config       # Open config in $EDITOR
sp config -v    # Validate config
sp version      # Show version

Controls

Key	Action
Up/Down	Navigate
Enter	Select session
Esc	Clear search
Type	Fuzzy search (works even when search box is hidden)
Ctrl+C	Quit

Configuration

Config is stored at $XDG_CONFIG_HOME/session-picker/config.yaml (defaults to ~/.config/session-picker/config.yaml).

Run sp config to create and edit your config file.

Example Config

# Show the search input box (fuzzy search works regardless)
show_search: false

shells:
  - name: "Local"
    command: "exec $SHELL"
    default: true
  - name: "Desktop"
    command: "ssh user@desktop"
  - name: "Work"
    command: "ssh me@work.example.com"
  - name: "Production"
    command: "ssh admin@prod.example.com"

Config Options

Global Options

Field	Type	Default	Description
show_search	bool	false	Show the search input box. Fuzzy search works regardless - just start typing. When hidden, the UI is cleaner and more minimal.

Shell Options

Field	Type	Required	Description
name	string	Yes	Display name for the session
command	string	Yes	Command to execute when selected
default	bool	No	If true, this session appears first (only one allowed)

Terminal Startup

To use sp as your terminal's startup command, set it as your shell's initial command or in your terminal emulator's config:

Ghostty:

command = /path/to/sp

Alacritty:

shell:
  program: /path/to/sp

Kitty:

shell /path/to/sp

WezTerm:

config.default_prog = { '/path/to/sp' }

License

MIT