Skip to content
Back to search

tmux-claude-hatch

MarketplaceWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/craftzdog--tmux-claude-hatch/badge.svg)](/listings/craftzdog--tmux-claude-hatch)

HTML

<a href="/listings/craftzdog--tmux-claude-hatch"><img src="/api/listings/craftzdog--tmux-claude-hatch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

tpm

Add to `~/.tmux.conf` (or `~/.config/tmux/tmux.conf`):

set -g @plugin 'craftzdog/tmux-claude-hatch'

Then hit `prefix` + <kbd>I</kbd> to install.

> **Keybinding note:** by default the plugin binds `prefix` + `y` (launch) and > `prefix` + `u` (list). If your config binds those elsewhere, either change the > [options](#options), or make sure the plugin loads **after** your own bindings > (put `run '~/.tmux/plugins/tpm/tpm'` _after_ them) so the one you want wins.

(Optional) Claude Code plugin

Independent of the tmux plugin above. It ships the Claude Code hook configuration this plugin wants, so you don't have to hand-edit `~/.claude/settings.json`:

- **Rings the terminal bell** when an agent ends a turn, asks for permission, or asks you a question — the moments the picker calls `idle` and `waiting`. That is what [bell forwarding](#making-claude-ring-the-bell) needs in order to highlight the window you launched the agent from. - **Refreshes the picker's agent cache** on those same events, plus session start/end and prompt submit. The picker paints its first frame from that cache (unless `@claude_picker_cache` is `'off'`), so without this it can be stale — showing `working` for an agent that has been waiting on you.

/plugin marketplace add craftzdog/tmux-claude-hatch
/plugin install tmux-claude-hatch@tmux-claude-hatch

See [`plugins/tmux-claude-hatch`](./plugins/tmux-claude-hatch) for exactly what it registers.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "tmux-claude-hatch",
  3. "owner": {
  4. "name": "Takuya Matsuyama",
  5. "email": "hi@craftz.dog"
  6. },
  7. "plugins": [
  8. {
  9. "name": "tmux-claude-hatch",
  10. "source": "./plugins/tmux-claude-hatch",
  11. "description": "Companion hooks for tmux-claude-hatch: ring the terminal bell when an agent needs you, and keep the picker's agent cache fresh."
  12. }
  13. ]
  14. }
README.md · README · 280 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # tmux-claude-hatch
  2. [![screenshot](./docs/screenshot.jpg)](https://youtu.be/NnTV6r4l5D0)
  3. A tmux plugin (plus an optional Claude Code plugin) that runs a Claude Code
  4. session in a popup for each project directory. Open the hatch, hand Claude the
  5. work, close it and get back to your editor. Each session lives in its own nested
  6. tmux session, so closing the hatch never interrupts it. When you want to check
  7. in, an `fzf` picker lists every running session, shows what each one is doing,
  8. and jumps you straight to it. And when a session finishes or needs your
  9. attention, it rings a bell that highlights the window you launched it from — so
  10. you know where to go without even opening the picker.
  11. Simple by design: it's just a few shell scripts.
  12. ## Why / philosophy
  13. - **Who it's for**
  14. - People who want to stay in their editor — (Neo)vim, Emacs — in the main tmux
  15. session
  16. - People who still read, write, and review the code themselves
  17. - People who'd rather have a small tool than a full-blown one just to manage
  18. agent sessions
  19. - **Who it's not for**
  20. - People whose focus is the agent's chat interface rather than the code
  21. - People who want one tool for sessions across several AI providers — this one
  22. is Claude Code only
  23. - People who run a swarm of agents and don't read or write code themselves
  24. ## Features
  25. - **A central picker** (`prefix` + `u`) listing every running Claude agent —
  26. several in one project, and any running loose in an ordinary pane.
  27. - **Live status** per agent — `working` / `waiting` / `idle` — read straight
  28. from the session files Claude Code keeps, so you instantly see which need you.
  29. No setup.
  30. - **A live preview** of each agent's screen right in the picker.
  31. - **Smart jump** — selecting an agent switches your client to the window it
  32. was launched from, then resumes it in a popup over it.
  33. - **A launcher** (`prefix` + `y`) that opens/attaches a Claude session for the
  34. current directory.
  35. - **Quick kill** (`ctrl-x`) of a finished agent from the picker.
  36. - **Copy location** (`ctrl-y`) — puts an agent's `session:window.pane` target
  37. on the clipboard, ready for `tmux send-keys -t` and friends.
  38. - **Bell forwarding** — a bell in a dedicated session highlights the window
  39. you launched it from, so you notice even without opening the picker
  40. ([one-time Claude Code setup](#making-claude-ring-the-bell)).
  41. ![bell-forwarding](./docs/bell-forwarding.png)
  42. ## Prerequisites
  43. - **tmux ≥ 3.2** (for `display-popup`)
  44. - **[fzf](https://github.com/junegunn/fzf)** — the picker UI
  45. - **[jq](https://jqlang.org/)** — parses Claude Code's session files
  46. - **[Claude Code](https://claude.com/claude-code)** ≥ 2.1.139 — for the
  47. `claude agents` command, the fallback when the session files can't be read
  48. (`claude --version` to check)
  49. - bash; macOS or Linux
  50. ## Installation
  51. ### tpm
  52. Add to `~/.tmux.conf` (or `~/.config/tmux/tmux.conf`):
  53. ```tmux
  54. set -g @plugin 'craftzdog/tmux-claude-hatch'
  55. ```
  56. Then hit `prefix` + <kbd>I</kbd> to install.
  57. > **Keybinding note:** by default the plugin binds `prefix` + `y` (launch) and
  58. > `prefix` + `u` (list). If your config binds those elsewhere, either change the
  59. > [options](#options), or make sure the plugin loads **after** your own bindings
  60. > (put `run '~/.tmux/plugins/tpm/tpm'` _after_ them) so the one you want wins.
  61. ### (Optional) Claude Code plugin
  62. Independent of the tmux plugin above. It ships the Claude Code hook
  63. configuration this plugin wants, so you don't have to hand-edit
  64. `~/.claude/settings.json`:
  65. - **Rings the terminal bell** when an agent ends a turn, asks for permission, or
  66. asks you a question — the moments the picker calls `idle` and `waiting`. That
  67. is what [bell forwarding](#making-claude-ring-the-bell) needs in order to
  68. highlight the window you launched the agent from.
  69. - **Refreshes the picker's agent cache** on those same events, plus session
  70. start/end and prompt submit. The picker paints its first frame from that cache
  71. (unless `@claude_picker_cache` is `'off'`), so without this it can be stale —
  72. showing `working` for an agent that has been waiting on you.
  73. ```
  74. /plugin marketplace add craftzdog/tmux-claude-hatch
  75. /plugin install tmux-claude-hatch@tmux-claude-hatch
  76. ```
  77. See [`plugins/tmux-claude-hatch`](./plugins/tmux-claude-hatch) for exactly what
  78. it registers.
  79. ## Usage
  80. | Key | Action |
  81. | -------------- | ------------------------------------------------------------------------------- |
  82. | `prefix` + `y` | Launch (or re-attach to) a Claude session for the current directory, in a popup |
  83. | `prefix` + `d` | Close the popup and go back to your window; the Claude session keeps running |
  84. | `prefix` + `u` | Open the agent picker |
  85. Inside the picker:
  86. | Key | Action |
  87. | ------------------------- | ---------------------------------------------------------------------------- |
  88. | `enter` | Jump to the agent |
  89. | `ctrl-x` | Kill the highlighted agent |
  90. | `ctrl-y` | Copy the highlighted agent's location (e.g. `claude-88074b0e:0.0`) and close |
  91. | `↑` / `↓`, type to filter | fzf navigation |
  92. Agents needing your attention (`waiting`, `idle`) sort to the top. Set
  93. `@claude_sort 'recent'` to sort by last activity instead, regardless of status.
  94. Every running Claude gets its own row — the picker identifies each by its
  95. process, not by its tmux session. So several agents in one project all show up
  96. separately, as does a Claude you started by hand in an ordinary pane.
  97. ## Options
  98. Set any of these before the plugin loads (defaults shown):
  99. ```tmux
  100. set -g @claude_launch_key 'y' # prefix key: launch/open for current dir
  101. set -g @claude_list_key 'u' # prefix key: open the picker
  102. set -g @claude_command 'claude' # command run in new sessions
  103. set -g @claude_args '' # extra args appended to the command
  104. set -g @claude_session_prefix 'claude-' # tmux session name prefix
  105. set -g @claude_popup_width '90%' # popup width
  106. set -g @claude_popup_height '90%' # popup height
  107. set -g @claude_fzf_options '' # extra options passed to the fzf picker
  108. set -g @claude_picker_cache 'on' # paint the picker's first frame from a cache
  109. set -g @claude_sort 'status' # picker order: 'status' or 'recent'
  110. set -g @claude_forward_bell 'on' # highlight the origin window on a bell
  111. ```
  112. For example, to skip permission prompts in launched sessions:
  113. ```tmux
  114. set -g @claude_args '--dangerously-skip-permissions'
  115. ```
  116. ## Manual installation
  117. If you don't use tpm:
  118. ```sh
  119. git clone https://github.com/craftzdog/tmux-claude-hatch ~/clone/path
  120. ```
  121. Add to `~/.tmux.conf`, then reload (`prefix` + <kbd>r</kbd> or
  122. `tmux source ~/.tmux.conf`):
  123. ```tmux
  124. run-shell ~/clone/path/claude_hatch.tmux
  125. ```
  126. ## Customizations
  127. ### Making Claude ring the bell
  128. Forwarding relays a bell; it cannot create one. Claude Code has to emit it. The
  129. [Claude Code plugin](#optional-claude-code-plugin) takes care of that; the
  130. alternatives below do the same job by hand.
  131. #### Via Claude's own notification settings
  132. Two settings decide this — and they live in **different files**.
  133. **How** it notifies — `~/.claude/settings.json`:
  134. ```json
  135. {
  136. "preferredNotifChannel": "terminal_bell"
  137. }
  138. ```
  139. Only `terminal_bell` and `iterm2_with_bell` write a real `\a`. `iterm2`, `kitty`
  140. and `ghostty` send escape sequences that tmux does not count as a bell,
  141. `notifications_disabled` sends nothing, and the default `auto` picks by terminal —
  142. so pin it.
  143. **When** it notifies — `~/.claude.json`, the global config (`settings.json`
  144. ignores this key and drops it silently):
  145. ```json
  146. {
  147. "messageIdleNotifThresholdMs": 0
  148. }
  149. ```
  150. Claude rings once it has sat idle this long. The default is 60000, long enough
  151. that you'd normally have gone back to look before it fires; `0` rings the moment a
  152. turn ends.
  153. #### Via a hook
  154. A hook is the way to keep the bell while pointing `preferredNotifChannel` at an
  155. OS-notification channel instead. This is what the Claude Code plugin registers;
  156. to wire it by hand, in `~/.claude/settings.json`:
  157. ```json
  158. {
  159. "hooks": {
  160. "Stop": [
  161. {
  162. "matcher": "",
  163. "hooks": [
  164. {
  165. "type": "command",
  166. "command": "printf '\\a' 2>/dev/null > /dev/tty || { [ -n \"$TMUX_PANE\" ] && printf '\\a' 2>/dev/null > \"$(tmux display-message -p -t \"$TMUX_PANE\" '#{pane_tty}' 2>/dev/null)\"; } || true"
  167. }
  168. ]
  169. }
  170. ]
  171. }
  172. }
  173. ```
  174. `Stop` fires the moment a turn ends, with no idle timer involved. The bell goes to
  175. `/dev/tty` — the hook's controlling terminal, which inside tmux is the pane's own
  176. pty, exactly where Claude's built-in bell would land. The `$TMUX_PANE` branch
  177. covers a hook running without a controlling terminal, resolving the pane's tty
  178. through tmux instead; the trailing `|| true` keeps a failed bell from failing the
  179. hook.
  180. Note that `2>/dev/null` comes **before** the `/dev/tty` redirection. A failed
  181. redirection is reported by the shell itself, so a trailing `2>/dev/null` is
  182. applied too late to suppress it — with the operands the other way round, a hook
  183. running without a controlling terminal prints
  184. `bash: /dev/tty: Device not configured` on every turn.
  185. Use the same command under `Notification` with the `permission_prompt` matcher to
  186. ring when Claude asks for permission, or under `PreToolUse` matching
  187. `AskUserQuestion` to ring when it asks you a question.
  188. Set `@claude_forward_bell 'off'` to disable forwarding altogether.
  189. ### Customizing the fzf picker
  190. `@claude_fzf_options` is passed straight to `fzf`, so you can add your own
  191. bindings. Here is a vim-style example:
  192. ```tmux
  193. set -g @claude_fzf_options "\
  194. --prompt 'nav> ' \
  195. --bind 'j:down' \
  196. --bind 'k:up' \
  197. --bind 'q:abort' \
  198. --bind 'x:execute-silent(kill {3})+reload(sleep 0.3; \$CLAUDE_PICKER --list)' \
  199. --bind 'i:unbind(j,k,q,i,a,x)+change-prompt(filter> )' \
  200. --bind 'a:unbind(j,k,q,i,a,x)+change-prompt(filter> )' \
  201. --bind 'esc:rebind(j,k,q,i,a,x)+change-prompt(nav> )'"
  202. ```
  203. The picker opens in **nav** mode:
  204. | Key | Action |
  205. | --------- | ------------------------------------------------------- |
  206. | `j` / `k` | move down / up |
  207. | `i` / `a` | switch to **filter** mode — type to fuzzy-match |
  208. | `x` | kill the highlighted agent (like the built-in `ctrl-x`) |
  209. | `q` | close the picker |
  210. | `enter` | jump to the agent (both modes) |
  211. | `esc` | filter mode → back to nav |
  212. Only the bound keys are special in nav mode; any other key still filters as you
  213. type. `x` reloads the list through `$CLAUDE_PICKER`, a path the picker exports
  214. for exactly this — write it as `\$CLAUDE_PICKER` inside the double-quoted value
  215. above so tmux stores a literal `$` (in a single-quoted value, use a bare
  216. `$CLAUDE_PICKER`).
  217. ## License
  218. [MIT](LICENSE) © Takuya Matsuyama

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.