r/tmux • • 1h ago

Showcase Fable 5.2 is insane!

1 Upvotes

tmuxbox: every tmux pane on one 3D bean. Type to jump, Enter for a real terminal


r/tmux • • 7h ago

Showcase xcontrol: a small tmux wrapper for coding agents

0 Upvotes

I've been using tmux for over 5 years, long before all this AI agent stuff. I kept using it to manage coding agents and eventually built some scripts around it, which turned into xcontrol.

It's more of a simple wrapper than another full blown competitor. It resumes CLI sessions in tmux and lets agents message each other. Supports Codex, Claude, Copilot, and other CLIs. Just wanted to share it.

https://github.com/faustinoaq/xcontrol


r/tmux • • 18h ago

Showcase Getting a screenshot path into the right tmux pane from macOS, with a check that it actually arrived

1 Upvotes

I run Claude Code and Codex CLI in tmux, locally and on a server, and wanted a screenshot to land in the right pane without saving the file, finding the path and pasting it by hand. I ended up building a small macOS menu bar app for it (PaneDrop, free, 1.0.0 today), and the tmux part turned out to be the interesting bit, so here is how it talks to tmux:

  • Finding panes: list-panes -a with format strings, then a process check to see which panes are running an agent. The list shows the session and project folder.

  • Typing: set-buffer -b <name> -- <text> then paste-buffer -p -b <name> -t <pane>. The -- matters: without it a payload starting with - gets read as options. -p only requests bracketed paste; markers appear only if the program in the pane has turned it on, so multi-line text is sent only when #{bracket_paste_flag} says the pane accepts it. Without bracketed paste, paste-buffer turns each newline into a CR, which would submit partial prompts.

  • Did it arrive? capture-pane -p -J before and after, so it can tell its own paste from text that was already on screen.

  • Cleanup: delete-buffer on every path, success or failure, so no named buffers are left behind.

  • No Enter: the paste path has no send-keys at all. Submitting is a separate action you have to turn on.

  • Over SSH: it uses your own OpenSSH config, uploads the image to the server, lists and pastes into tmux panes there the same way, and types the remote path.

Needs tmux 3.3 or later. Mac side: Apple Silicon, macOS 14+. https://panedrop.app

Curious whether anyone has a cleaner way to confirm a paste landed than diffing capture-pane output.


r/tmux • • 1d ago

Showcase neopane: each Neovim window as a real tmux pane, sharing one Neovim

48 Upvotes

neopane runs Neovim once, in a background daemon, and gives each window a tmux pane of its own. :vsplit splits the tmux pane, <C-w>h/j/k/l move tmux's focus, pickers open in tmux floating panes (tmux 3.7+), and tab pages become tmux windows. Every pane shares the same buffers, registers, undo and language servers, so it isn't one Neovim per pane.

It works with no config inside tmux 3.2+. brew install spiritledsoftware/tap/neopane or cargo install --locked neopane

https://github.com/ian-pascoe/neopane

It's very early. I'd especially like to hear from people with unusual tmux setups.


r/tmux • • 2d ago

Showcase I built weaver: open a whole tmux dev environment from one YAML file

0 Upvotes

r/tmux • • 2d ago

Showcase vtmux: drop-in tmux replacement, better rendering, live upgrades

0 Upvotes

https://github.com/martintrojer/vtmux

vtmux is a tmux 3.8 drop-in replacemnt using libghostty-vt.

Disclaimer; Agents wrote most of the code.

tmux 3.8 compliant; same CLI, config, formats and control mode.

  • 173 of tmux's own 174 regress tests pass, run unchanged.

  • 449 scenarios recorded from real tmux (screens, output, control-mode streams) replay identically.

What it does better than tmux:

- Stable rendering: each client gets one finished frame at a time, with only what changed, inside synchronized output and with the cursor placed once. There's no cursor jumping or tearing under heavy output.

- Much less traffic to your terminal: a redraw-heavy benchmark sends 0.07 MB where tmux sends 10.1 MB, at 0.3x the CPU.

- Less CPU usage for most common use cases.

- Live upgrade: you swap the binary under a running server and shells and clients stay put. 10 panes with 100k lines each move over in under a second.

- Compressed scrollback: 1M lines settle at 103 MB against tmux's 622 MB.

- Protocols tmux drops (each opt-in): kitty keys, notifications, kitty graphics.

What it costs: twice tmux's idle memory (8.5 vs 4.2 MB), a 10 MB binary, 0.30 vs 0.21 ms key echo.

Looking for testers!

Installing and running beside tmux

$ mise use -g github:martintrojer/vtmux

or follow https://github.com/martintrojer/vtmux#install

then

