Capture pane output

Edit this page on GitHub

The other half of Attach and send keys: reading what a pane printed, and — since tmux accepts a command before the shell running it has necessarily finished (see Sending keys) — waiting for the right moment to read rather than reading immediately or sleeping a guessed amount. Capturing output is the guide-level discussion of why each pattern below exists; this page is the sourced code behind it — see the table at the end for exactly which file each block came from and how it’s checked.

Read what’s on screenLink to section

// From examples/quickstart/main.go, shown in full on Attach and send keys.
lines, err := pane.Capture(ctx, tmux.CapturePaneRequest{
  Start: tmux.CaptureBoundary,
  End:   tmux.CaptureBoundary,
})

No checked .NET example calls the ordinary Pane.CaptureAsync by itself outside a wait — the README’s own read is the block under “Wait for text instead of guessing a delay” below, and the separate Psmux surface has its own CaptureAsync for that different transport (examples/LibTmux.Examples/Snippets/Psmux.cs).

Wait for text instead of guessing a delayLink to section

Python’s checked wait is wait_for, tmux’s own signal channel, rather than a helper that scrapes pane text for a pattern — no checked helper that waits on pane text was found in the source for this page.

// Command control-mode-subscribe watches a persistent tmux control client
// receive changes without polling.
package main

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

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

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

// start owns cleanup because log.Fatal skips deferred calls in main.
func start() error {
  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
  defer cancel()

  server, err := tmux.NewServer(tmux.ServerOptions{})
  if err != nil {
    return fmt.Errorf("configure tmux server: %w", err)
  }
  return run(ctx, server)
}

// run accepts injected server state so tests can isolate the example.
func run(ctx context.Context, server tmux.Server) (err error) {
  session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "libtmux-control"})
  if err != nil {
    return fmt.Errorf("create session: %w", err)
  }
  defer func() {
    cleanupCtx, cleanupCancel := context.WithTimeout(context.Background(), time.Second)
    defer cleanupCancel()
    err = errors.Join(err, session.Kill(cleanupCtx))
  }()

  // docs:watching
  stream, err := session.OpenNotifications(ctx, tmux.NotificationOptions{})
  if err != nil {
    return fmt.Errorf("open notification stream: %w", err)
  }
  defer func() { err = errors.Join(err, stream.Close()) }()

  // Rename after subscribing; notifications do not include earlier changes.
  if _, err := session.Rename(ctx, "control-example"); err != nil {
    return fmt.Errorf("rename session: %w", err)
  }

  for {
    notification, err := stream.Next(ctx)
    if err != nil {
      return fmt.Errorf("read notification: %w", err)
    }
    fmt.Printf("notification: %s\n", notification.Kind())
    if notification.Kind() == tmux.ControlNotificationSessionRenamed {
      fmt.Println("heard the rename")
      return nil
    }
  }
  // docs:end
}

Session.OpenNotifications streams what tmux does as it happens rather than polling — tmux pushes each change instead of a poll guessing how often to ask. tmuxtest.WaitForText (see Testing with libtmux) is the equivalent built specifically for tests.

Rust’s wait_for_text looks before it sleeps, joins wrapped lines so a needle spanning a wrap still matches, and returns PaneWait::Dead rather than hanging forever if the pane’s process ends first.

Attaching a ControlClient is what makes tmux push %output at all — a client that never attaches only ever hears command replies.

TmuxWait.UntilAsync polls a read against a predicate rather than sleeping a fixed amount.

C++ has no checked snippet that waits on pane text. Server::wait_for(channel, timeout), in include/libtmux/server.hpp, uses tmux’s own wait-for signal instead of scraping output, and its doc comment explains why that is the safer choice when the command you are waiting on can be made to announce itself: “a server that dies under a waiter makes tmux exit zero, which is indistinguishable from being signalled … this reports that as a failure instead.”

waitForOutput takes patterns for both success and failure, so a process that fails fast is discovered immediately rather than by timing out.

Where this comes fromLink to section

Go, Rust, and Swift each reuse a file already shown in full on Attach and send keys: rather than dump the same file a second time, this page quotes just the relevant lines by hand, with a comment naming the source, and points back at the full listing there.