CHANGES

# Changelog

## libtmux-mcp 0.1.x (unreleased)

<!-- KEEP THIS PLACEHOLDER - DO NOT REMOVE OR MODIFY THIS LINE -->
_Notes on upcoming releases will be added here_
<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->

## libtmux-mcp 0.1.0a22 (2026-09-06)

libtmux-mcp 0.1.0a22 runs on FastMCP 4, which brings MCP Python SDK v2 with
it. The `tmux://` resources keep accepting the socket paths and session names
tmux allows but a generic screen reads as filesystem paths, so the resource and
tool views continue to agree on what exists. The templates answer argument
completion for the hosts that ask for it, a failed read reports a different
error code, and a wait tool no longer takes down its own call when the
execution carries no session.

### Dependencies

**Minimum `fastmcp>=4.0.2`** (was `>=3.4.2,<4.0.0`)

libtmux-mcp tracks the FastMCP 4 line. FastMCP 4 builds on MCP Python SDK
v2, which brings `mcp>=2.0.0`, `mcp-types` and pydantic 2.12 with it, and
replaces httpx with httpx2 across FastMCP's HTTP stack. No tool, resource or
prompt changes shape, and one server serves both the session-based and the
sessionless `2026-07-28` protocol eras, negotiated per connection.

**FastMCP releases are adopted without waiting out the cooldown**

The dependency cooldown held every FastMCP release back, so a refreshed lock
resolved to a patch behind the one being tested against. `fastmcp` and its
`fastmcp-slim` companion are exempt from it.

### What's new

**`tmux://` templates answer argument completion**

The templates take live tmux identifiers, and MCP publishes a template's URI
but never its parameter domain, so a reader had no way to discover a valid
session name or pane id from the listing. A completion handler offers them
from the live server, filtered by what has been typed and scoped by an
already-supplied `socket_name`. A server that is gone yields no suggestions
rather than an error.

Whether suggestions appear depends on the client. The MCP Inspector's browser
UI and VS Code send `completion/complete`; measured against five agent CLIs,
none do.

### Fixes

**`tmux://` reads keep accepting tmux names that look like paths**

FastMCP 4 screens templated resource parameters before a handler runs. Its
absolute-path check does not fit tmux identifiers: it rejects the socket paths
`list_servers` reports, and reads any `<letter>:<rest>` session name — which
tmux accepts — as a Windows drive-relative path. Both stay readable, so
`tmux://` and the equivalent tools continue to agree on which sessions and
servers exist.

Traversal and null-byte screening remain on, and are set per template rather
than server-wide. `socket_name` reaches `tmux -L`, which appends it to the
socket directory without normalising, so `../..` really does place the socket
elsewhere; exempting the parameter outright would drop that guard along with
the absolute-path check.

**A `tmux://` read that fails now says so as `-32603`**

FastMCP's `ErrorHandlingMiddleware` matches not-found exceptions by exact
class, so only an unknown resource URI still maps to `-32002`. A missing
session raises `ResourceError`, and a rejected path raises
`ResourceSecurityError` — a `NotFoundError` subclass, and so not an exact
match — and both reach the client as `-32603` "Internal error". The message is
unchanged; only clients matching on the numeric code are affected.

**A wait tool survives a context that carries no session**

`Context.session` raises rather than degrading when there is no request
context, so `ctx.warning` and `ctx.report_progress` took the whole tool call
down in any execution that lacks one. The wait helpers check before
delivering: the call returns its normal result, without notifications, instead
of failing. Notification delivery on an ordinary request is unchanged.

### Documentation

**The completion topic describes the handlers the server registers**

The page said libtmux-mcp registered no completion handlers and offered
workarounds for the gap. It describes what the `tmux://` templates complete,
and states the caveat where it now belongs: whether suggestions appear depends
on the client. The retired claims are pinned as forbidden text, so the page
cannot drift back to underclaiming a shipped feature.

**The toolset migration notes reach the migration page**

The 0.1.0a21 notes mapping the retired tiers onto `inspect`, `manage`,
`execute` and `teardown` lived in a second file the documentation did not
include, so {ref}`migration` ended at 0.1.0a19. They are now a dated section
of `MIGRATION`, and they state that `LIBTMUX_SAFETY` raises while the server
module loads — every value, the former default `mutating` included — and that
the former default is reached by removing the variable and setting nothing.

### Development

**A Sphinx warning fails the documentation build**

The docs workflow passes `-W --keep-going`, so a warning stops the build that
publishes the site instead of scrolling past in a green run.

**Path-like session-name tests skip on tmux below 3.7**

tmux before 3.7 rewrites `:` and `.` in a session name to `_`, turning `a:1`
into `a_1`, and exits 0 with no stderr — so a caller cannot tell from the
result. The resource tests that need such a name check what tmux stored and
skip when it differs, naming the rewrite. They ran only against a newer tmux
before, and reported the resulting absent session as a failed read on every
supported tmux in CI.

**The test suite runs without FastMCP's camelCase compatibility shims**

FastMCP 4 answers MCP SDK v1 attribute spellings such as `tool.inputSchema`
through warn-once shims it plans to remove. Neither gate catches a test that
depends on one: the type checker sees `Any`, and the warning fires once per
attribute for the whole run. The suite sets `FASTMCP_MCP_CAMELCASE_COMPAT=false`,
so a surviving camelCase read raises `AttributeError` and fails the test that
made it.

**The compatibility reference is bound to the manifest**

The dependency table restated floors by hand and had drifted: it named libtmux
0.55 against a manifest requiring 0.62, and omitted `regex` entirely. A test
compares the table against `[project].dependencies` as version ranges, so the
next floor that moves without its documentation fails the suite.

## libtmux-mcp 0.1.0a21 (2026-08-30)

libtmux-mcp 0.1.0a21 replaces cumulative safety tiers with independently
selectable `inspect`, `manage`, `execute`, and `teardown` toolsets, including an
opt-in teardown surface. Caller-supplied names, paths, formats, and regular
expressions now stay within declared bounds, while conservative annotations and
the new {ref}`trust` page state how tmux hooks, client consent, and OS isolation
divide responsibility. Write-capable batch wrappers are removed so client
policy sees each operation, and `mcp_swap.py` adds opencode and pi while
migrating local configurations away from `LIBTMUX_SAFETY`.

### Breaking changes

**Toolsets replace safety tiers**

Tools now belong to the unordered `inspect`, `manage`, `execute`, and
`teardown` sets. `LIBTMUX_TOOLSETS` selects any combination; the default is
`inspect,manage,execute`, while `teardown` remains opt-in.
`LIBTMUX_TOOLS` enables individual tools and `LIBTMUX_EXCLUDE_TOOLS` takes
precedence over every inclusion. Unknown toolset or tool names fail startup.

`LIBTMUX_SAFETY` now fails startup rather than silently widening the exposed
surface.

**Before**

```console
$ LIBTMUX_SAFETY=readonly libtmux-mcp
```

**After**

```console
$ LIBTMUX_TOOLSETS=inspect libtmux-mcp
```