$ vtmux

(it keeps its own sockets)


r/tmux • • 4d ago

Showcase zmux: tmux style window and session management for zmx

0 Upvotes

r/tmux • • 4d ago

Question Are there any terminal programs written to cooperate with tmux?

27 Upvotes

I'm new to tmux (but a dinosaur in this space**). I'm finding it to have a lot of great features that I'm just barely getting started with. But right away I see some drawbacks. Maybe these are solved problems that more experienced users could address, but I also see that these problems COULD be solved if a dedicated terminal program was designed to directly cooperate with tmux.

For one thing (I'm sure this has been endlessly rehashed), but cut and paste is a mess. And as a dinosaur, I understand the historical reasons for this mess better than most. (Let me know if you want a long-winded posting about this.) But, in a nebulous and not-fully-thought-out way, it seems like a parent terminal emulator that understood this pain could alleviate at last some of the issues. I would prefer to preserve both the traditional middle-click to paste any current terminal selection, and the system-wide paste shortcut for the current clipboard. Yes there are very old conflicts on that one that go way deeper than tmux, but I think some thought and added terminal features could at least partially clean things up. (And can we just all agree that system cut and paste shortcuts in Linux should be changed community-wide to Super-C and Super-V and all the other conflicts would then disappear?)

The other one that is striking to me is handling of terminal size. I realize there is no built-in protocol for having a program resize it's parent terminal. But it would be such an easy feature to add with a dedicated terminal emulator, and would be super convenient for more cleanly attaching and detaching other sessions. Even if monitor resolution was a problem it could use font scaling to get sessions to fit without at all touching what was happening to the individual layouts within a session.

And I know some will say that the entire point of tmux is its independence from the terminal program, allowing it to be work across ssh connections, across operating systems, across whatever. And that's true. But I think there is space to add these features as optional improvements without destroying that independence.

[**As far as the dinosaur thing, I was a driving force in the creation of an ancient X11 terminal multiplexer called xlax, and I became it's maintainer for a while and added some features before abandoning it. It was somewhat similar to cssh, though arguably more powerful). Would be amazing if anyone remembered this program.]


r/tmux • • 5d ago

Tip Aki: a board of who is waiting on whom across GitLab, GitHub and Jira, with a tmux integration

13 Upvotes

On a team, every merge request and every ticket is waiting on someone. Finding out whether that someone is me meant opening GitLab, GitHub, Jira and my mail, again and again.

So I built aki: one terminal board with two columns, To do (someone is waiting on me) and Waiting (I'm waiting on someone: who, and since when). When a teammate answers, the task changes column by itself and I get a notification. It runs in any terminal.

And for tmux, I built an integration: one key on a task starts a coding agent on it in its own tmux window, in a session per repository.

Press the key again and you're taken back to that window instead of getting a second one. Plain tmux commands, no plugin, nothing in .tmux.conf. (In the video the agent is a stand-in script; by default it's Claude Code.)

Free, open source, written in Rust. I'm the author; part of the code was written with Claude Code and reviewed by me.

https://github.com/nathan-poncet/aki · https://nathan-poncet.github.io/aki/


r/tmux • • 5d ago

Showcase I made a Ghostty fork that supports Tmux Control Mode

Thumbnail
reddit.com
3 Upvotes

r/tmux • • 5d ago

Showcase Too stubborn to leave tmux, so I built muxrail

0 Upvotes

Hey folks,

With so many new terminals and multiplexers popping up, I prefer to keep things simple. Been loyal to tmux for years and at this point divorce isn't an option.

I built muxrail to keep track of my coding agents and regular shells without leaving tmux.

Nothing groundbreaking, just scratching my own itch.

https://github.com/kislow/muxrail

Curious what other tmux users are running these days and what you think of this.


r/tmux • • 6d ago

Showcase Untether: your tmux sessions, and the coding agents running in them, from a phone browser (open source)

0 Upvotes

I run Claude Code and Codex on my Mac pretty much all day. The annoying part was never the coding, it was me sitting there waiting to see if one of them had finished or was stuck on a permission prompt.

So I built Untether. It's a menu bar app with a local server, and you open it from any browser. I mostly use it from my phone.

The part I actually care about is tasks. You type ut task new "add rate limiting to the API" and it starts an agent in its own git worktree. When the agent says it's done, a second agent reviews the diff and your test command runs. If that's all green it merges by itself. If not, it goes back to the agent. You can also make it wait for you before merging.

A few things people asked me in other threads:

  • the sessions are plain tmux underneath, so closing the tab or losing signal doesn't kill anything

  • a failed task doesn't block the queue, the next one starts from the last good commit

  • nothing is opened to the internet. I reach it over Tailscale and there's a login on top

  • you get a push when something finishes

It's free and MIT, repo here: https://github.com/Nachx639/untether

You need an Apple Silicon Mac on macOS 14 or later. There's no installer yet so you have to build it, the steps are in the README. It's beta and I'm sure it breaks in ways I haven't seen.

It started as a fork of VibeTunnel, which is what gets the terminals into the browser. Most of the rest I wrote with Claude Code, about half the commits in the repo are co-authored by it, and for a while now new features get built by queueing them as Untether tasks.

If you try it, tell me where it falls over.


r/tmux • • 6d ago

Showcase TUI Weekly

Thumbnail tuiweekly.bl0ggers.com
1 Upvotes

r/tmux • • 8d ago

Showcase Clingon: Terminal Cheat-sheets you can run that are just markdown files (using tmux panels)

10 Upvotes

I can never remember commands. Ever.

So I built Clingon, an opinionated terminal cheat-sheet runner. It uses tmux: your cheat sheets sit in a panel on the left, your shell on the right. Pick a command, fill in the blanks, and it runs.

What makes it different:

  • Curated packs out of the box for git, docker, aws, node and more. Common commands are explained and ready to run.

  • It’s just markdown. No new format to learn, and your commands double as documentation (see image below).

  • Per-repo packs. Drop a .clingon folder in a repo and your team’s workflows are one keypress away.

  • Safety built in. Risky commands are flagged, and dangerous ones make you type a code before running.

  • Recipes. Chain commands and rerun them from any step.

GitHub: https://github.com/con-dog/clingon/blob/master/README.md

Feedback very welcome, especially on which packs you’d want next.


r/tmux • • 8d ago

Other I got tired of losing shells when a window closed, so my terminal keeps them running

0 Upvotes

Two things kept biting me: closing the wrong window and losing a long-running shell, and scrolling back through 2000 lines to find what a failed command printed. tmux fixes the first, but I didn’t want a second set of keybindings inside my terminal.

So in vif (my terminal, Linux/macOS) every shell runs under a small host process. Close the window or quit the app, and the shells keep running. Open it again and you get the same windows, tabs and splits with their scrollback. After a reboot the layout comes back with a fresh shell in each pane’s folder. vif ssh host does the same on a remote box and reconnects by itself after Wi-Fi drops.

For the second problem, every command is a block (zsh/bash marked without editing your rc). It shows exit code and duration, and ⌘↑ / ctrl+shift+↑ picks one so you can copy just its output, rerun it, or fold it. A command that took longer than N seconds notifies you when it ends if you’re looking elsewhere.

Small things I use constantly:

  • Hints: every file.rs:212, URL, commit hash on screen gets a letter. Press it to open the path in $EDITOR at that line, or a commit as git show.

  • Search across every pane, plus a 30-day local archive of commands with their output (secrets stripped, 0600). vif history WORD searches it from the shell.

  • Rules by host: ssh into anything matching prod* and the pane switches theme, so prod never looks like your laptop.

Rough edges: vif ssh needs vif installed on the remote side, IME is lightly tested, no Windows.

https://github.com/Pisosenie/vif. I’d like to hear what your setup does for “don’t lose my shell”. tmux, zellij, abduco, something else?

(Disclosure: a lot of the code was written with Claude; design and testing are mine.)


r/tmux • • 9d ago

Showcase libtmux-elixir 0.1: tmux client library for Elixir

Thumbnail
github.com
2 Upvotes

r/tmux • • 9d ago

Showcase I made a tmux sidebar to run Claude Code, Codex, OpenCode and Pi in one window

Post image
0 Upvotes

I run a few coding agents at the same time and kept ending up with a tmux window per agent. It got messy fast, so I built a sidebar for it.

All agents live in one window. You click or j/k to pick one, and its terminal shows next to the sidebar. The others keep running in the background, so nothing loses its session or history when you switch.

What it does:

  • Groups agents by folder, with a status indicator for working, waiting, ready, error

  • Shows usage for the agent you’re looking at: 5-hour and weekly limits, reset times, model, session tokens and cost

  • Sound and desktop notifications when an agent finishes or asks something while you’re not looking at it

  • Starts agents from a popup (pick agent, permission mode, folder)

  • Auto-configures Claude Code, Codex, OpenCode V2 and Pi if it finds them

It started from hiroppy’s tmux-agent-sidebar. I kept the base idea and changed it to a single-window workspace, fixed selection and ordering, and added the integrations above. Credit to them for the original.

I know herdr like exist but I am ready comfortable with tmux and other usecase for tmux so this plugin improve my workflow for tmux for agents

I mostly use it on Arch with Hyprland, so Linux is the most tested. Notifications use notify-send. macOS and other setups probably have rough edges.

Repo: https://github.com/ahmad9059/AgentsTmux

If you try it and something breaks, open an issue or tell me here. Feature ideas welcome too.


r/tmux • • 9d ago

Showcase tmux-ci-ca: True Vim-style ci / ca enclosed-text selection for tmux copy mode (with proper nesting & multiline │ support)

11 Upvotes

Hi r/tmux!

One thing that always bothered my muscle memory when switching from Vim/Neovim back to tmux copy mode was the lack of ci / ca text object selection.

There are plugins that try to solve this by chaining tmux's jump-to-forward and jump-backward commands (like tmux-vilto), but they quickly fall short: they can't handle nesting, fail awkwardly when a delimiter doesn't exist, and only work within the visible viewport.

To solve this properly, I built tmux-ci-ca.

How it works

Enter copy mode (prefix + [), move your cursor anywhere inside a pair, and press c -> i (inner) or a (around) -> target pair:

  • ci(: Selects inside parentheses

  • ca{: Selects curly braces and their content

  • ci": Selects inside quotes

The selection remains natively highlighted, so you can copy with y / Enter, or enable auto-copy on select.

Why it's different

Instead of fragile jump hacks, tmux-ci-ca computes the exact range using an AWK matcher running against the pane buffer and scrollback:

  • Nesting Depth: Correctly resolves nested structures like func(foo, (bar + baz), qux).

  • Multiline & Soft-wrapped aware: Selects across newlines, blank lines, and soft-wrapped rows.

  • CJK & Curly Quotes Support: ASCII and fullwidth CJK twins are interchangeable (e.g. typing ci( on (hello) works seamlessly).

  • Graceful Failures: If no enclosing pair is found or the inner region is empty, your selection stays intact and shows a helpful status bar notification.

  • Snapshots on tmux 3.6+: Matches against the copy-mode snapshot, meaning active background output won't corrupt your selection.

Installation (TPM)

Add to your ~/.tmux.conf:

setw -g mode-keys vi
set -g @plugin 'killkli/tmux-ci-ca'

(Manual installation without TPM is also supported).

Requirements

• tmux 3.2+ • Bash 3.2+ • Any standard awk

Check it out on GitHub: https://github.com/killkli/tmux-ci-ca

Feedback, bug reports, and suggestions are very welcome!

GIF demo added~


r/tmux • • 10d ago

Showcase libtmux-ruby 0.1: tmux client for ruby

Thumbnail
github.com
4 Upvotes

I am porting libtmux, the Python library, to more languages. This is the Ruby port.

One of the ways this differs is keeping snapshots you can query with Ruby objects and blocks. There's also control mode support, and a separate Async gem. See the earlier posts for Rust, TypeScript, and Golang.

A word on AI: It's experimental, and I used LLMs extensively to create this. I write libtmux's AI policy at https://libtmux.org/en/meta/ai-policy/.

libtmux core: tmux from Ruby

RubyGems · GitHub · Homepage · Guides · API Explorer

What's interesting:

Requires Ruby 3.3+, tmux 3.3a+ and build tools for Ruby native extensions.

gem install libtmux

Save as demo.rb. Server.start creates a private tmux server and closes it when the block exits. The queries read a snapshot; the pane input and capture run while the server is open.

require "libtmux"
require "timeout"

LibTmux::Server.start do |server|
  session = server.new_session(name: "demo", command: ["/bin/cat"])
  window = session.new_window(name: "logs", command: ["/bin/cat"])
  created = window.split(direction: :horizontal, command: ["/bin/sh"])
  server.run(["select-pane", "-t", created.id, "-T", "build"])

  snapshot = server.snapshot
  session = snapshot.sessions.where(name: "demo").one
  window = session.windows.where(name: { starts_with: "log" }).one
  matched = window.panes.where(title: "build").one
  puts "#{session.name} / #{window.name} / #{matched.title}"

  pane = server.pane(matched.ref)
  pane.send_text("printf 'build: %s\\n' complete")
  pane.send_keys("Enter")
  output = Timeout.timeout(5) do
    loop do
      line = pane.capture.stdout.lines.find { |row| row.chomp == "build: complete" }
      break line.chomp if line

      sleep 0.05
    end
  end
  puts "output: #{output}"
end

ruby demo.rb

Prints:

demo / logs / build
output: build: complete

Pane#capture reads what tmux has on screen. The loop waits up to five seconds for the line from our command (more pane I/O).

P.S. Change the window filter from starts_with: "log" to starts_with: "log2" and run it again. From the error:

selection has no matches (LibTmux::NoMatchError)

.one raises NoMatchError if nothing matches, or MultipleMatchesError if more than one does.

Async: queries and control mode

There is also an Async gem for concurrent calls and streams: README, Guide, API.

Same idea, but inside an Async scope. We can chain where calls, then use control mode to rename a window and hear about the change from tmux. This example needs tmux 3.7+.

gem install libtmux-async

Save as async-demo.rb:

require "libtmux"
require "libtmux/async"

LibTmux::Server.start do |server|
  session = server.new_session(name: "demo", command: ["/bin/cat"])
  window = session.new_window(name: "logs", command: ["/bin/cat"])
  server.run(["select-pane", "-t", window.list_panes.fetch(0).id, "-T", "build"])

  Async do |parent|
    LibTmux::Async.open(parent: parent, server: server) do |scope|
      snapshot = scope.server.snapshot
      session = snapshot.sessions.where(name: "demo").one
      window = session.windows.where(name: { starts_with: "log" }).one
      pane = window.panes.where(active: true).where(title: "build").one
      puts "#{session.name} / #{window.name} / #{pane.title}"

      scope.server.open_control(session: session.ref) do |control|
        events = control.events
        renamed = parent.async do
          event = events.next(timeout: 5) until event&.raw&.start_with?("%window-renamed")
          puts "event: #{event.raw.strip}"
        end
        control.exchange("rename-window -t #{window.id} compiling", timeout: 5)
        renamed.wait
        puts "window now: #{scope.server.window(window.ref).snapshot.name}"
      end
    end
  end.wait
end

ruby async-demo.rb

Prints:

demo / logs / build
event: %window-renamed @1 compiling
window now: compiling

The queries still read a snapshot. events.next waits for tmux while the other task sends the command with exchange. We read the window again after the event. There are also examples of concurrent captures and cancellation.

MCP

RubyGems · GitHub · Homepage · Guides · Tools · Resources · API Explorer

An MCP server for interacting with tmux - powered by the Ruby core library. Same idea as Python's libtmux-mcp!

gem install libtmux-mcp

This MCP server connects to an existing tmux server. For a demo, start one on its own socket:

tmux -L libtmux-ruby-mcp-demo -f /dev/null new-session -d -s demo

Use this command with a client that launches stdio MCP servers:

libtmux-mcp --socket-name libtmux-ruby-mcp-demo --endpoint demo

It waits for MCP requests over stdin. tmux_capabilities and tmux_snapshot are enabled by default; the guides cover enabling other tools.

After closing the MCP client, remove the demo server:

tmux -L libtmux-ruby-mcp-demo kill-server

Workspace manager

This is like tmuxp, but in Ruby! Uses the libtmux core library.

Workspace library

RubyGems · GitHub · Homepage · Guides · API Explorer

gem install libtmux-workspace

A subset of tmuxp's configuration format. Save as workspace.yaml:

session_name: demo
windows:
  - window_name: shells
    layout: even-horizontal
    panes:
      - {}
      - {}

Save as workspace.rb. Workspace.load reads the file; plan.apply creates its session (example).

require "libtmux"
require "libtmux/workspace"

LibTmux::Server.start do |server|
  workspace = LibTmux::Workspace.load(File.expand_path("workspace.yaml", __dir__))
  result = workspace.plan(snapshot: server.snapshot).apply(server: server)
  puts "applied: #{result.success?}"
  puts "panes: #{server.snapshot.windows.one(name: 'shells').panes.size}"
end

ruby workspace.rb

Prints:

applied: true
panes: 2

Workspace CLI

The same gem includes the command: GitHub, Homepage, Guides, CLI reference, API.

Validate the file:

libtmux-workspace validate workspace.yaml

Prints:

Workspace configuration is valid.

Load it on a separate running server:

tmux -S "$PWD/workspace.sock" -f /dev/null new-session -d -s keepalive

libtmux-workspace load --socket "$PWD/workspace.sock" workspace.yaml

Check the created panes:

tmux -S "$PWD/workspace.sock" display-message -p -t demo:shells '#{window_panes}'

Prints:

2

Remove the demo server:

tmux -S "$PWD/workspace.sock" kill-server

r/tmux • • 10d ago

Showcase couchdeck: your tmux sessions as tap-to-attach cards on your phone

7 Upvotes

I love the Claude remote app, so I tried to get a similar phone UI for any CLI, not just Claude. This is what I ended up with: couchdeck.

It shows every tmux session on your machine as a card, so you can see at a glance which agent is working or waiting on a prompt. Tap one to attach to a full terminal, or start a new Claude Code, Codex, opencode, Grok or plain shell session in any project folder without typing on a phone keyboard. Leaving just detaches, so nothing gets killed.

I use it daily as a remote CLI on my phone. All it needs is Tailscale and tmux 3.2+.

Heads up: it has no login by design, so keep it on your tailnet and never expose it publicly. It's free and open source.

https://github.com/frasod/couchdeck


r/tmux • • 10d ago

Question What's the point of having Termux in mobile

Thumbnail reddit.com
0 Upvotes

r/tmux • • 11d ago

Showcase libtmux-go 0.1: tmux client library, mcp, workspace manager for golang

Thumbnail
github.com
2 Upvotes

I am porting libtmux, the Python library, to more languages. This is the Go port.

You can read a snapshot and query it with typed filters. It also has operation planning and control mode support (!). See the earlier Rust and TypeScript ports.

A word on AI: It's experimental, and I used LLMs extensively to create this. I write libtmux's AI policy at https://libtmux.org/en/meta/ai-policy/.

libtmux core: tmux from Go

pkg.go.dev · GitHub · Homepage · Guides · API Explorer

The core module has three packages:

PackageWhat it's forLinks
tmuxServers, sessions, windows, panes, snapshots and control mode.pkg.go.dev · GitHub
tmuxqQuery helpers for slices and iter.Seq, including your own types. It doesn't need tmux.pkg.go.dev · GitHub
tmux/tmuxtestRun terminal programs in tests, type into them and check their output.pkg.go.dev · GitHub

Workspace and MCP are separate modules, below. The core has no third-party Go dependencies.

What's interesting:

The example needs Go 1.26+ and tmux 3.3a+. Start in a new directory:

go mod init example.com/tmux-demo

go get github.com/libtmux/libtmux-go/tmux@latest

Save as main.go. It creates a separate server, then matches a session name, a window name and a pane title in a snapshot. It removes the server afterward.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/libtmux/libtmux-go/tmux"
	"github.com/libtmux/libtmux-go/tmuxq"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) (err error) {
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: fmt.Sprintf("libtmux-go-demo-%d", os.Getpid()),
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return err
	}
	session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "demo"})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, server.Kill(context.WithoutCancel(ctx))) }()

	window, err := session.NewWindow(ctx, tmux.NewWindowRequest{Name: new("logs"), Command: "cat"})
	if err != nil {
		return err
	}
	panes, loaded := window.Panes()
	if !loaded || len(panes) != 1 {
		return fmt.Errorf("expected the new window's pane")
	}
	if _, err = panes[0].SetTitle(ctx, "build"); err != nil {
		return err
	}

	snapshot, err := server.Snapshot(ctx)
	if err != nil {
		return err
	}
	where := tmux.PaneFilter{
		Title:   new("build"),
		Session: &tmux.SessionFilter{Name: new("demo")},
		Window:  &tmux.WindowFilter{Name: new("logs")},
	}
	matches, err := tmuxq.Matching(snapshot.Panes(), where)
	if err != nil {
		return err
	}
	fmt.Println("matching panes:", len(matches))
	return nil
}

