tmux-claude-hatch: Claude Code sessions in tmux popups, with an fzf picker
tmux plugin that runs Claude Code sessions in popups per project directory, with an fzf picker showing each session's status and a bell that highlights the window that needs you.
At a glance
- What is it?
- A shell-based tmux plugin that gives each project directory its own Claude Code popup, lists every running agent in an fzf picker with live status, and forwards the terminal bell back to the window that launched it.
- Who is it for?
- tmux-claude-hatch fits people who keep their editor in the main tmux session and want agent sessions managed without leaving it. It does not fit anyone who wants one manager across several AI providers, or who works mainly inside the agent's chat view.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agent sessions that outlive the pane you started them in
Running Claude Code in a split pane works until you close the pane. A long refactor dies with the terminal, or you keep a dedicated window open per project and lose track of which one is waiting on you. The plugin's answer is to put each session in its own nested tmux session so closing the popup never interrupts the agent, and to give you one picker that lists them all. The README is explicit about who it is for: people who want to stay in their editor, who still read and review the code themselves, and who would rather have a small tool than a full-blown one. It is equally explicit about who it is not for: people whose focus is the agent's chat interface, people who want one tool across several AI providers, and people running a swarm of agents who do not read or write code. That last exclusion matters. This is a session switcher, not an orchestration layer.
How the popup, the nested session and the picker fit together
Three mechanisms carry the plugin. The launcher binds prefix+y and opens a popup, via tmux's display-popup, running the configured command (claude by default) for the current directory; the session is named with a prefix, claude- by default, so it lives independently of the popup. The picker binds prefix+u and paints from a cache, reading agent state from claude agents --json through jq, which is where the working, waiting and idle labels come from. Because the picker identifies each agent by its process rather than by its tmux session, several agents in one directory each get their own row, and so does a Claude you started by hand in an ordinary pane. Selecting a row switches your client to the window the agent was launched from, then resumes it in a popup over that window. Bell forwarding is the third piece, and it is the one with a caveat the README states plainly: forwarding relays a bell, it cannot create one. Claude Code has to emit it, which is what the optional Claude Code plugin configures.
Installing tmux-claude-hatch with tpm and launching your first session
The prerequisites are tmux 3.2 or newer for display-popup, fzf for the picker UI, jq to parse claude agents --json, Claude Code 2.1.139 or newer for the claude agents command, and bash on macOS or Linux. Check the Claude Code version before anything else, since the picker depends on a subcommand that older installs do not have.
claude --versionWith tpm in place, add the plugin to your tmux config. The README shows this exact line for ~/.tmux.conf or ~/.config/tmux/tmux.conf.
set -g @plugin 'craftzdog/tmux-claude-hatch'Then press prefix followed by I to install through tpm. If you do not use tpm, the README gives the manual route instead: clone the repository and run the plugin's entry script from your config.
git clone https://github.com/craftzdog/tmux-claude-hatch ~/clone/pathThe manual install adds a run-shell line pointing at claude_hatch.tmux, followed by a reload of the config. Reload with prefix+r or the tmux source command shown here.
run-shell ~/clone/path/claude_hatch.tmux
tmux source ~/.tmux.confNow open a project directory and press prefix+y. A popup opens with a Claude session for that directory; prefix+d closes the popup and the session keeps running. Press prefix+u for the picker, which lists every running agent with its status, a live preview of the agent's screen, and agents that are waiting or idle sorted to the top. Enter jumps to the agent, ctrl-x kills the highlighted one. One note on bindings: prefix+y and prefix+u are the defaults, and if your config binds those keys elsewhere you either change the plugin options or make sure the plugin loads after your own bindings, so the one you want wins.
The bell only rings if Claude Code rings it
Bell forwarding is the feature most likely to disappoint on first install, and the README does not hide why. tmux relays a bell; it cannot manufacture one, so the highlight on the window you launched from only appears if Claude Code emits a real bell character. The optional Claude Code plugin registers the hook configuration for you, and the README lists the events it covers: turn end, permission prompts, questions to you, plus session start and end and prompt submit. That last group does a second job, refreshing the picker's agent cache so the first frame is not stale and does not show working for an agent that has been waiting on you. If you configure it by hand instead, the settings live in different files, and only terminal_bell and iterm2_with_bell write a real bell character; iterm2, kitty and ghostty send escape sequences that tmux does not count as a bell, notifications_disabled sends nothing, and the README's text is cut off at the default channel. Read that section in full before debugging a bell that never arrives.
Where it stops being the right tool
The scope is deliberately narrow, and the cost of that is real. It is Claude Code only, so a team splitting work across several providers gets nothing from it. The picker depends on claude agents --json and on jq, so the status column is only as good as that command's output on your installed version; the README pins Claude Code at 2.1.139 or newer, which tells you the command is recent enough to be a moving target. Bell forwarding requires a one-time Claude Code setup, and without it the highlight feature simply does not fire. And the whole thing is, in the README's own words, just a few shell scripts: there is no daemon, no persistent state beyond tmux sessions and a cache, and nothing that survives a tmux server restart. If your workflow assumes sessions outlive the tmux server, this is not that tool.
Compared with running Claude Code in plain tmux panes
The obvious alternative is what the plugin's own prerequisites describe: tmux itself, plus fzf and jq, with no plugin in between. You start Claude in a pane, keep one window per project, and switch with tmux's own window list. The difference in approach is what the plugin adds on top: a popup that closes without killing the agent, a picker that reads agent status from claude agents --json rather than from pane titles, a preview of each agent's screen, and bell forwarding that points back at the origin window. Plain tmux gives you none of the status awareness; you have to look at each pane to know whether an agent is waiting. The trade-off runs the other way too: plain tmux has no dependency on the claude agents subcommand or on jq, and no keybindings to reconcile. If you run one agent at a time, the plugin's picker earns little. If you run several across directories, the status column is the whole point.
Maintenance, licence and upgrade cost
The repository is not archived and the last push was on 2026-09-15, the same day as the v1.4.0 release; v1.3.0 came on 2026-08-26 and v1.2.0 on 2026-08-17, so releases have been arriving at a steady clip. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are kept; that is a description of the licence text, not legal advice, and anyone embedding it in a product should read the LICENSE file in the repository root. Upgrade cost is low by construction. Under tpm, updating the plugin and reloading tmux is the whole procedure, and the manual install is a git pull in the clone directory plus a source of the tmux config. The one thing to watch on upgrade is the options block: the README documents nine @claude_ settings with their defaults, and any of them can be overridden, so a config that sets @claude_launch_key or @claude_list_key should be re-checked after a version bump rather than assumed stable.
Editorial conclusion
tmux-claude-hatch fits people who keep their editor in the main tmux session and want agent sessions managed without leaving it. It does not fit anyone who wants one manager across several AI providers, or who works mainly inside the agent's chat view. Before adopting it, check three things in order: that tmux is at least 3.2 so display-popup exists, that claude agents --json returns output on your installed Claude Code, and whether prefix+y and prefix+u already mean something in your tmux.conf, because the plugin's bindings are set before it loads and load order decides which one wins.
Frequently asked questions
Why use tmux for Claude Code instead of just running it in a terminal?
tmux-claude-hatch puts each Claude Code session in its own nested tmux session, so closing the popup with prefix+d does not interrupt the agent. The picker then lists every running agent with its status, which a plain terminal cannot do.
What is tmux used for?
In this project tmux provides the popup (via display-popup, which needs tmux 3.2 or newer), the nested sessions the agents live in, and the client switching that the smart jump uses when you select an agent in the picker.
Is tmux outdated?
The README does not discuss tmux's overall standing, and this plugin depends on a relatively recent tmux feature: display-popup, which the README lists as requiring tmux 3.2 or newer.
Community notes