The former default maps to `inspect,manage,execute`; the former full surface
adds `teardown`. See {ref}`migration` and {ref}`trust`. (#128)

**Write-capable batch wrappers are removed**

`call_readonly_tools_batch` becomes
{tooliconl}`call-read-tools-batch` and accepts `inspect` tools only.
`call_mutating_tools_batch` and `call_destructive_tools_batch` are removed;
call write-capable tools directly so client policy sees each tool's own name.
(#128)

**{tooliconl}`display-message` accepts literals and variables**

`format_string` now accepts literal text and plain `#{variable}` references,
including hyphenated built-in and user-option names. Modifiers, conditionals,
padding, and jobs are rejected because they can re-expand values supplied by a
pane. Run `tmux display-message -p` through {tooliconl}`run-command` when raw
format syntax is required. (#128)

**Spawn tools require an existing working directory**

A supplied `start_directory` must resolve to an existing directory. Calls that
previously appeared to succeed while tmux silently placed the pane in `$HOME`
now fail and identify the invalid path. (#128)

### Fixes

**Names and paths remain literal**

Caller-supplied session names, window names, pane titles, option names, and
working directories are escaped before tmux format expansion. Values containing
`#(...)`, `#{...}`, or `#[...]` now arrive intact instead of running a job or
being rewritten. (#128)

**{tooliconl}`search-panes` stops pathological matching**

Regex matching now has one two-second budget across the call, excluding tmux
pane-capture time. Pattern length is capped separately, and a pattern that
exhausts the matching budget returns a correctable error instead of blocking
the server. (#128)

**Tool annotations account for programmable tmux targets**

Every tool that requests a tmux operation now advertises conservative
whole-call annotations. Command aliases and `after-*` hooks can replace or
extend an operation on an existing tmux server, so the project-owned toolsets
carry the direct-operation distinction that standard MCP hints cannot promise.
(#128)

**Failed tool calls run once**

The server no longer retries failed inspection calls automatically. A tmux
alias or hook may already have acted before reporting an error, so the client or
operator decides whether repeating the request is appropriate. (#128)

**Shutdown leaves tmux buffers alone**

Server shutdown clears only the Python process cache. It no longer deletes
buffers by a shared name prefix that cannot prove which MCP server instance
created them. (#128)

**Prompt adapters remain callable through `inspect`**

With `LIBTMUX_MCP_PROMPTS_AS_TOOLS=1`, `list_prompts` and `get_prompt` remain
visible and callable when the `inspect` toolset is enabled. They render
server-local text without contacting tmux and retain their narrower
annotations. (#128)

### Documentation

#### opencode joins the install picker

The install widget gains an opencode panel. `opencode mcp add tmux -- <command>`
is non-interactive once a name and a `--` command are both given, so it is a CLI
panel rather than a paste-this-JSON one — which also sidesteps opencode's
unusual entry shape.

**The trust page separates tool filtering from confinement**

The trust page replaces the safety topic and explains what the MCP call gate,
tmux aliases and hooks, shared sockets, status jobs, and OS isolation each
control. The old safety URL and renamed batch-tool URL redirect to their current
pages, and tool catalogs expose each toolset with a copyable label and colored
badge. (#128)

### Development

**`mcp_swap.py` covers opencode and pi**

`use-local`, `status`, `revert`, `doctor` and `detect` now reach two more agent
CLIs.

opencode is the first config the script edits that is not plain JSON or TOML.
Its `$XDG_CONFIG_HOME/opencode/opencode.jsonc` is JSONC, its server map hangs
off a top-level `mcp` key rather than `mcpServers`, and one entry packs argv
into a single `command` array with its environment table spelled
`environment`. Getting the shape wrong is not a soft failure there: a scalar
`command` is a decode error that stops opencode starting, and an `env` key is
dropped without a word. Comments survive a swap, including one written directly
above the `command` it explains.

pi ships no MCP client — its README says so outright, and the released build
contains no MCP code. `~/.pi/agent/mcp.json` is read by the third-party
`pi-mcp-adapter` extension, so a swap written there takes effect only once that
package is installed. `detect` says so rather than reporting a swap that cannot
do anything.

**JSONC is edited rather than reserialized**

The JSON writer rebuilds the whole document, which for a commented file would
mean deleting every comment in it. JSONC values now come from stdlib `json`
after comments and trailing commas are blanked in place, and writes are applied
as text splices, so every byte outside a replaced value is untouched. The
obvious dependency was measured and rejected: `json-five` round-trips comments,
but raises on the valid JSON string `"C:\\x"` and silently decodes a literal
`\u0041` to `"A"`.

**Per-CLI behavior is declared, not branched**

`CLIInfo` gained `container` (the key path to the server map) and `dialect` (the
entry shape) alongside `fmt`. The four `cli in (...)` membership tuples that
`get_server`, `set_server`, `delete_server` and `_all_server_specs` each carried
are gone. Two of them ended in a bare `else` that fell through to the TOML key,
so a CLI registered but forgotten in one tuple reported "no entry" instead of
failing; the other two raised `AssertionError`, which the caller did not catch.
A non-mapping at a container key now raises a `RuntimeError` naming the path for
every CLI, not just Claude. `scripts/README.md`'s extension guide described
three branch sites when there were four; it now describes the fields instead.

**`mcp_swap.py` migrates retired safety settings**

`use-local` removes a stored `LIBTMUX_SAFETY` only when
`LIBTMUX_TOOLSETS` supplies its replacement. Otherwise it stops with migration
instructions, and `--env LIBTMUX_SAFETY=...` is rejected so a restricted
configuration cannot widen silently. (#128)

## libtmux-mcp 0.1.0a20 (2026-08-09)

libtmux-mcp 0.1.0a20 changes no tool behavior. ruff's curated default rule
set is enabled behind a `ruff>=0.16.0` floor, and the CI workflow actions move
to their current majors. In the documentation, the dataclass identifying an
MCP caller describes each field instead of reaching the API reference as
"Alias for field number 0".

### Documentation

#### Caller identity fields are described (#105)

The dataclass identifying an MCP caller now says what each field holds. They
previously reached the rendered API reference as "Alias for field number 0"
or as a bare name carrying only its type.

### Development

#### CI actions updated to current majors

Workflow actions moved to their current major releases: `actions/checkout` v7,
`actions/cache` v6, `astral-sh/setup-uv` v9.0.0, `codecov/codecov-action` v7,
and `dorny/paths-filter` v4. Workflow behavior is unchanged, though setup-uv no
longer prunes the uv cache, so the first run after this repopulates it.

**Minimum `ruff>=0.16.0`** (was unpinned)

The `dev` and `lint` dependency groups now require ruff 0.16.0 or newer, so
contributors and CI see the same diagnostics rather than whichever ruff each
machine resolved. From this release on, `ruff format` also formats Python code
blocks inside Markdown, so `uv run ruff format .` reaches the README and the
`docs/` tree. Neither the lint nor the format change rewrites anything here.
(#113)

**ruff's curated default rule set is now enabled**

`[tool.ruff.lint]` layers this project's linters on with `extend-select` instead
of `select`. An explicit `select` replaces ruff's default set rather than adding
to it, so the project had been silently opting out of every rule it did not name
itself; enabled rules go from 351 to 565. The findings that surfaced are fixed —
`re.DOTALL` spelled out in place of `re.S`, `str.removesuffix` and `min()` in
`scripts/mcp_swap.py`, the server instruction blob built as an f-string, and the
wrapped marker fixtures parenthesized so a dropped comma can no longer pass for
a deliberate join. `scripts/mcp_swap.py` is now executable and its shebang points
at `uv run --script`, so running it directly honours the PEP 723 metadata instead
of failing to import `tomlkit` under a bare `python3`. Two rules are scoped
ignores with their reasons recorded in
`pyproject.toml`: `exec` in `docs/conf.py`, which is how Sphinx reads version
metadata, and the `except Exception` boundaries in the error middleware, the
batch runners, the best-effort tmux probes, and `mcp_swap`'s config rollback.
(#113)

## libtmux-mcp 0.1.0a19 (2026-07-25)

libtmux-mcp 0.1.0a19 makes {tooliconl}`wait-for-text` see the output it was asked to watch for, and puts a ceiling under every wait. The tool anchored one row below the cursor's position at entry, which on a quiescent pane is exactly where the next line lands, so the case it exists for — output you did not author, a daemon printing a single `ready` line — could not match at all. Waits are now bounded by a server ceiling, cancellable without orphaning their tmux child, and report an `outcome` that distinguishes a command that never ran from output that did not match from a pager owning the pane. The wait API changes shape in the process: `pattern` becomes `patterns`, `stop` markers end a wait early, and `wait_for_content_change` is removed in favour of `wait_for_text(patterns=null)`.

### Breaking changes

**{tooliconl}`wait-for-text` takes a list of patterns, and no wait outruns the
server**

The single `pattern` string becomes `patterns`, a list — or `null` to wait for
any new output at all. A new `stop` list carries failure markers, and a hit ends
the wait immediately. Every wait tool is now capped by
`LIBTMUX_MCP_WAIT_MAX_SECONDS` (30 s by default): an over-large `timeout` is
clamped rather than rejected, and the result reports the value actually
enforced. The cap is not scoped to {tooliconl}`wait-for-text` —
{tooliconl}`run-command` and {tooliconl}`wait-for-channel` previously honoured a
caller `timeout` verbatim and now enforce the same limit, so a call that used to
block for an hour returns at the ceiling. (#100)

```python
# Before
wait_for_text(pane_id="%1", pattern="ready", timeout=600)

# After — patterns is a list, stop bails out early, timeout is clamped
wait_for_text(pane_id="%1", patterns=["ready"], stop=["error"], timeout=600)
```

**`wait_for_content_change` and `ContentChangeResult` are removed**

Use `wait_for_text(patterns=null)`, which waits for any new output and
additionally excludes pre-existing scrollback and stale paint from the change
predicate. (#100)

**{class}`~libtmux_mcp.models.WaitForTextResult` reports an outcome, not loose
flags**

One `outcome` field states how the wait ended — it matched, it saw any new
output, it hit a stop marker, the pane was on the alternate screen, or it timed
out. `risk_band_warned` is gone; the history-limit trim signal is delivered only
as an MCP warning notification. Clients that cannot surface notifications should
compose `tmux wait-for -S` into the command and use
{tooliconl}`wait-for-channel`, which does not read the pane at all. (#100)

**Self-bounded tools can no longer be nested in a batch wrapper**

{tooliconl}`run-command`, {tooliconl}`wait-for-text` and
{tooliconl}`wait-for-channel` each block under the wait ceiling, and the batch
wrappers run their operations serially with no aggregate deadline — batching one
multiplied that ceiling by the operation count. All three wrappers now reject
all three tools per operation. (#100)

### What's new

**A wait explains itself**

Alongside `outcome`, the result names which entry fired, whether anything new
was written, whether the match was stale text already on screen when the wait
began, and a bounded tail of the rows it was watching. Every field is observed
rather than inferred, so a timeout tells you which of "the command never ran",
"output arrived and did not match", and "a pager owned the pane" actually
happened. Progress notifications carry the remaining budget rather than a
constant string. (#100)

**Pagers and editors are reported instead of matched on paint**

Inside `less`, an editor, or any other full-screen program, a pane capture
returns rows the program has already painted, which a naive wait reported as new
output. The wait now says the pane is on the alternate screen so the agent reads
it instead of trusting a false match, and resumes ordinary matching when the
program exits. (#100)

### Fixes

**{tooliconl}`wait-for-text` sees the row the cursor was on**

The wait anchored one row BELOW the cursor's position at entry, and on a
quiescent pane that is exactly where the next line of output lands — the cursor
sits at the end of the prompt. So the case the tool is reserved for, output you
did not author such as a daemon printing a single `ready` line, could not match
at all: the wait burned its whole budget and then reported that the pane had
been silent. Measured before the fix, a bare `READY_MARK` missed at 5.02 s with
the marker provably on screen, while the same marker written with a leading
newline matched in 1.017 s.

The anchor now lands on the entry row and that row's pre-existing content is
suppressed by value rather than by index, so carriage-return spinners and
single-line status updates become matchable too. A stale match still does not
end the wait — it keeps waiting for a fresh occurrence, so re-running a command
whose output looks identical continues to work. (#100)

**Waits no longer hang, leak, or claim a result they did not get**

Four failures with one theme — a wait that reports something other than what
happened. An unresponsive tmux could leave the process, and Ctrl-C, hanging
indefinitely, because waits reached tmux through worker threads that cannot be
cancelled. Cancelling a call returned immediately but left the tmux child
running for the rest of its timeout — measured at 13 s of orphan for a
15-second wait cancelled at 2 s. Retrying a wait restarted its budget, so a
bounded wait could still run unbounded. And {tooliconl}`wait-for-channel`
reported success when the tmux server shut down without ever signalling,
because `tmux wait-for` exits 0 for both — it now re-probes the server before
claiming a signal. (#100)

**{tooliconl}`pipe-pane` writes to the path you asked for**

`output_path` reached tmux's format expander before `/bin/sh`, and only the
shell layer was escaped. Both of tmux's expansions were live, so `#Session.log`
lost its `#S` to the session name and `100%done.log` became `10025one.log` via
strftime — the log landed on a different file while the tool reported back the
path requested. The path is now escaped for both.

**Failures name the thing that actually failed**

A missing dependency was reported as "libtmux-mcp requires fastmcp" whichever
module was missing — close to the one cause it cannot be, since fastmcp is a
hard dependency. A pane, window, or session that could not be resolved raised
"Could not find object" without naming the target the caller passed. And the
unknown-argument hint stopped naming the connected client after an SDK field
rename. All three now say which thing failed.

**The interrupt recipe no longer reports success as failure**

The `interrupt_gracefully` prompt told agents to treat a `^C` echo as proof that
a program had trapped SIGINT and kept running. The terminal echoes `^C` whenever
SIGINT is delivered, dead process or not, so the marker fired on the success
path — and the recipe's next step is SIGQUIT and then killing the pane. It now
brackets the interrupt with {tooliconl}`get-pane-info` and trusts
`pane_current_command`, the one signal that discriminates.

### Documentation

**New topic: Waiting**

Which wait to reach for, how {tooliconl}`wait-for-text` decides something is
new, how to read each result field, and what a wrong search pattern actually
costs — one bounded call whose `tail` usually already contains the text you
should have searched for. It also records the designs that were measured and
rejected, so they are not re-litigated from intuition: MCP background tasks, an
event-driven `pipe-pane`, a deferred resume handle, and removing the tool.

**The wait ceiling's rationale was wrong**

The ceiling was justified as stopping a bad wait from stalling the shared MCP
connection. There is no such stall: the wait tools await throughout and FastMCP
serves the connection concurrently — measured, a tool awaiting 6 s served 58
interleaved calls at a 3.4 ms median, against exactly one at 6014 ms for a
control that blocked the event loop. The ceiling is unchanged and still right;
it bounds the agent's turn, which MCP gives it no way to abandon mid-call.
`LIBTMUX_MCP_WAIT_MAX_SECONDS` is now documented in {doc}`/configuration`.

### Development

**`mcp_swap.py` keeps the pre-swap config on a repeat swap**

Swapping a CLI layer that was already swapped and not yet reverted used to take
a fresh backup of the swapped config, so `revert` restored an already-swapped
config and the only pristine copy was lost. A re-swap now keeps the first
backup, backup files are never overwritten, and `doctor` no longer calls
untracked backups "safe to delete".

**`mcp_swap.py doctor` and `use-local --env`**

A read-only `doctor` subcommand reports the effective MCP-swap environment —
which server name each CLI points at, un-reverted swaps, orphaned or missing
backups, and auth-overriding environment variables. `use-local --env` injects
environment entries such as an isolated `LIBTMUX_SOCKET` at swap time instead of
requiring a hand-edit post-edit.

## libtmux-mcp 0.1.0a18 (2026-07-12)

libtmux-mcp 0.1.0a18 raises the libtmux floor to 0.62.0 and tightens how the server handles lookups that cannot succeed. A readonly call carrying a stale or ambiguous id now fails on the first attempt instead of paying a second tmux round-trip and a backoff window to fail identically, and an ambiguous target — a window shared between sessions, matched by name or index — now comes back with a recovery hint that says to target it by id instead of an unexplained error. The floor bump is what makes both fixes possible: libtmux 0.62.0 folds its query errors into the {exc}`libtmux.exc.LibTmuxException` hierarchy the server keys on.

### Dependencies

**Minimum `libtmux>=0.62.0`** (was `>=0.61.0`). Picks up libtmux 0.62.0, which
re-parents {exc}`libtmux.exc.MultipleObjectsReturned` and
{exc}`libtmux.exc.ObjectDoesNotExist` under {exc}`libtmux.exc.LibTmuxException`.
The retry and error-mapping fixes below rely on that hierarchy. (#98)

### Fixes

**A stale id fails once instead of twice**

Readonly tools retried on any {exc}`libtmux.exc.LibTmuxException`, the right
trigger for the transient socket errors libtmux wraps but wrong for the rest of
that family — a pane that does not exist will not exist on the second look, and
an ambiguous match does not become unambiguous during a backoff window. A lookup
that a retry cannot change now fails on the first attempt, without the redundant
tmux round-trip and its backoff delay. (#98)

**An ambiguous target says how to disambiguate it**

A window shared between sessions — through a grouped session or `link-window` —
is listed once per session that holds it, so a name or index can match more than
one row and the lookup raises {exc}`libtmux.exc.MultipleObjectsReturned`. That
reached the agent with no recovery hint. It now says to target the object by id
instead. (#98)

## libtmux-mcp 0.1.0a17 (2026-07-11)

libtmux-mcp 0.1.0a17 makes best-effort shell-history suppression the default for {tooliconl}`run-command` — calls that omit `suppress_history` now inherit the server default, and setting {envvar}`LIBTMUX_SUPPRESS_HISTORY` to `0` restores the previous behavior. Spawned shells gain the same hygiene: {tooliconl}`create-session`, {tooliconl}`create-window`, {tooliconl}`split-window`, and {tooliconl}`respawn-pane` accept `suppress_persistent_history=true` for best-effort no-disk history controls. {tooliconl}`create-window` and {tooliconl}`split-window` also accept per-process `environment` mappings, and the MCP install picker now covers Grok CLI and Antigravity.

### Breaking changes

**History suppression now defaults on for run commands**

MCP clients now see the effective server default for `suppress_history` on {tooliconl}`run-command`, and calls that omit the argument inherit it. The default requests best-effort history suppression. To run multiline input while suppression is enabled, pass `suppress_history=false`; to retain the previous omitted-call behavior, set {envvar}`LIBTMUX_SUPPRESS_HISTORY` to `0` and restart the server. Direct Python calls remain unchanged. See {ref}`configuration` for details. (#91)

### What's new

**History controls for spawned shells**

{tooliconl}`create-session`, {tooliconl}`create-window`, {tooliconl}`split-window`, and {tooliconl}`respawn-pane` now let callers opt into best-effort no-disk shell-history controls with `suppress_persistent_history=true`. Session controls reach the initial and future panes, while the other tools limit the setting to the process launched by that call.

History suppression reduces accidental persistence, but it is not secret transport: shells can override the controls, and terminal output and other observation surfaces remain visible. See {ref}`history-hygiene` for shell behavior and {ref}`trust` for the remaining boundaries. (#91)

**Per-process environments for windows and panes**

{tooliconl}`create-window` and {tooliconl}`split-window` now accept per-process `environment` mappings or JSON object strings, so callers can configure new windows and panes without changing the tmux session environment. {tooliconl}`respawn-pane` now accepts the same JSON object form for its existing environment input. Values can still surface in host process inspection and child environments; use credential references, not literal credentials. See {ref}`trust` for details. (#91)

### Documentation

**Grok CLI and Antigravity in the MCP install picker**

The MCP client picker now covers Grok CLI and Antigravity (Google's agy) alongside Claude, Codex, Gemini, and Cursor. Grok registers through its own `grok mcp add` verb (`~/.grok/config.toml`); Antigravity has no such verb, so its `mcpServers` snippet is pasted into `~/.gemini/config/mcp_config.json`. (#89)

## libtmux-mcp 0.1.0a16 (2026-07-04)

libtmux-mcp 0.1.0a16 raises the libtmux floor to 0.61.0, picking up libtmux 0.61.0's hardening of the tmux 3.7 patch line. The server runs cleanly against tmux 3.7a and 3.7b, and tmux 3.2a-3.6 keep working unchanged. The bump requires no server code or test changes.

### Dependencies

**Minimum `libtmux>=0.61.0`** (was `>=0.60.0`). Picks up libtmux 0.61.0's hardening of the tmux 3.7 patch line, so the server runs cleanly against tmux 3.7a and 3.7b. Every 3.7-only surface stays version-gated, so tmux 3.2a-3.6 keep working unchanged, and the bump requires no server code or test changes. (#86)

## libtmux-mcp 0.1.0a15 (2026-06-28)

libtmux-mcp 0.1.0a15 raises the libtmux floor to 0.60.0, which completes tmux 3.7 feature parity at the library layer the server wraps — floating panes, typed tmux 3.7 options, new pane format variables, and new command flags. Every 3.7-only surface is version-gated, so tmux 3.2a-3.6 keep working unchanged. The dev and test dependency groups also move to pytest 9.1.0.

### Dependencies

**Minimum `libtmux>=0.60.0`** (was `>=0.58.0`). Picks up libtmux 0.59.0's initial tmux 3.7 support and 0.60.0's completion of tmux 3.7 feature parity — floating panes, typed tmux 3.7 server, session, window, and pane options, new pane format variables, and new command flags. Every 3.7-only surface is version-gated, so tmux 3.2a-3.6 keep working unchanged, and the bump requires no server code or test changes. (#85)

### Development

**Minimum `pytest>=9.1.0`**

The dev and test dependency groups now require pytest 9.1.0 or newer. (#83)

## libtmux-mcp 0.1.0a14 (2026-06-14)

libtmux-mcp 0.1.0a14 adds tier-aware tool batching. {tooliconl}`call-readonly-tools-batch`, {tooliconl}`call-mutating-tools-batch`, and {tooliconl}`call-destructive-tools-batch` run an ordered list of existing MCP tools in a single call and return a per-operation result for each, preserving every nested tool's own structured output. Each wrapper caps the safety tier of the calls it will make — regardless of the server's `LIBTMUX_SAFETY` tier — and `on_error` selects stop-at-first-failure or continue-and-report handling. Aggregate results stay within the server's response limit.

### What's new

**Tier-aware tool batching**

{tooliconl}`call-readonly-tools-batch`, {tooliconl}`call-mutating-tools-batch`, and {tooliconl}`call-destructive-tools-batch` run an ordered list of existing MCP tools in a single call and return a per-operation result for each, preserving every nested tool's own structured output. Each wrapper caps the safety tier of the calls it will make — the readonly wrapper refuses mutating or destructive operations, and the mutating wrapper refuses destructive ones — regardless of the server's `LIBTMUX_SAFETY` tier. Nested calls keep their normal schema validation, middleware, and safety checks, and `on_error` selects stop-at-first-failure or continue-and-report handling. Large aggregate results stay within the server's response limit — oversized nested payloads are dropped (with the truncation flagged in the result), and very large operation lists are rejected rather than allowed to overflow it. (#79)

## libtmux-mcp 0.1.0a13 (2026-06-13)

libtmux-mcp 0.1.0a13 adds {tooliconl}`send-keys-batch` for sending an ordered batch of raw key/text operations to tmux panes in a single call, with per-operation results, stop-or-continue error handling, and an optional timeout that bounds both the batch and each send. Argument-validation failures also stop echoing the rejected input into the server's logs and tool error results, so a secret-bearing argument can no longer surface there.

### What's new

**Ordered raw input with {tooliconl}`send-keys-batch`**

{tooliconl}`send-keys-batch` sends several raw-input operations in order and returns per-operation success or failure metadata. Choose stop-at-first-failure or continue-and-report handling, and set an optional timeout to bound a long batch and each underlying send. It is intentionally scoped to keystrokes and text input for TUIs or persistent shells; authored command completion stays with {tooliconl}`run-command`, and repeated observation stays with {tooliconl}`capture-since`. (#49, #61)

### Fixes

**Argument-validation failures no longer echo rejected input**

When a tool call fails argument-schema validation, the error result and the server's invalid-argument log record now omit the rejected input values, so a secret-bearing argument can no longer surface in logs or error text. (#78)

## libtmux-mcp 0.1.0a12 (2026-06-13)

libtmux-mcp 0.1.0a12 hardens the MCP server's read-only and safety surface and adds a one-call `run_command` tool. Read-only tools can no longer trigger tmux format-job shell evaluation, an invalid safety tier fails closed instead of exposing write tools, and large successful results keep their structured payload. Panes and windows also gain liveness and active-pane metadata, and the package ships a `py.typed` marker. The fastmcp floor rises to 3.4.2 to pick up its explicit `starlette>=1.0.1` floor (CVE-2026-48710).

### Dependencies

**Minimum `fastmcp>=3.4.2`** (was `>=3.4.0`). Picks up fastmcp 3.4.1's explicit `starlette>=1.0.1` floor, so installs can no longer resolve to a Starlette version affected by CVE-2026-48710 — previously this was constrained only transitively through `mcp`. (#77)

### What's new

**One-call command completion with {tooliconl}`run-command`**

{tooliconl}`run-command` runs a shell command in a pane, waits for it to finish, and returns the exit status, timeout state, and tail-preserved output in a single call — no manual {tooliconl}`send-keys` + {tooliconl}`wait-for-channel` + {tooliconl}`capture-pane` sequence. The command runs in a subshell so its state changes don't leak into later calls, and `suppress_history` keeps secret-bearing commands out of shell history where the shell ignores space-prefixed input. (#73)

**Richer, typed pane and window metadata**

{tooliconl}`snapshot-pane` now reports `pane_pid`, `pane_dead`, and `alternate_on` for liveness and alternate-screen decisions, and window results carry `active_pane_id` for reliable follow-up targeting. The package also ships a `py.typed` marker so downstream type checkers see its inline annotations. (#75)

### Fixes

**Read-only tools no longer evaluate tmux `#()` format jobs**

{tooliconl}`search-panes` and {tooliconl}`display-message` were advertised as read-only, but tmux `#(...)` formats schedule shell jobs during expansion. Both now reject or route around `#()` so those parameters can no longer spawn a shell. (#68, #69)

**Invalid `LIBTMUX_SAFETY` fails closed**

An unrecognized `LIBTMUX_SAFETY` value now falls back to `readonly` instead of `mutating`, so a typo in the safety tier can no longer expose write tools the operator meant to hide. (#71)

**Large structured results keep their structured payload**

The global response backstop was truncating big successful results into text-only responses before tool-level caps ran, dropping the structured metadata schema-bearing tools depend on. It now matches FastMCP's 1 MB default, leaving per-tool line caps to handle terminal truncation. (#70)

**{tooliconl}`clear-pane` clears scrollback reliably**

{tooliconl}`clear-pane` now uses libtmux's single-call reset path; the previous two-call sequence could leave scrollback intact. Its annotations also disclose that it is destructive and non-idempotent. (#74)

**Stdio transport pinned at startup**

The server runs with an explicit stdio transport so an inherited FastMCP transport environment can't change its startup surface and break stdio clients, and `--help` / `--version` resolve locally without starting the server. (#72)

## libtmux-mcp 0.1.0a11 (2026-06-06)

libtmux-mcp 0.1.0a11 redesigns how tool failures reach agents. Error messages now arrive exactly as raised — no more `Internal error:` mangling — with structured detail and recovery hints that tell agents what to do next, from stale pane ids to stray arguments leaked by client schedulers. Expected, agent-correctable failures log at WARNING so ERROR records always mean an operator should look. The fastmcp floor rises to 3.4.0 to build on its error-result and log-level support.

### Dependencies

**Minimum `fastmcp>=3.4.0`** (was `>=3.2.4`). Enables the error-result and log-level improvements below; the bump alone also restores resource titles on the `tmux://` hierarchy and brings MCP-compliant telemetry span attributes.

### What's new

**Tool errors arrive clean, with structured detail and recovery hints**

Failed tool calls now return their message exactly as raised — previously every failure was prefixed with `Internal error:`. Error results carry a structured `_meta` payload (`error_type`, `expected`, `suggestion`), and not-found errors point at {tooliconl}`list-sessions` / {tooliconl}`list-windows` / {tooliconl}`list-panes` to resolve stale or guessed ids. (#64)

**Unknown tool arguments get a do-this-next hint**

When a call includes arguments a tool doesn't accept, the error result now names exactly which argument(s) to remove or fix. When the stray key is `wait_for_previous` — a scheduling flag Gemini CLI can leak into batched tool calls — the hint says so and names the connected client, so agents recover in one read instead of re-deriving the problem from a validation traceback. (#64)

**Expected tool failures log at WARNING, not ERROR**

Agent-correctable failures — unknown ids, invalid arguments, safety-tier denials, transient tmux errors — now log at WARNING in the server's log stream. A missing tmux binary and unexpected exceptions stay at ERROR, so ERROR records are always worth attention. (#64)

## libtmux-mcp 0.1.0a10 (2026-05-24)

### What's new

**Incremental pane observation with {tooliconl}`capture-since`**

{tooliconl}`capture-since` gives agents a cursor-based way to observe a pane without re-reading the same terminal output on every turn. The first call returns the current visible screen and an opaque cursor; later calls return only rows written or rewritten after that cursor while tmux still retains the needed history. If scrollback was cleared or trimmed, the result sets `lines_missed=True`, returns a conservative current visible capture, and issues a fresh cursor. Malformed cursors, cross-pane replay, pane death, and pane respawn fail clearly instead of silently switching processes. (#60)

## libtmux-mcp 0.1.0a9 (2026-05-24)

libtmux-mcp 0.1.0a9 tightens pane polling correctness for agents waiting on terminal output. Search and wait tools now handle wrapped content, history-limit risk reporting, and pane lifecycle changes with clearer results instead of silent false positives.

### Fixes

**{tooliconl}`search-panes` matches wrap-spanning slow-path text**

{tooliconl}`search-panes` now joins tmux-wrapped visual rows when it uses the captured-content slow path, so long build, test, or log lines can match across the pane width. Plain fast-path searches still use tmux's native visual-row search; pass `regex=True` or a content range when exact text may span a wrap boundary. (#55)

**{tooliconl}`wait-for-text` reports trim-risk warnings in results**

{tooliconl}`wait-for-text` now returns `risk_band_warned=True` when polling enters tmux's history-limit trim-risk band. Clients that do not surface MCP warning notifications can still detect that matching was best-effort and switch to {tooliconl}`wait-for-channel` for deterministic command completion. (#54)

**{tooliconl}`wait-for-content-change` fails on pane lifecycle changes**

{tooliconl}`wait-for-content-change` now raises a tool error when the watched pane dies or is respawned during the wait. Those lifecycle changes invalidate the entry content baseline, so callers no longer receive a misleading `changed=True` result for a different pane process. (#53)

## libtmux-mcp 0.1.0a8 (2026-05-23)

libtmux-mcp 0.1.0a8 bumps libtmux to 0.58.0, fixing session and window listing on systems whose locale is not UTF-8.

### Dependencies

**Minimum `libtmux>=0.58.0`** (was `>=0.56.0`). Picks up the 0.57.x command-coverage and client-awareness releases and the 0.58.0 non-UTF-8 locale fix — session and window listing could silently return empty results when the system locale was not UTF-8.

### What's new

**Installer picker now covers config scope and file locations**

The MCP install widget on the front page, {doc}`/quickstart`, and {ref}`clients` now lets you pick a config scope per LLM client alongside the install method — *local* / *user* / *project* for Claude Code, *user* / *project* for Codex and Gemini, *project* / *global* for Cursor. JSON-only clients (Cursor, Claude Desktop) also show the destination config-file path next to the snippet so the paste target is never a guess. Your scope choice is remembered per-client, so switching between clients restores each one's last selection.

**Installer picker can apply or bypass dependency cooldowns**

A new *Configure cooldowns* control on the install widget lets you tack a cooldown onto the snippet without leaving the page. Pick a delay in days (uv's `--exclude-newer`, pip's `--uploaded-prior-to`, pipx's `--pip-args`) to wait out community vetting before pulling a fresh release, or pick *Bypass any global cooldown* to skip a `~/.config/uv/uv.toml` cutoff and grab the latest libtmux-mcp anyway. The setting persists across pages, and the embedded *What are cooldowns?* expander links to the [Datadog Security Labs writeup](https://securitylabs.datadoghq.com/articles/dependency-cooldowns/) and [cooldowns.dev](https://cooldowns.dev/) if you want the supply-chain context. (#31)

### Documentation

**MCP install widget ships working cooldown snippets**

The install widget on the front page, {doc}`/quickstart`, and {ref}`clients` now emits a runnable snippet in every method × cooldown cell. uvx days panels apply the cooldown to transitive dependencies while exempting libtmux-mcp itself, so a fresh release stays installable. pipx and pip days panels fall back to the bare install command — neither tool exposes a per-package cooldown override today — and their cooldown note redirects readers to the uvx tab when they want true cooldown enforcement. (#58)

## libtmux-mcp 0.1.0a7 (2026-05-16)

### Breaking changes

**{tooliconl}`wait-for-text` waits for new output, not stale scrollback**

{tooliconl}`wait-for-text` now matches lines written *after* the call begins. The previous behaviour returned `found=True` on the first poll whenever the pattern already lived in the pane, so agents synchronising on command output got the wrong result. For the synchronous "is the pattern in the pane right now?" case, call {tooliconl}`search-panes` instead.

Baseline-loss events surface as `ToolError`: pane respawn, pane death, `clear-history`, and any other event that drops history below the entry baseline. Pane resize that pulls lines back from history into the visible region is exempted — the anchor stays valid.

Trim during heavy output near `history-limit` can't be reliably detected from polling alone. When polling approaches that limit, the tool emits a `notifications/message` warning so MCP clients can decide whether to keep waiting, retry, or switch to {tooliconl}`wait-for-channel`. For deterministic command completion, compose `tmux wait-for -S <channel>` into the shell command and call {tooliconl}`wait-for-channel`. (#45)

**{tooliconl}`wait-for-text` drops `content_start` / `content_end`**

The new baseline anchor follows the pane's grid position automatically, so the manual capture-range parameters have no remaining purpose. Drop them from call sites. (#45)

```python
# Before
wait_for_text(pattern="OK", content_start=-100)

# After
wait_for_text(pattern="OK")
```

**Wait result models drop `timed_out`**

{class}`~libtmux_mcp.models.WaitForTextResult` and {class}`~libtmux_mcp.models.ContentChangeResult` drop the `timed_out` field. It was mechanically the boolean negation of the primary result (`not found` / `not changed`) and carried no information beyond that. Callers should switch to `not result.found` / `not result.changed`. (#47)

```python
# Before
result = wait_for_text(pattern="OK")
if result.timed_out:
    ...

# After
result = wait_for_text(pattern="OK")
if not result.found:
    ...
```

### Dependencies

**Minimum `libtmux>=0.56.0`** (was `>=0.55.1`). Picks up libtmux 0.56's typed wrappers for the tmux commands the server invokes — the MCP now uses libtmux's public API instead of raw command-line escapes for pane lifecycle, scrollback, and session navigation. (#46)

### Fixes

**{tooliconl}`wait-for-channel` recipe no longer exits the parent shell**

The `run_and_wait` prompt template previously appended `exit $__mcp_status` to its shell payload to preserve the command's exit status. In an interactive shell that exits the shell itself, destroying single-pane sessions. The recipe now signals completion via `tmux wait-for -S` without exiting, and the equivalent example in {doc}`/tools/pane/wait-for-channel` is similarly fixed. Exit-status preservation in interactive shells is documented as out-of-scope; agents that need it should inspect the captured output for command-specific success markers. (#47)

**{tooliconl}`wait-for-text` matches patterns across visually-wrapped lines**

Long patterns like `"Build failed: module not found"` that tmux wraps at the pane's column width are now matched against the joined logical line. Previously the wrap split the pattern across two captured rows and neither row matched. The joined line is returned in `matched_lines` and can exceed the pane width. (#45)

**{tooliconl}`wait-for-text` rejects misused `pattern` / `interval` / `timeout`**

Empty `pattern`, `interval` below 10 ms, and non-positive `timeout` each raise `ToolError` at entry. Previously they silently matched every line, spun the tmux server in a tight loop, or completed a surprise single probe. (#45)

### Documentation

**Wait family is re-framed around {tooliconl}`wait-for-channel` as the deterministic primitive**

The {tooliconl}`send-keys` docstring, server system instructions, {tooliconl}`wait-for-text` docstring, and the user-facing quickstart, gotchas, prompting, troubleshooting, recipes, and send-keys topics now point agents at {tooliconl}`wait-for-channel` with composed `tmux wait-for -S` for command completion. {tooliconl}`wait-for-text` and {tooliconl}`wait-for-content-change` are reframed as the fallbacks for output the agent does not author. The `run_and_wait` recipe shows the canonical safe-completion pattern. (#45)

## libtmux-mcp 0.1.0a6 (2026-05-09)

libtmux-mcp 0.1.0a6 is the activation and registration cleanup release. It makes the server much easier for MCP clients to discover from ordinary "pane", "window", and "session" prompts, standardizes new setup docs around the `tmux` registration slug, and adds migration guidance for existing `libtmux` registrations. Existing installs keep working; the release changes defaults and documentation so new installs line up with the tool prefix users actually see.

### What's new

**Bare tmux prompts now find the server**

Agents no longer need the word "tmux" in every prompt before this server becomes relevant. The server instructions now name the positive cases users naturally write, such as "split this pane", "current window", and "this session", while steering clients away from unrelated browser tabs, editor splits, tiling-window-manager panes, and notebook cells. The discovery anchors most likely to answer those prompts - {tooliconl}`list-panes`, {tooliconl}`list-windows`, and {tooliconl}`snapshot-pane` - also carry the preload hint used by clients that keep a small always-available schema set. See {ref}`prompting` for the user-facing activation contract. (#37)

**New installs are documented as `tmux`**

The recommended registration slug is now `tmux`, matching the MCP `serverInfo.name` and the `mcp__tmux__*` tool-call prefix surfaced by clients. The package name, import name, and existing user-created `libtmux` registrations are unchanged; only the documented install target moves to the clearer slug. See {ref}`migration` for the walkthrough. (#40)

### Documentation

Hierarchy-noun tool titles now include a `tmux` qualifier in catalog-style displays, so entries like "List tmux Sessions" stay understandable when a client shows tools from several MCP servers together. Tmux-specific verbs such as {tooliconl}`send-keys`, {tooliconl}`pipe-pane`, {tooliconl}`snapshot-pane`, {tooliconl}`capture-pane`, and {tooliconl}`paste-text` keep their shorter names because the verb already identifies the tmux operation. (#38)

The {ref}`prompting` guide gains an activation and discovery section with positive triggers, anti-triggers, a client-level `alwaysLoad` example, and a project-instructions fragment for teams that want stronger bias toward tmux when users say "this pane" or "current window". (#39)

## libtmux-mcp 0.1.0a5 (2026-05-06)

libtmux-mcp 0.1.0a5 makes layout-relative pane targeting a first-class workflow. Agents can ask for "the bottom-right pane" directly, reason from typed geometry returned on pane models, and avoid parsing tmux format strings for common layout questions. The release also polishes the documentation site after the theme migration and extends the local MCP swap helper so Claude users can choose project-local or user-global config.

### What's new

**Layout-relative pane targeting via {tooliconl}`find-pane-by-position`**

{tooliconl}`find-pane-by-position` resolves a window corner - top-left, top-right, bottom-left, or bottom-right - to a single {class}`~libtmux_mcp.models.PaneInfo`. This replaces the old workaround of calling {tooliconl}`display-message` with `#{pane_at_bottom}` / `#{pane_at_right}` and parsing raw string output. Single-pane and otherwise ambiguous layouts resolve deterministically, so the common "use the only pane" case does not require an extra branch in the agent workflow. (#34)

**Pane responses now carry geometry**

{class}`~libtmux_mcp.models.PaneInfo`, {class}`~libtmux_mcp.models.PaneContentMatch`, and {class}`~libtmux_mcp.models.PaneSnapshot` now include window-relative coordinates, edge predicates, and the pane TTY. That means an agent can inspect returned data to decide whether a pane is at the left edge, bottom edge, or a specific corner instead of making another tmux query. The older `pane_width` and `pane_height` fields intentionally keep their existing string typing in this alpha; changing those fields is left for a later breaking-change window. (#34)

### Documentation

The docs site moves onto `gp-furo-theme` with `sphinx-vite-builder` handling the theme asset pipeline, so the rendered site follows the same gp-sphinx docs stack used by the rest of the project documentation. (#33)

The install widget and above-the-fold typography no longer shift after first paint. Saved install-widget choices now render in the correct panel immediately, and the fonts and logo used on the landing page are loaded early enough to avoid visible swaps. (#36)

The new corner-finder appears anywhere a reader is likely to look for targeting guidance: the homepage tool chain, tools index, pane tools page, prompting guide, recipes, and example responses. Existing {tooliconl}`display-message` guidance now points layout-relative pane selection at {tooliconl}`find-pane-by-position` instead of teaching agents to expand pane-edge format variables by hand. (#34)

### Development

`scripts/mcp_swap.py` gains `--scope {user,project}` for Claude. Project scope keeps the safe local override used while working in this checkout; user scope intentionally changes the fallback used from other projects. Codex, Cursor, and Gemini have only a global layer, so the flag is accepted there without creating a fake per-project mode. (#35)

## libtmux-mcp 0.1.0a4 (2026-05-02)

libtmux-mcp 0.1.0a4 adds pane recovery and closes the last gap in the core hierarchy's single-object metadata reads. Agents can restart a stuck pane without losing its identity, fetch known sessions or windows directly, and use a bundled development script to point local MCP clients at a checkout. The {tooliconl}`respawn-pane` parameter name settles on `shell` before the stable API, replacing the earlier alpha spelling `shell_command`.

### What's new

**Restart wedged panes in place with {tooliconl}`respawn-pane`**

{tooliconl}`respawn-pane` restarts the process in an existing tmux pane while preserving the `pane_id` and the window layout. That is the right recovery primitive for long-running agent sessions: {tooliconl}`kill-pane` followed by {tooliconl}`split-window` creates a new pane, invalidates stored handles, and can disturb the surrounding layout. The final alpha API uses `shell` for the replacement command to match {tooliconl}`split-window` and libtmux's upstream respawn naming. (#27)

**Direct metadata reads for sessions and windows**

{tooliconl}`get-session-info` and {tooliconl}`get-window-info` complete the server/session/window/pane metadata pattern alongside {tooliconl}`get-server-info` and {tooliconl}`get-pane-info`. Callers that already have an ID or a scoped index no longer need to call a list tool and filter the response. Buffers, hooks, options, and environment values keep their existing show/load/read tools rather than gaining redundant `get_*_info` wrappers. (#27)

### Documentation

{ref}`trust` now documents {tooliconl}`respawn-pane` as a mutating recovery tool with real process side effects, including the `kill=true` default and the visibility tradeoffs of passing command or environment data through tmux. The same update refreshes socket-guard notes for macOS, tightens guidance around {tooliconl}`display-message` and {tooliconl}`pipe-pane`, and adds dedicated tool pages for the new recovery and metadata tools. (#27)

### Development

`scripts/mcp_swap.py` lands as local dogfooding infrastructure for Claude, Codex, Cursor, and Gemini. It detects installed clients, shows the current libtmux-mcp registration, rewrites config to run this checkout through `uv`, and reverts from backups. The `just mcp-use-local` and `just mcp-revert` recipes wrap that flow for branch QA. (#27)

## libtmux-mcp 0.1.0a3 (2026-04-19)

libtmux-mcp 0.1.0a3 is a focused correctness release after the FastMCP alignment work. It fixes caller identity across multiple tmux sockets, moves channel waits off the FastMCP event loop, and raises the libtmux floor to pick up upstream pytest-fixture cleanup. The result is less surprising metadata in multi-server setups and fewer stalled clients during long waits.

### Dependencies

Minimum `libtmux>=0.55.1` (was `>=0.55.0`) for [tmux-python/libtmux#661](https://github.com/tmux-python/libtmux/pull/661), which fixes pytest-plugin socket cleanup under `/tmp/tmux-<uid>/`.

### Fixes

**Pane caller identity is socket-aware**

The `is_caller` pane annotation no longer treats pane `%0` on every tmux server as the current agent pane just because the pane IDs match. The annotation now compares the caller's tmux socket as well, matching the self-protection checks used around destructive tools. This fixes {class}`~libtmux_mcp.models.PaneInfo`, {class}`~libtmux_mcp.models.PaneSnapshot`, and {class}`~libtmux_mcp.models.PaneContentMatch` responses in multi-socket environments. (#22, fixes #19)

**Channel waits no longer stall the MCP server**

{tooliconl}`wait-for-channel` and {tooliconl}`signal-channel` now run their blocking tmux subprocess work outside the event loop. Other tool calls and client keepalives can continue while a wait is pending, matching the async behavior already used by {tooliconl}`wait-for-text` and {tooliconl}`wait-for-content-change`. (#21, fixes #18)

## libtmux-mcp 0.1.0a2 (2026-04-19)

libtmux-mcp 0.1.0a2 is the FastMCP alignment release. It expands the server from a basic tmux wrapper into a broader agent automation surface with discovery, waits, buffers, hooks, pane/window navigation, prompt recipes, middleware, and bounded terminal output. The release includes one response-shape breaking change: {tooliconl}`search-panes` now returns a paginated {class}`~libtmux_mcp.models.SearchPanesResult` instead of a bare list. (#15)

### Breaking changes

**{tooliconl}`search-panes` returns {class}`~libtmux_mcp.models.SearchPanesResult`**

{tooliconl}`search-panes` now returns a result object with matches and pagination metadata instead of the earlier `list[`{class}`~libtmux_mcp.models.PaneContentMatch``]` shape. Existing callers should iterate over `.matches`; callers that search large tmux workspaces can also inspect `truncated`, `truncated_panes`, `total_panes_matched`, `offset`, and `limit`.

```python
# Before
for match in search_panes(...):
    ...

# After
for match in search_panes(...).matches:
    ...
```

**Minimum `fastmcp>=3.2.4`** (was `>=3.1.0`). The newer FastMCP release is required for the former `ReadonlyRetryMiddleware` and per-parameter input-schema descriptions.

### What's new

**Discovery and synchronization tools**

{tooliconl}`list-servers` discovers live tmux servers, including explicitly provided socket paths. The wait family adds content waits ({tooliconl}`wait-for-text`, {tooliconl}`wait-for-content-change`) and tmux channel synchronization ({tooliconl}`wait-for-channel`, {tooliconl}`signal-channel`) so agents can wait for explicit milestones instead of sleeping or repeatedly capturing panes. (#15)

**Buffers, hooks, and richer pane/window control**

Agent-namespaced buffer tools - {tooliconl}`load-buffer`, {tooliconl}`paste-buffer`, {tooliconl}`show-buffer`, and {tooliconl}`delete-buffer` - support staged multi-line input without overloading keystroke simulation. Read-only hook tools ({tooliconl}`show-hook`, {tooliconl}`show-hooks`) expose tmux hook state without adding write-hooks that survive process death. The pane and window surface grows with {tooliconl}`snapshot-pane`, {tooliconl}`pipe-pane`, {tooliconl}`display-message`, {tooliconl}`paste-text`, {tooliconl}`select-pane`, {tooliconl}`swap-pane`, {tooliconl}`select-window`, {tooliconl}`move-window`, {tooliconl}`enter-copy-mode`, and {tooliconl}`exit-copy-mode`. (#15)

**Prompt recipes for common agent workflows**

Four MCP prompts ship for repeatable tmux work: `run_and_wait`, `diagnose_failing_pane`, `build_dev_workspace`, and `interrupt_gracefully`. Clients that only expose tools can opt into tool-shaped prompt access with `LIBTMUX_MCP_PROMPTS_AS_TOOLS=1`. See {ref}`prompts-overview` for the prompt catalog. (#15)

**Middleware for safer long-running automation**

The middleware stack now includes {class}`~libtmux_mcp.middleware.AuditMiddleware` for digest-redacted argument summaries, the former `SafetyMiddleware` for safety-tier visibility, the former `ReadonlyRetryMiddleware` for transient readonly libtmux failures, and {class}`~libtmux_mcp.middleware.TailPreservingResponseLimitingMiddleware` for oversized tool output. Timing and error-handling middleware round out the request path. (#15)

**Tail-preserving bounded output**

{tooliconl}`capture-pane`, {tooliconl}`snapshot-pane`, and {tooliconl}`show-buffer` accept `max_lines` and report whether older lines were trimmed. Truncation keeps the newest terminal output, which is usually the active prompt or most recent command result. Pass `max_lines=None` when a caller intentionally wants the full scrollback or buffer. (#15)

**Better schemas and startup failures**

Tool input schemas now include parameter descriptions extracted from docstrings, so clients can explain arguments without separate docs lookups. Startup also fails with a clear {exc}`RuntimeError` when `tmux` is not available on `PATH`, and {attr}`~libtmux_mcp.models.SessionInfo.active_pane_id` tells callers which pane was created by {tooliconl}`create-session`. (#15)

### Fixes

- {tooliconl}`search-panes` neutralizes tmux format-string injection in the regex fast path.
- The macOS self-kill guard resolves the live tmux socket before falling back to `TMUX_TMPDIR` reconstruction.
- The `build_dev_workspace` prompt uses real tool parameter names, avoids waiting for prompts after screen-grabbing commands, and replaces a Linux-specific log default with `log_command`.
- The former `ReadonlyRetryMiddleware` logs retry warnings under `libtmux_mcp.retry`.

### Documentation

The tools documentation gains category pages for {doc}`/tools/buffer/index`, {doc}`/tools/hook/index`, and {doc}`/tools/index`. The pane tools docs explain the {class}`~libtmux_mcp.models.SearchPanesResult` migration, while {ref}`trust` documents the audit log, socket caveats, {tooliconl}`pipe-pane`, and {tooliconl}`set-environment`. (#15)

## libtmux-mcp 0.1.0a1 (2026-04-13)

libtmux-mcp 0.1.0a1 expands the tmux control surface around the workflows agents actually perform after they find a pane. It adds richer screen snapshots, waits, navigation, pane/window movement, copy-mode entry points, live logging, and bracketed paste support. The docs also adopt the gp-sphinx visual stack so the generated API and tool pages become easier to scan. (#11)

### What's new

**Screen snapshots and waits**

{tooliconl}`snapshot-pane` returns terminal content together with cursor position, copy-mode state, and scroll position in a single read. {tooliconl}`wait-for-content-change` lets an agent wait for any visible update when it does not know the exact text to expect. {class}`~libtmux_mcp.models.PaneSnapshot` and {class}`~libtmux_mcp.models.ContentChangeResult` carry those responses in typed models. (#11)

**Pane and window navigation**

{tooliconl}`select-pane`, {tooliconl}`swap-pane`, {tooliconl}`select-window`, and {tooliconl}`move-window` let agents navigate within tmux and rearrange panes or windows without asking a user to manually focus the target. Directional window selection is scoped to the requested session, and pane selection handles next/previous relative navigation through concrete pane IDs. (#11)

**Terminal I/O helpers**

{tooliconl}`pipe-pane` logs live pane output to a file, {tooliconl}`display-message` exposes tmux format expansion as a read-only metadata escape hatch, {tooliconl}`enter-copy-mode` and {tooliconl}`exit-copy-mode` control copy-mode state, and {tooliconl}`paste-text` uses tmux buffers for multi-line input where raw keystroke simulation is fragile. (#11)

### Documentation

The API docs adopt the gp-sphinx documentation stack: card-style API layouts, safety and scope badges, MyST cross-reference roles, improved CLI-doc section scoping, IBM Plex typography, and FastMCP-aware tool rendering. The docs dependency stack is then refreshed to gp-sphinx `0.0.1a8`. (#10, #14)

## libtmux-mcp 0.1.0a0 (2026-03-22)

libtmux-mcp 0.1.0a0 is the first standalone alpha release, extracted from libtmux's MCP branch. It packages libtmux-backed tmux control as an MCP server with typed tools, hierarchy resources, safety tiers, and socket-aware server selection. The release establishes the base contract that later alphas expand: inspect tmux state, make scoped mutations, and keep destructive operations behind an explicit safety tier.

### What's new

**Standalone MCP server for tmux**

The package exposes tmux sessions, windows, panes, options, and environment operations through MCP tools backed by libtmux. It includes the console entry point, FastMCP server wiring, and the first set of Pydantic response models for tool output.

**Browsable tmux hierarchy**

`tmux://` resources let MCP clients browse the tmux hierarchy from server to sessions, windows, and panes. Tool resolvers accept the normal tmux identifiers so callers can move between resource browsing and concrete tool calls.

**Safety and socket isolation**

The initial server ships with readonly, mutating, and destructive safety tiers, controlled by `LIBTMUX_SAFETY`. Socket selection through `LIBTMUX_SOCKET` and `LIBTMUX_SOCKET_PATH` lets the same process target isolated tmux servers, and `TMUX_PANE` awareness marks the pane that belongs to the calling agent.

**Typed implementation baseline**

Server caching, resolver helpers, standardized error handling, and strict mypy coverage provide the internal foundation for later tool families. All initial tool responses are typed through Pydantic models rather than ad hoc dictionaries.