go run main.go

Prints:

matching panes: 1

Batching and queries

We can also record a plan, then run it. This one splits a pane, names it build, sends it a line and reads its title back. The pane runs cat, which echoes what we type.

Plan.Explain shows how the commands will be grouped. This example groups six operations into four invocations for the plan; creating the server and reading snapshots are separate (more planning examples).

Use the same module as above. Save as batching/main.go (create the batching directory):

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
	"github.com/libtmux/libtmux-go/tmuxq"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() (err error) {
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: fmt.Sprintf("libtmux-go-batch-%d", os.Getpid()),
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return err
	}
	session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "demo"})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, server.Kill(context.WithoutCancel(ctx))) }()
	window, err := session.NewWindow(ctx, tmux.NewWindowRequest{
		Name: new("logs"), Command: "cat",
	})
	if err != nil {
		return err
	}

	plan := tmux.NewPlan()
	plan.SelectLayout(window.Ref(), tmux.SelectLayoutRequest{Layout: "tiled"})
	pane := plan.SplitPane(window.Ref(), tmux.SplitPaneRequest{Command: "cat"})
	plan.SetPaneTitle(pane, "build")
	plan.SendKeys(pane, tmux.SendKeysRequest{Command: new("build: complete")})
	plan.DisplayMessage(pane, "#{pane_title}")
	fmt.Printf("planned operations: %d, command groups: %d\n", plan.Len(), len(plan.Explain()))

	result, err := plan.Run(ctx, server)
	if err != nil {
		return err
	}
	if !result.OK() {
		return result.Err()
	}
	fmt.Printf("title read by plan: %q\n", result.Ops[len(result.Ops)-1].Stdout)

	snapshot, err := server.Snapshot(ctx)
	if err != nil {
		return err
	}
	predicate, err := (tmux.PaneFilter{
		Title:   new("build"),
		Session: &tmux.SessionFilter{Name: new("demo")},
		Window:  &tmux.WindowFilter{Name: new("logs")},
	}).Predicate()
	if err != nil {
		return err
	}
	panes := snapshot.Panes()
	fmt.Println("snapshot matches:", len(tmuxq.Where(panes, predicate)))
	only, err := tmuxq.ExactlyOne(panes, predicate)
	if err != nil {
		return err
	}
	title, _ := only.Title()
	fmt.Println("only matching pane:", title)

	live := tmux.TmuxFilter("#{==:#{pane_title},build}")
	fresh, err := window.SearchPanes(ctx, &live)
	if err != nil {
		return err
	}
	fmt.Println("live matches:", len(fresh))
	return nil
}

