Skip to content
tmux-companion

tmux.conf, starter

The file as it ships, docs/tmux.conf.starter.example.

Terminal window
# tmux-companion: a tmux.conf to start from
#
# Three example files ship, and this is the one to copy first:
#
#   tmux.conf.starter.example   this: the bar and the eight bindings worth
#                               having on day one, nothing else
#   tmux.conf.example           the bar alone, as one laptop runs it, with the
#                               measurements behind each line
#   tmux.conf.full.example      every feature on, with what each one costs
#
# Every line here is optional and every key is yours to move. The binary binds
# nothing on its own.
#
# ── Install order ───────────────────────────────────────────────────────────
#
# Binary first, then this file. The bar calls `tmux-companion status-right`,
# and against a binary without it the right-hand side is blank.
#
#   ./scripts/install.sh          # or: cargo build --release && sudo install ...
#   tmux-companion doctor         # can it see tmux, which config, which font
#   tmux source-file ~/.config/tmux/tmux.conf
#
# After an upgrade: `tmux-companion restart`. The daemon is one long-lived
# process, and a new binary on disk changes nothing until it is restarted.


# ── The bar ─────────────────────────────────────────────────────────────────
#
# status-style is not optional: the segments draw against colour233 and
# tmux's default green shows through everywhere they do not reach without it.
set -g  status-interval 1
set -g  status-style bg=colour233,fg=colour251
set -g  status-left  "#[fg=colour251,bg=colour236] #S #[fg=colour240,bg=colour233] %H:%M:%S "
set -g  status-left-length 80
set -g  status-right-length 150


# One `#()` for the whole right side: git status, bandwidth and battery,
# computed together in the daemon. Do not split it into three; tmux spawns a
# process per `#()` per second per attached client, and that spawn is the
# whole cost of the bar.
set -g  status-right "#(tmux-companion status-right --branch-max-len 40 #{pane_current_path})"


set -g window-status-format          "#I:#W#{?window_flags,#{window_flags}, }"
set -g window-status-current-format  "#I:#W#{?window_flags,#{window_flags}, }"
set -g window-status-separator       " "


# ── Bindings ────────────────────────────────────────────────────────────────
#
# The `-N "companion: <group> ..."` note on each one is not decoration. `keys`
# (the searchable key list) and `cheatsheet` show the bindings that carry it
# and nothing else, and the word after `companion:` picks the cheat sheet box:
# pane, window, session, project, go, copy, open, search, config, help.
# A binding without the note works as a key and is invisible to both.
#
# Two of these sit in the root table (`-n`), so they fire without the prefix
# and take Alt-s and Alt-a away from every program in the pane. Drop the `-n`
# to put them behind the prefix instead.


# Which project. Live sessions first, then the directories zoxide (or
# `[project] dirs_source`) knows. Picking a directory builds its session from
# `[[layout]]` in config.toml, or a plain shell when there is none.
# `display-popup -B` (tmux 3.3 and later) leaves tmux's own border off, because
# the pickers draw theirs. tmux 3.2 has no -B, so there the %else line binds
# the same popup with both borders.
%if "#{>=:#{version},3.3}"
bind -N "companion: project pick a project" -n M-s \
  display-popup -B -E -w 80% -h 70% "tmux-companion project"
%else
bind -N "companion: project pick a project" -n M-s \
  display-popup -E -w 80% -h 70% "tmux-companion project"
%endif


# The next window in this session, wrapping at the end.
bind -N "companion: project toggle the windows in this session" -n M-a \
  run-shell "tmux-companion toggle '#{session_name}'"
# The flip between the two most recent windows, for a session with more than two.
bind -N "companion: project flip to the last window" -n M-A \
  run-shell "tmux-companion toggle --last '#{session_name}'"


# Every binding, searchable, and the same list as a cheat sheet.
%if "#{>=:#{version},3.3}"
bind -N "companion: help search every key binding" ? \
  display-popup -B -E -w 80% -h 60% "tmux-companion keys"
%else
bind -N "companion: help search every key binding" ? \
  display-popup -E -w 80% -h 60% "tmux-companion keys"
%endif
%if "#{>=:#{version},3.3}"
bind -N "companion: help cheat sheet of my bindings" C-c \
  display-popup -B -E -w 90% -h 80% "tmux-companion cheatsheet"
