Capture a pane to read its visible screen or scrollback. After Sending keys, wait for the expected output or a completion signal before reading the result.
Visible pane vs. scrollbackLink to section
tmux capture-pane distinguishes the currently visible screen from the
scrollback history above it, and every port exposes that split rather than
flattening it:
Java’s pane.capture() and .NET’s pane.CaptureAsync() return the visible
pane as a list of lines; neither’s own README shows a scrollback option as
of this page, so check the port’s reference before assuming one exists.
Sources: TypeScript’s is examples/capture/capture.ts, run by bun test examples/capture. Go’s is examples/quickstart/main.go. Rust’s is
crates/libtmux/README.md’s capability table, doctested via #![doc = include_str!("../README.md")]. C++‘s is README.md’s “Read a pane”
section, quoted verbatim from examples/05-readme.cpp’s capture region
and checked by tools/docs/check_readme.py. Swift’s is README.md,
“Change what is there.”
Wait for the expected textLink to section
An immediate capture can race the shell, as Sending keys explains. Wait for the expected text with a timeout so your program stops promptly when the output arrives and reports a failure if it never does:
Python’s pytest plugin supplies isolated test servers; see Testing with
libtmux. For Python and C++ signal-based waiting, use
the wait-for APIs below. This page does not include a wait-for-text helper for
those ports.
Sources: Go’s is tmux/tmuxtest/screen.go, quoted in README.md’s “Testing
your own code” section. Rust’s is crates/libtmux/README.md, doctested.
TypeScript’s is examples/agent/agent.ts, run by the integration suite and
quoted in packages/libtmux/README.md (<!-- runs: examples/agent/agent.ts -->). Java’s is examples/.../WatchPaneOutput.java. .NET’s is README.md,
one of the csharp run blocks ReadmeExampleTests runs. Swift’s is
Examples/Sources/ExampleCode/Waiting.swift, matched against
<doc:Waiting> and the README by Scripts/check_examples.py; the same
file’s server.capture(pane, since: mark), called in a loop with the cursor
it returns, is the “watch as it prints” shape for output too large or too
open-ended to wait on a single pattern.
When the pane can announce itself: wait-for, not scrapingLink to section
If you control the command, have it signal completion with tmux wait-for -S done. Wait on the same channel to avoid matching screen text:
The Python example is a doctest in src/libtmux/server.py. C++‘s
Server::wait_for(channel, timeout), declared in include/libtmux/server.hpp,
also detects a server that dies during the wait. Swift’s server.wait(for:)
example waits for a build to signal completion:
Source: Examples/Sources/ExampleCode/Waiting.swift. Rust’s
crates/libtmux/README.md documents the same pattern under “tmux keeps a
signal nobody is waiting on, so the job finishing first does not lose the
race, and nothing polls,” runnable as examples/orchestrate.rs.
Where to go nextLink to section
- Filtering and querying, in practice: once you’re reading more than one pane, finding the right one to capture.
- Testing with libtmux: the isolated-server fixtures that make waiting on real tmux practical inside a test suite.
- Capture pane output: the full sourced code for the patterns above.