go run ./batching

Prints:

planned operations: 6, command groups: 4
title read by plan: ["build"]
snapshot matches: 1
only matching pane: build
live matches: 1

The two snapshot queries reuse a compiled predicate and make no more tmux calls. ExactlyOne returns ErrNoMatch or ErrMultipleMatches when appropriate.

For a fresh read, SearchPanes passes the TmuxFilter expression to tmux's -f filter (both styles together). Typed predicates run in Go; tmux format expressions run in tmux. There are also WhereSeq and FirstSeq for lazy queries over iterators (source).

Control mode and channels

There's also control mode (!). This example keeps a command connection open, listens for a session rename, and does three reads through that same connection. It needs tmux 3.7+ (connection example).

Notifications returns a Go iterator. Here, a goroutine reads it and sends the rename result through an ordinary channel. The notification stream has its own attached tmux client.

Save as control/main.go (create the control directory):

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() (err error) {
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: fmt.Sprintf("libtmux-go-control-%d", os.Getpid()),
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return err
	}
	session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "demo"})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, server.Kill(context.WithoutCancel(ctx))) }()

	connection, err := session.OpenControl(ctx, tmux.ConnectionOptions{})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, connection.Close()) }()
	connected := connection.Session()
	stream, err := session.OpenNotifications(ctx, tmux.NotificationOptions{})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, stream.Close()) }()

	renamed := make(chan error, 1)
	go func() {
		for notification, err := range stream.Notifications(ctx) {
			if err != nil {
				renamed <- err
				return
			}
			if notification.Kind() == tmux.ControlNotificationSessionRenamed {
				renamed <- nil
				return
			}
		}
		renamed <- errors.New("notification stream ended before the rename")
	}()

	if _, err := connected.Rename(ctx, "renamed"); err != nil {
		return err
	}
	select {
	case err := <-renamed:
		if err != nil {
			return err
		}
		fmt.Println("heard session rename over a channel")
	case <-ctx.Done():
		return ctx.Err()
	}

	for range 3 {
		windows, err := connected.SearchWindows(ctx, nil)
		if err != nil {
			return err
		}
		fmt.Println("windows over control connection:", len(windows))
	}
	return nil
}

