workon-tmux

Personal tool. Built for my own workflow — sharing in case it's useful to anyone else.

Minimal tmux session manager for project work. Pick a project with fzf, choose an AI agent and git viewer, and get a new tmux session with your preferred layout.

┌──────────────────┬──────────────────┐
│                  │                  │
│     agent        │   git viewer     │
│                  │                  │
└──────────────────┴──────────────────┘

• Creates multiple sessions per project
• Names new sessions from the project, latest Git commit date, and commit hash
• Opens existing sessions without recreating the layout
• Kill sessions from the same picker with ctrl-d
• Sets the terminal tab title to the session name (Ghostty, iTerm2)

Requirements

• tmux
• fzf
• lazygit
• At least one AI agent CLI — e.g. Claude Code, Codex, Gemini CLI

Install

git clone https://github.com/chrissy-dev/workon-tmux ~/Projects/workon-tmux
ln -s ~/Projects/workon-tmux/workon /usr/local/bin/workon

Configure

mkdir -p ~/.config/workon
cp ~/Projects/workon-tmux/projects.txt.example ~/.config/workon/projects.txt

Edit ~/.config/workon/projects.txt with your projects, one path per line:

# comments are supported
~/Projects/my-app
~/Projects/dotfiles

New session names are generated from the project basename, latest Git commit date, and latest commit hash, for example my-app-20260718-a1b2c3d. If a matching session already exists, workon appends a numeric suffix so you can keep multiple sessions open for the same project and commit.

Agent

By default the agent picker shows claude and codex. Override by setting DEFAULT_AGENTS in ~/.config/workon/config:

DEFAULT_AGENTS="claude codex gemini"

Git viewer

By default the git viewer picker shows lazygit and tig status. Override with a bash array in ~/.config/workon/config (array syntax is required since commands can contain spaces):

DEFAULT_GIT_VIEWERS=("lazygit" "tig status" "gitui")

If only one entry is listed, the picker is skipped for both agents and git viewers.

Usage

workon          # pick a project
workon add      # add a project via directory browser
workon remove   # remove a project from the list

Run from your terminal. Pick a new project row to create another session, choose an agent and git viewer, and the session opens. Pick an open row to attach to an existing session, pick a kill row to terminate one, or use ctrl-d to kill selected active sessions.