tmux MCP server

libtmux for Go

Alpha software. Releases carry an -alpha prerelease tag, the API is not settled, and any release may change or remove exported identifiers without a deprecation period. Pin an exact version. Not recommended for production.

Drive tmux from Go: sessions, windows, and panes as typed values, every tmux option and hook as a typed accessor, and errors classified by what tmux actually refused.

MCP modules. The compatibility matrix checks ten builds spanning that range, the 3.8 release candidate included. The Go floor tracks upstream's support window, which covers the two most recent releases, so it rises whenever a Go release retires the oldest - roughly twice a year, and sooner than a toolchain pinned for longer.

• No runtime dependencies. The core module imports only the standard library.
• Go 1.26+, tmux 3.2a through 3.8-rc across the core, workspace, and

when you asked, not a live handle that changes underneath.

• Records never refresh behind you. A Session you hold is what tmux said

macOS run the suites on every change, and the BSDs, illumos and Plan 9 build. A Windows build compiles and resolves a tmux executable by Windows PATH and PATHEXT rules, so a cross-platform program still builds; it has no tmux to reach.

• Unix. tmux is a Unix program, so driving one needs a Unix host: Linux and

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

Modules are tagged per directory, so each consumer carries its own version: the tags are mcp/vN and workspace/vN beside the core's plain vN. Pin the exact ones you want in your own go.mod; the commands here fetch the newest.

Contents — Quick start · Querying · Choosing a mode · Watching tmux · Packages · For agents · Testing your code · Documentation

Quick start

Make a window, split it, type a command into the new pane, and read the reply back through an io.Reader:

<!-- docs:quickstart -->

// Given: ctx context.Context; server tmux.Server
session, err := server.NewSession(ctx, tmux.NewSessionRequest{
	Name: "libtmux-go-quickstart", WindowName: "start",
})
if err != nil {
	return fmt.Errorf("create session: %w", err)
}
defer func() {
	cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
	defer cleanupCancel()
	err = errors.Join(err, session.Kill(cleanupCtx))
}()

window, err := session.NewWindow(ctx, tmux.NewWindowRequest{Name: new("work")})
if err != nil {
	return fmt.Errorf("create window: %w", err)
}
pane, err := window.SplitPane(ctx, tmux.SplitPaneRequest{
	Direction: tmux.PaneDirectionRight, Command: "sh",
})
if err != nil {
	return fmt.Errorf("split window: %w", err)
}
output, err := pane.OpenObservation(ctx)
if err != nil {
	return fmt.Errorf("watch pane: %w", err)
}
defer func() { err = errors.Join(err, output.Close()) }()
if _, err := fmt.Fprintln(pane.Writer(ctx), "printf 'libtmux ready\\n'"); err != nil {
	return fmt.Errorf("send command: %w", err)
}

<!-- docs:end -->

Every Go block below marked this way is generated from a program in examples/ that is compiled, linted, run against a real tmux, and swept across every supported release — so none of it can drift from code that works.

Runnable: examples/quickstart — go -C examples run ./quickstart.

Running a command to completion

Shortened. The full README is on GitHub.