go run ./control

Prints:

heard session rename over a channel
windows over control connection: 1
windows over control connection: 1
windows over control connection: 1

Keep the handle returned by connection.Session() for those calls. The original session still uses subprocesses. You can also subscribe to a tmux format and hear when a value like the window count changes.

Testing a terminal program

tmuxtest gives each test a real tmux server and cleans it up afterward. This one runs a small greeter, types world and waits for hello, world to appear (complete repository example).

Save as terminal-test/greeter_test.go (create the terminal-test directory):

package terminal_test

import (
	"context"
	"os"
	"testing"
	"time"

	"github.com/libtmux/libtmux-go/tmux/tmuxtest"
)

func TestMain(m *testing.M) {
	os.Exit(tmuxtest.Main(m))
}

func TestGreeterAnswersALine(t *testing.T) {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	greeter := `while read name; do echo "hello, $name"; done`
	pane := tmuxtest.RunInPane(ctx, t, greeter)
	tmuxtest.Type(ctx, t, pane, "world")
	tmuxtest.WaitForLine(ctx, t, pane, "hello, world")
}

go test -count=1 ./terminal-test

It prints ok with the package name and elapsed time. RunInPane starts the program; Type sends input; WaitForLine checks the screen. tmuxtest.Main keeps the suite's tmux servers separate from yours.

