tmux

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package tmux provides a general-purpose Go client for managing tmux sessions. This package is designed to be self-contained and can be used by any Go application that needs to programmatically control tmux sessions.

The package provides functionality to:

  • Create and manage tmux sessions
  • Launch sessions with complex multi-pane configurations
  • Monitor sessions and wait for them to close
  • Capture pane content
  • Check session existence

Example usage: 

client, err := tmux.NewClient()
if err != nil {
    log.Fatal(err)
}

opts := tmux.LaunchOptions{
    SessionName: "my-session",
    Panes: []tmux.PaneOptions{
        {Command: "vim main.go"},
        {Command: "go test -v"},
    },
}

if err := client.Launch(ctx, opts); err != nil {
    log.Fatal(err)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Command 

func Command(args ...string) *exec.Cmd

Command creates an exec.Cmd for tmux that respects GROVE_TMUX_SOCKET. Use this instead of exec.Command("tmux", ...) for socket-aware operations when you need a raw *exec.Cmd (e.g., for AttachStdin/Stdout). For most operations, prefer using the Client methods instead.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient() (*Client, error)

func NewClientWithSocket 

func NewClientWithSocket(socket string) (*Client, error)

NewClientWithSocket creates a tmux client that uses a dedicated server socket. This provides isolation from the default tmux server.

func (*Client) CapturePane 

func (c *Client) CapturePane(ctx context.Context, target string) (string, error)

func (*Client) ClosePopup 

func (c *Client) ClosePopup(ctx context.Context) error

ClosePopup closes the current tmux popup synchronously. This is useful when you need to close a popup immediately before quitting a TUI.

func (*Client) ClosePopupCmd 

func (c *Client) ClosePopupCmd() *exec.Cmd

SwitchAndClosePopup switches to a tmux session and closes the current popup if running in one. This ensures the popup closes regardless of whether the binding has the -E flag.

The method executes the switch synchronously, then returns a command to close the popup that should be executed after the TUI exits.

Example usage from a bubbletea Update function: 

client, _ := tmux.NewClient()
if err := client.SwitchClient(ctx, sessionName); err != nil {
    // handle error
}
model.CommandOnExit = client.ClosePopupCmd()
return model, tea.Quit

func (*Client) FocusOrRunCommandInWindow 

func (c *Client) FocusOrRunCommandInWindow(ctx context.Context, command, windowName string, windowIndex int) error

FocusOrRunCommandInWindow ensures a window with the given name exists, runs the command, and focuses it. If the window already exists, it just switches to it without killing it (preserving any work in progress). If the window doesn't exist, it creates it at the specified index.

func (*Client) FocusOrRunTUIWithErrorHandling 

func (c *Client) FocusOrRunTUIWithErrorHandling(ctx context.Context, command, windowName string, windowIndex int) error

FocusOrRunTUIWithErrorHandling runs a TUI command in a tmux window with error handling. If the window exists, it focuses it. If not, it creates the window and runs the command. If the command fails, it displays the error and opens a shell for debugging.

func (*Client) GetCurrentPaneID 

func (c *Client) GetCurrentPaneID(ctx context.Context) (string, error)

GetCurrentPaneID returns the ID of the currently active pane

func (*Client) GetCurrentSession 

func (c *Client) GetCurrentSession(ctx context.Context) (string, error)

func (*Client) GetCursorPosition 

func (c *Client) GetCursorPosition(ctx context.Context, sessionName string) (row int, col int, err error)

GetCursorPosition returns the 1-based row and column of the cursor in the specified session's active pane.

func (*Client) GetPaneCommand 

func (c *Client) GetPaneCommand(ctx context.Context, target string) (string, error)

func (*Client) GetPaneWidth 

func (c *Client) GetPaneWidth(ctx context.Context, target string) (int, error)

GetPaneWidth returns the width of the specified pane (or current pane if target is empty)

func (*Client) GetSessionPID 

func (c *Client) GetSessionPID(ctx context.Context, sessionName string) (int, error)

GetSessionPID returns the process ID of the tmux server for a given session.

func (*Client) GetSessionPath 

func (c *Client) GetSessionPath(ctx context.Context, sessionName string) (string, error)

GetSessionPath returns the working directory path of a specific tmux session.

func (*Client) GetWindowPaneID 

func (c *Client) GetWindowPaneID(ctx context.Context, windowTarget string) (string, error)

GetWindowPaneID returns the active pane ID for a given window target.

func (*Client) InsertWindowAt 

func (c *Client) InsertWindowAt(ctx context.Context, session, windowName string, targetIndex int) error

InsertWindowAt moves a window to a specific position Uses tmux's swap-window to avoid renumbering issues

func (*Client) IsPopup 

func (c *Client) IsPopup(ctx context.Context) (bool, error)

IsPopup checks if the current pane is inside a tmux popup window.

func (*Client) KillServer 

func (c *Client) KillServer(ctx context.Context) error

KillServer kills the tmux server for this client's socket. This is useful for cleaning up isolated test servers. If the client uses the default socket, this will kill the default tmux server (use with caution!).

func (*Client) KillSession 

func (c *Client) KillSession(ctx context.Context, sessionName string) error

func (*Client) KillWindow 

func (c *Client) KillWindow(ctx context.Context, target string) error

func (*Client) Launch 

func (c *Client) Launch(ctx context.Context, opts LaunchOptions) error

func (*Client) ListSessions 

func (c *Client) ListSessions(ctx context.Context) ([]string, error)

func (*Client) ListWindows 

func (c *Client) ListWindows(ctx context.Context, session string) ([]int, error)

ListWindows returns a list of window indices for the current session

func (*Client) ListWindowsDetailed 

func (c *Client) ListWindowsDetailed(ctx context.Context, sessionName string) ([]Window, error)

ListWindowsDetailed returns a list of windows with detailed information for the given session.

func (*Client) MoveWindow 

func (c *Client) MoveWindow(ctx context.Context, source, target string) error

func (*Client) NewWindow 

func (c *Client) NewWindow(ctx context.Context, target, windowName, command string) error

func (*Client) NewWindowAndClosePopup 

func (c *Client) NewWindowAndClosePopup(ctx context.Context, sessionName, windowName, command string) (*exec.Cmd, error)

NewWindowAndClosePopup switches to a session, creates a new window, and closes the popup. Returns a command to be executed after the TUI exits.

func (*Client) NewWindowWithOptions 

func (c *Client) NewWindowWithOptions(ctx context.Context, opts NewWindowOptions) error

NewWindowWithOptions creates a new window with extended options.

func (*Client) OpenInEditorWindow 

func (c *Client) OpenInEditorWindow(ctx context.Context, editorCmd, filePath, windowName string, windowIndex int, reset bool) error

OpenInEditorWindow finds or creates a window with a given name and opens a file. If the window exists, it's focused. If a file is provided, it's opened in the existing editor session. A new session can be forced with the reset flag.

func (*Client) PaneExists 

func (c *Client) PaneExists(ctx context.Context, paneID string) bool

PaneExists checks if a pane with the given ID exists

func (*Client) RenameWindow 

func (c *Client) RenameWindow(ctx context.Context, target string, newName string) error

RenameWindow renames a tmux window.

func (*Client) SelectPane 

func (c *Client) SelectPane(ctx context.Context, paneID string) error

SelectPane switches focus to the specified pane

func (*Client) SelectWindow 

func (c *Client) SelectWindow(ctx context.Context, target string) error

func (*Client) SelectWindowAndClosePopup 

func (c *Client) SelectWindowAndClosePopup(ctx context.Context, sessionName, windowName string) (*exec.Cmd, error)

SelectWindowAndClosePopup switches to a session, selects a window, and closes the popup. Returns a command to be executed after the TUI exits.

func (*Client) SendKeys 

func (c *Client) SendKeys(ctx context.Context, target string, keys ...string) error

func (*Client) SessionExists 

func (c *Client) SessionExists(ctx context.Context, sessionName string) (bool, error)

func (*Client) SetGlobalEnvironment 

func (c *Client) SetGlobalEnvironment(ctx context.Context, env map[string]string) error

SetGlobalEnvironment sets environment variables at the tmux server level. These variables will be inherited by all new sessions and windows. Use this to configure the environment for an isolated tmux server (e.g., demo environments).

func (*Client) SetPaneEnvironment 

func (c *Client) SetPaneEnvironment(ctx context.Context, paneTarget string, env map[string]string) error

SetPaneEnvironment sets environment variables for a specific pane by sending export commands. This affects the shell running in the pane for its entire lifetime. Commands are prefixed with a space to prevent shell history pollution.

func (*Client) Socket 

func (c *Client) Socket() string

Socket returns the socket name this client uses, or empty string for default.

func (*Client) SplitWindow 

func (c *Client) SplitWindow(ctx context.Context, target string, horizontal bool, size int, command string) (string, error)

SplitWindow splits a target pane and optionally runs a command. target can be a session, window, or pane identifier. Use "" for the current pane. If horizontal is true, it creates a vertical split (side-by-side panes). size, if > 0, specifies the width (for horizontal) or height (for vertical) of the new pane in cells. Returns the pane ID of the newly created pane.

func (*Client) SwapWindow 

func (c *Client) SwapWindow(ctx context.Context, source, target string) error

func (*Client) SwitchClient 

func (c *Client) SwitchClient(ctx context.Context, target string) error

func (*Client) SwitchClientToSession 

func (c *Client) SwitchClientToSession(ctx context.Context, sessionName string) error

SwitchClientToSession switches the client to the specified session. It uses an exact match for the session name to avoid ambiguity.

func (*Client) WaitForSessionClose 

func (c *Client) WaitForSessionClose(ctx context.Context, sessionName string, pollInterval time.Duration) error

type LaunchOptions 

type LaunchOptions struct {
	SessionName      string
	WorkingDirectory string
	WindowName       string
	WindowIndex      int // Window index to position the window at (-1 = no specific index)
	Panes            []PaneOptions
}

type NewWindowOptions 

type NewWindowOptions struct {
	Target     string
	WindowName string
	Command    string
	WorkingDir string
	Env        []string // Environment variables in "KEY=VALUE" format
}

NewWindowOptions provides detailed options for creating a new window.

type PaneOptions 

type PaneOptions struct {
	Command          string
	WorkingDirectory string
	SendKeys         string
	Env              map[string]string // Environment variables to set in the pane
}

type Window 

type Window struct {
	ID       string `json:"id"`
	Index    int    `json:"index"`
	Name     string `json:"name"`
	IsActive bool   `json:"is_active"`
	Command  string `json:"command"` // Active pane's command
	PID      int    `json:"pid"`     // Active pane's PID
}

Window holds detailed information about a tmux window.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.