Introducing gotmucks: Programmatic tmux Control in Go
An open-source Go library for driving tmux programmatically: typed sessions, commands, output capture, and live events through control mode.
gotmucks is an open-source Go library for interacting with tmux programmatically. It provides a typed API for managing tmux sessions, executing commands, capturing terminal output, and receiving real-time events through tmux control mode.
The library is intended for developers building terminal automation, remote development tools, agent orchestration systems, and other Go applications that need to interact with tmux.
Why gotmucks?
tmux is commonly used to run long-lived terminal processes that survive SSH disconnections. It also exposes functionality that applications can use to manage and observe those processes.
Go applications can interact with tmux by invoking its executable through os/exec, but that requires managing command arguments, parsing output, handling identifiers, and implementing the control-mode protocol when live events are needed.
gotmucks provides these capabilities as a reusable Go library.
What can you do with it?
| Capability | Description |
|---|---|
| Session management | Create, list, inspect, and terminate tmux sessions |
| Terminal interaction | Send keys and commands to panes |
| Output capture | Retrieve terminal output programmatically |
| Control mode | Maintain a persistent connection to tmux |
| Live events | Receive pane output and asynchronous notifications |
| Options and hooks | Configure tmux options and hooks |
| Typed API | Work with session, window, and pane identifiers |
Getting started
Install the package:
go get github.com/counterflow/gotmucks
Create a tmux session and capture its output:
c := gotmucks.New(gotmucks.WithSocketName("myapp"))
s, err := c.NewSession(ctx, gotmucks.NewSessionOptions{
Name: "build",
Command: []string{"go", "test", "./..."},
})
if err != nil {
return err
}
panes, err := c.ListSessionPanes(ctx, s.ID)
if err != nil {
return err
}
out, err := c.CapturePane(
ctx,
panes[0].ID,
gotmucks.CaptureOptions{},
)
Real-time monitoring with control mode
For applications requiring continuous monitoring, gotmucks supports tmux control mode (tmux -C).
Instead of repeatedly executing tmux commands to capture output, applications can maintain a persistent connection and receive events as they occur.
cc, err := gotmucks.Connect(
ctx,
gotmucks.WithSocketName("myapp"),
gotmucks.WithAttach(s.ID),
)
if err != nil {
return err
}
defer cc.Close()
for ev := range cc.Events() {
switch e := ev.(type) {
case gotmucks.PaneOutput:
os.Stdout.Write(e.Data)
case gotmucks.Exited:
return nil
}
}
This is particularly useful for applications that need to monitor long-running processes without continuously polling their output.
Example applications
- AI coding agents: Launch agents in tmux sessions and observe their terminal output.
- Remote development tools: Manage long-running development processes over SSH.
- Terminal dashboards: Monitor multiple tmux sessions from a Go application.
- Build and test automation: Run commands in persistent sessions and retrieve their output.
- Developer tooling: Build custom applications that interact with tmux programmatically.
Implementation details
gotmucks uses stable tmux identifiers rather than relying on session names or window indexes. It also uses structured format strings for parsing output.
The control-mode client supports asynchronous notifications, concurrent command requests, and event buffering with dropped-event reporting.
The library uses only the Go standard library and requires tmux 3.2 or later and Go 1.22 or later.
Source code
gotmucks is available under the MIT licence.