P.S. Change the expected line to "goodbye, world" to see a failure with the pane's contents. For tests that only need command responses, there's also ScriptedTmux (example).

MCP

pkg.go.dev · GitHub · Homepage · Guides · Tools · Resources · API Explorer

An MCP server for interacting with tmux - powered by the Go core library (like libtmux-mcp!).

Install the command into this directory's bin folder:

GOBIN="$PWD/bin" go install github.com/libtmux/libtmux-go/mcp/cmd/libtmux-mcp@latest

Start a separate tmux server for the demo:

tmux -L libtmux-go-mcp-demo -f /dev/null new-session -d -s demo

Use this command with a client that launches stdio MCP servers:

./bin/libtmux-mcp -socket-name libtmux-go-mcp-demo

It waits for MCP requests over stdin. The tools cover reading sessions, running commands and inspecting pane output.

After closing the client, remove the demo server:

tmux -L libtmux-go-mcp-demo kill-server

Workspace manager

This is like tmuxp, but in Go! There's a workspace library and a CLI using the same core.

Workspace library

pkg.go.dev · GitHub · Homepage · Guides · API Explorer

go get github.com/libtmux/libtmux-go/workspace@latest

Save as workspace.yaml:

session_name: demo
windows:
  - window_name: shells
    layout: even-horizontal
    panes:
      - {}
      - {}