%else
bind -N "companion: help cheat sheet of my bindings" C-c \
  display-popup -E -w 90% -h 80% "tmux-companion cheatsheet"
%endif


# tmux's own prefix+c, with a say in the directory: the query starts on this
# pane's directory, so Enter is what prefix+c always did.
%if "#{>=:#{version},3.3}"
bind -N "companion: window new one here, or at any directory" c \
  display-popup -B -E -w 65% -h 65% "tmux-companion new-window"
%else
bind -N "companion: window new one here, or at any directory" c \
  display-popup -E -w 65% -h 65% "tmux-companion new-window"
%endif


# A command from shell history, run in a pane beside this one.
%if "#{>=:#{version},3.3}"
bind -N "companion: window run a command from history" e \
  display-popup -B -E -w 70% -h 60% "tmux-companion run"
%else
bind -N "companion: window run a command from history" e \
  display-popup -E -w 70% -h 60% "tmux-companion run"
%endif


# Every pane on the server, with what it runs and whether it has gone quiet;
# enter jumps there. `--agents` narrows it to the coding agents.
%if "#{>=:#{version},3.3}"
bind -N "companion: window jump to any pane" g \
  display-popup -B -E -w 80% -h 70% "tmux-companion panes"
%else
bind -N "companion: window jump to any pane" g \
  display-popup -E -w 80% -h 70% "tmux-companion panes"
%endif
# What the agents stopped to ask, oldest first; enter jumps to the one picked.
%if "#{>=:#{version},3.3}"
bind -N "companion: project the agents waiting on you" M-g \
  display-popup -B -E -w 80% -h 70% "tmux-companion inbox"
%else
bind -N "companion: project the agents waiting on you" M-g \
  display-popup -E -w 80% -h 70% "tmux-companion inbox"
%endif
# One screen of what needs you: the waiting agents, the health reasons, the
# idle sessions, the numbers. The same screen opens by itself on attach when
# there is news, through the client-attached hook below.
%if "#{>=:#{version},3.3}"
bind -N "companion: help what needs me" b \
  display-popup -B -E -w 90% -h 75% "tmux-companion brief"
%else
bind -N "companion: help what needs me" b \
  display-popup -E -w 90% -h 75% "tmux-companion brief"
%endif
# A click on the right side of the bar: the agent count opens the inbox, the
# health mark the brief. Needs `set -g mouse on`.
bind -T root MouseDown1StatusRight \
  run-shell "tmux-companion click '#{mouse_status_range}'"
# What happened in each project today, newest first: what ran long, what the
# agents asked, what opened and closed.
%if "#{>=:#{version},3.3}"
bind -N "companion: help what happened today" J \
  display-popup -B -E -w 80% -h 70% "tmux-companion journal"
%else
bind -N "companion: help what happened today" J \
  display-popup -E -w 80% -h 70% "tmux-companion journal"
%endif
# Quiet hours from a prompt: `45m`, `2h`, or `off`. The health mark says
# `quiet` while it lasts.
bind -N "companion: config quiet hours, no nagging for a while" Q \
  command-prompt -p "quiet for (45m, 2h, off):" "run-shell \"tmux-companion quiet %%\""


# Everything but this pane goes: a zoom with other panes open, the status bar
# with none.
bind -N "companion: pane zen, everything but this one goes" z \
  run-shell "tmux-companion zen --pane '#{pane_id}'"


# Close this project cleanly, capturing its layout on the way out so it opens
# with the same windows next time.
bind -N "companion: session close this project cleanly" X \
  confirm-before -p "close #{session_name}? (y/n)" "run-shell 'tmux-companion project close'"


# ── Later ───────────────────────────────────────────────────────────────────
#
# `tmux-companion theme init` writes the colour themes, `prefix C-t` picks one
# per project, and this hook paints a new session in its project's colour.
# With no themes on disk it does nothing and says nothing.
#
#   bind -N "companion: config pick a colour theme" C-t \
#     display-popup -E -w 70% -h 70% "tmux-companion theme pick"
#   set-hook -g session-created "run-shell 'tmux-companion theme apply \"#{session_name}\" -t \"#{session_name}\"'"
#
# `[sessions] autosave` in config.toml snapshots every session on a timer, and
# `tmux-companion sessions resurrect` brings them back after a reboot.
# tmux.conf.full.example has the keys for that and everything else.