gotomux

README

gotomux

go to mux, (yet) another fuzzy tmux session picker with presets, shapes, zoxide.

Forget about tmux and just jump into work: live sessions, saved presets, with zoxide paths, and sticky shapes reapplied on new projects.

Install

Arch Linux:

yay -S gotomux                            # or paru, pamac,...
systemctl --user enable --now gotomuxd    # daemon for instant cold start

Go (any platform):

go install github.com/fm39hz/gotomux@latest
# binary: $(go env GOPATH)/bin/gotomux
# optional daemon:
go install github.com/fm39hz/gotomux/cmd/gotomuxd@latest

From source:

git clone https://github.com/fm39hz/gotomux.git && cd gotomux
make install           # go install CLI
make install-all       # CLI + daemon + systemd unit + enable
# or: make build && ./gotomux
# or: make pkg         # Arch: dist/*.pkg.tar.zst

Requires: tmux, zoxide (optional) Optional: Nerd Font (icons, or GOTOMUX_ASCII=1)

Usage

gotomux             # interactive picker (auto-detect daemon)
gotomux -f [name]   # freeze session
gotomux -e [name]   # edit preset in $EDITOR
gotomux -h          # show help

The picker opens instantly. Type to filter, Enter to connect.

Daemon (gotomuxd)

Optional background service for faster cold start and automatic reranking supported telemetry.

systemctl --user enable --now gotomuxd

Gotomux auto-detects the daemon on startup. If absent, it will falls back to standalone mode (works identically, slightly slower cold start).

Keybind

Picker

Key	Action
type	filter (diacritics folded)
enter	connect
ctrl-n / ctrl-p	next / prev
ctrl-u / ctrl-w	clear query / delete word
ctrl-x	kill active session
ctrl-f	freeze into preset + shape
ctrl-t	set sticky shape for new projects
ctrl-e / ctrl-d	edit / delete preset
esc / ctrl-c	cancel
?	toggle help

Shell

This is the setup i use for myself, adapt into your own shell config if needed

# nushell
$env.config.keybindings ++= [{
  name: launch_gotomux
  modifier: control
  keycode: char_b
  mode: [emacs, vi_normal, vi_insert]
  event: { send: executehostcommand, cmd: "gotomux" }
}]

Tmux popup

bind-key C-b display-popup -E -w 80% -h 70% "gotomux"
bind-key C-e display-popup -E -w 90% -h 90% "gotomux -e"
bind-key -n C-f run-shell "gotomux -f >/dev/null 2>&1; tmux display-message 'Froze #{session_name}'"

Behaviour

Item	Enter
Active	attach / switch
Preset	load if missing, then attach
Create / Zoxide	live? attach : same-name preset? load : unfreeze sticky shape into project root

Shapes

A shape is cockpit essence (no paths, no pixel dumps). Freeze saves a full instance, and a shape is derived from it (topology + tools only). Sticky shapes are used for new projects via Create/Zoxide.

{
  "id": "shape-2942bbbd21e65a14",
  "label": "nvim+v2+yazi",
  "windows": [
    { "fork": "1||nvim", "name": "editor", "panes": [{ "cmd": "nvim" }] },
    {
      "fork": "2|even-vertical|",
      "name": "shell",
      "split": "even-vertical",
      "panes": [{}, {}]
    },
    { "fork": "1||yazi", "name": "files", "panes": [{ "cmd": "yazi" }] }
  ]
}

The fork string is a window essence fingerprint (panes|split|tools). Common patterns accumulate hit counts in the DB and can be composed into new shapes automatically.

Data

Path	Contents
$XDG_CONFIG_HOME/gotomux/shapes/<label>--<id8>.json	shape backup (auto-reconciled)
$XDG_DATA_HOME/gotomux/state.db	presets, shapes, usage, forks
$XDG_DATA_HOME/gotomux/gotomuxd.sock	daemon IPC (if running)

Ranking

Sources is form into a space × time matrix ranking

	Here	Anywhere
Future	Create	Zoxide
Present	—	Active
Past	—	Preset

Sort: tier > recency > cooccur > kind > detail > busy > pathQ > idx. Same formula everywhere, environment only changes inputs:

• Inside tmux (ctxSession set): items matching the current session name or path are excluded; co-occurrence overlay active.
• Outside tmux: all items visible; co-occurrence = 0.

"Just left" surfaces via recency.

Env

Variable	Effect
GOTOMUX_ASCII=1	TUI without Nerd Font icons
GOTOMUX_NERD=1	force nerd icons
EDITOR / VISUAL	preset edit (-e / ctrl-e)

Roadmap

Local first.

• Sources: create / tmux / preset / zoxide
• Freeze / load, sticky shapes, placement + fork learning
• Shape labels, config reconcile, product JSON (split / tools)
• go install / CI / local Arch package
• AUR release
• Remote tmux as one pool (tmux@host; server: tmux + ssh only)
• Polish everyday use until boring

Dev

make help && make test

Acknowledgements

tmux: Obviously, what do you expect? zoxide: Smart directory jump Bubble Tea: TUI library fzf: Fuzzy match core engine modernc sqlite: Go version of Sqlite gopsutil: psutil for Go projectdetect: Detect project type go-devicons: Nerd font icon

License

MIT