Save as workspace-demo/main.go. workspace.Parse reads the configuration and workspace.Build creates the session (example).

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/libtmux/libtmux-go/tmux"
	"github.com/libtmux/libtmux-go/workspace"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) (err error) {
	data, err := os.ReadFile("workspace.yaml")
	if err != nil {
		return err
	}
	config, err := workspace.Parse(data)
	if err != nil {
		return err
	}
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: fmt.Sprintf("libtmux-go-workspace-%d", os.Getpid()),
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return err
	}
	defer func() { err = errors.Join(err, server.Kill(context.WithoutCancel(ctx))) }()
	session, err := workspace.Build(ctx, server, config)
	if err != nil {
		return err
	}
	windows, err := session.SearchWindows(ctx, nil)
	if err != nil {
		return err
	}
	fmt.Println("windows:", len(windows))
	return nil
}

Run from the directory holding workspace.yaml:

go run ./workspace-demo

Prints:

windows: 1

Workspace CLI

pkg.go.dev · GitHub · Homepage · Guides · CLI reference · API

GOBIN="$PWD/bin" go install github.com/libtmux/libtmux-go/workspace/cmd/tmux-workspace@latest

Load the same file detached, on a separate socket:

./bin/tmux-workspace load -L libtmux-go-workspace-demo -d workspace.yaml

