tmux-claude-hatch: Claude Code in a tmux popup
tmux-claude-hatch
A tmux plugin that runs a Claude Code session in a popup for each project and shows the status of every agent in an fzf picker
- 403 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The Claude Code plugin registers hooks on agent events and runs shell scripts on them
- Running sessions keep working in the background after the popup closes, so an agent can run commands while you are in the editor
- The plugin reads Claude Code session files to show statuses and screen snapshots of agents
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/tmux-claude-hatchDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The Claude Code plugin registers hooks on agent events and runs shell scripts on them
- Running sessions keep working in the background after the popup closes, so an agent can run commands while you are in the editor
- The plugin reads Claude Code session files to show statuses and screen snapshots of agents
This is third-party code. Review the repository files before installing.
What it does
tmux-claude-hatch opens Claude Code in a tmux popup for the current project folder. You hand the agent a task, close the popup and go back to your editor. Each session lives in its own nested tmux session, so closing the popup does not interrupt it. The agent picker opens with `prefix` + `u`. It lists every running Claude Code, including several in one project and ones started by hand in an ordinary pane. The plugin reads each status, working, waiting for you or idle, from the session files Claude Code itself keeps, and shows a live snapshot of its screen. The chosen agent opens in the window it was launched from. When a session finishes a turn or waits for permission, the terminal rings a bell and tmux highlights the originating window, so you do not have to look in the picker. The bell comes from an optional Claude Code plugin with hooks. The project is a handful of shell scripts, aimed at people who read and write code themselves in (Neo)vim or Emacs.
Who it is for. For developers who live in tmux and an editor such as Neovim or Emacs, read and edit the code themselves, and want to run several Claude Code sessions without a separate shell for agents.
Good fit when
- You work in Neovim or Emacs inside tmux and want to hand tasks to an agent without leaving your main session
- Several Claude Code sessions run in parallel in different projects and you need to see quickly which one wants an answer
- You want a bell when an agent finishes a turn or asks for permission, with the originating window highlighted
- You need to copy an agent pane's address as session:window.pane to send commands to it later with tmux send-keys
- You want a small tool made of shell scripts that is easy to read and rework
Not a fit when
- The agent's chat matters to you more than the code: the authors list such users among those the tool is not for
- You need one session manager for several AI providers: the plugin is built for Claude Code only
- You run a swarm of agents and do not read or write code yourself
- The machine lacks tmux 3.2 or newer, fzf or jq, or runs a system other than macOS or Linux
Example request
Work through the failing tests in this project and fix them while I go back to my editor.Limitations
You need tmux 3.2 or newer for popups, fzf, jq, bash, Claude Code 2.1.139 or newer, and macOS or Linux. The Claude Code version matters for the claude agents command, which serves as a fallback source of statuses when session files cannot be read.
The plugin works only with Claude Code, and the Anthropic API is unavailable from Russia. The plugin only forwards the bell; Claude Code itself creates it, so you need the hooks from the Claude Code plugin or notification settings. Terminal notification channels other than terminal_bell and iterm2_with_bell do not count as a bell for tmux.
How to disable. Remove the set -g @plugin 'craftzdog/tmux-claude-hatch' line from the tmux configuration and reload it. If you installed the Claude Code plugin, remove it through the /plugin menu. End running claude-* sessions with tmux kill-session or the ctrl-x key in the picker.
FAQ
How do I install tmux-claude-hatch?
Through the tpm plugin manager: add the line set -g @plugin 'craftzdog/tmux-claude-hatch' to your tmux configuration and press `prefix` + `I`. Without tpm clone the repository and load the claude_hatch.tmux file with run-shell. By default launch is bound to `prefix` + `y` and the picker to `prefix` + `u`.
What must be on the machine besides the plugin?
tmux 3.2 or newer, fzf for the picker, jq to parse session files and Claude Code 2.1.139 or newer. It runs on macOS and Linux in bash.
How do I set up a bell when Claude Code finishes?
Claude Code itself creates the bell and the plugin only forwards it. The easiest way is the optional tmux-claude-hatch plugin from the Claude Code marketplace: its hooks ring at the end of a turn, on a permission request and on an agent question. By hand, set terminal_bell for preferredNotifChannel in ~/.claude/settings.json.
How do I see the status of every running agent?
Press `prefix` + `u`. Agents that need your attention (waiting or idle) sit at the top, and `@claude_sort 'recent'` switches to last activity order. Enter jumps to the chosen agent, ctrl-x kills it and ctrl-y copies its address.
Can I start sessions without permission prompts?
Yes: set `set -g @claude_args '--dangerously-skip-permissions'` and every session the plugin starts begins with that flag. Keep in mind the agent then runs commands without confirmation.
Discussion
No questions or reviews yet.
Related
PluginsA marketplace of 17 Claude Code mods: token-spend breakdown, a rollback edit timeline, assumption tracking, a verification board and a live command feed
A Claude Code plugin: a status line with context, 5-hour and 7-day limits, cost and usage of Codex, Gemini and z.ai
A Claude Code plugin that catches your corrections in chat and, after review, writes them into CLAUDE.md and AGENTS.md
A terminal kanban board in Python that Claude Code and other agents can read and change through a CLI or MCP
A statusline for Claude Code: token and cost usage, context left, rate limits and git branch in four styles and six themes
Claude-to-IM
claude-to-im
A bridge between Claude Code or Codex and messengers: talk to the agent from Telegram, Discord, Feishu, QQ or WeChat
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| tmux-claude-hatch: Claude Code in a tmux popup (this entry) | no | 403 | |
| Claude Squad | no | 8,694 | a standalone terminal app for parallel sessions of different agents in isolated working copies |
| tmux-ide | yes | 558 | shows which agents in tmux sessions are working, waiting or idle and sets up a working environment |
README in short
The plugin is a handful of shell scripts: launching a session, the agent picker, bell forwarding and shared functions. The Claude Code plugin sits in a separate folder with hooks and does not depend on the tmux plugin.