Check the panes:

tmux -L libtmux-go-workspace-demo display-message -p -t demo:shells '#{window_panes}'

Prints:

2

Remove the demo server:

tmux -L libtmux-go-workspace-demo kill-server

r/tmux • • 12d ago

Showcase Keeping track of coding agents across tmux panes from the notch

0 Upvotes

I run Claude Code and Codex in a bunch of tmux panes and never knew which one was stuck waiting for me. So I built Openbar: every session in one list in the notch, the one that needs you jumps to the top, "Open" switches to the right tmux pane, and you can send a reply straight into it.

Free, open source: https://github.com/MF-DEEV/Openbar

How do you all keep tabs on long-running stuff in tmux? Curious if anyone does this with plain status line tricks.


r/tmux • • 12d ago

Question Still running coding agents in tmux, or did you move to herdr? Curious why

71 Upvotes

I run 4-6 Claude Code / Codex sessions across tmux sessions every day. herdr (a Rust multiplexer built around coding agents) keeps coming up, and on paper it covers most of what I use tmux for: a server you detach from, splits with prefix keys, plugins, and it marks each pane working / blocked / idle.

I'm still on tmux, honestly out of habit: my .tmux.conf has keybindings and plugins I'm used to, the same way I stay on Neovim. I've never seriously compared the two, so I'm curious what herdr actually does better (lighter? faster? or just the agent features?).I've seen the plugin posts here, but not much about why people stay on tmux or leave. I'd like to hear from people who made the call either way:

  1. If you stayed on tmux for agent work, what does your setup look like? How do you notice which agent needs you (hooks, status bar, notifications, a plugin like tmux-agent-status, tmux-agent-wizard or workmux), and how do you lay out sessions, windows and worktrees?

  2. If you moved to herdr (or Zellij, or something else), what was the deciding feature, and what do you miss from tmux?

  3. What do you think tmux still lacks for this kind of work?

This is my current setup. The sidebar on the left is a small plugin I wrote, party-hud: every tmux session is a squad, and each agent shows whether it's waiting for me, context left and prompt cache minutes left (https://github.com/mangow314/party-hud). It covers the "who needs me" part, but I'm more interested in how others handle this than in pitching it.