Codecov Report

❌ Patch coverage is 89.33333% with 104 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.09%. Comparing base (d8b7127) to head (7ee8374).
⚠️ Report is 4 commits behind head on master.

@@            Coverage Diff             @@
##           master     #684      +/-   ##
==========================================
+ Coverage   52.44%   60.09%   +7.65%     
==========================================
  Files          26       47      +21     
  Lines        3726     4701     +975     
  Branches      747      821      +74     
==========================================
+ Hits         1954     2825     +871     
- Misses       1468     1535      +67     
- Partials      304      341      +37     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Feedback from driving tmux through an MCP layer (libtmux-mcp)

Some real-world motivation for this exploration, from the perspective of an automation/agent layer that drives tmux through an MCP server built on libtmux.

The pain today

Building a layout programmatically — say a right-hand column of four evenly stacked panes — currently takes four ordered tool calls, each splitting the pane id returned by the previous one:

split %1 right  -> %2
split %2 below  -> %3
split %3 below  -> %4
split %4 below  -> %5

Each call is a separate libtmux dispatch → separate tmux process → separate command queue. The new pane id doesn't exist until the call returns, so I can't express the whole layout up front; I'm forced into a dependency chain of round-trips, one per pane.

On the CLI the same thing is a single invocation:

tmux split-window -h \; split-window \; split-window \; split-window

That works because every command in one invocation shares tmux's current target state, and split-window advances it to the newly created pane — unless -d is set:

https://github.com/tmux/tmux/blob/3f651d9/cmd-split-window.c#L176-L177

libtmux's split(attach=False) always passes -d, so that cursor never advances, and because each MCP call is its own process the shared queue state is gone at the boundary anyway. Net effect: there's no way to fold a layout build into one atomic tmux invocation today.

The pattern that would be the unlock

Exactly what this PR is prototyping: an ordered sequence of typed commands that compiles to one native \; invocation, with targets that can be deferred and resolved rather than known up front. The substrate is already the right shape — CommandSequence.argv() semicolon-joins the calls and .run() dispatches through a single runner.cmd(...):

https://github.com/tmux-python/libtmux/blob/228ff0b/tests/chainable_commands_experiment/shared.py

Collapsing N round-trips into one invocation is the headline win; recovering tmux's own cursor semantics inside that single queue is the bonus.

Deferred plan

deferred_plan_api is the variant that maps most directly onto what an automation layer needs:

https://github.com/tmux-python/libtmux/blob/228ff0b/tests/chainable_commands_experiment/deferred_plan_api.py

• Typed, target-safe targets (PaneTarget / WindowTarget / SessionTarget) so select-layout can only bind a window and send-keys only a pane — mistakes that would otherwise surface at runtime.
• A lazy query over a snapshot, mapped to commands, compiled once and dispatched once (CommandPlan.run → to_sequence(snapshot) → sequence.run(runner)), with NoCommandsResolved degrading to a no-op.

The big deal: I never thread freshly created ids through arguments. I query live state, map each row to commands, and let the plan resolve and dispatch atomically.

The companion auto_batch_api is worth keeping alongside it — it encodes the detection rule for "what may fold into a chain": a call is chain-safe iff its output isn't consumed mid-chain. DeferredCommandResult raises if you read stdout before dispatch, and show_option is the deliberate counterexample of a call that can't batch because it needs output immediately:

https://github.com/tmux-python/libtmux/blob/228ff0b/tests/chainable_commands_experiment/auto_batch_api.py

Combined with the CommandSpec.chainable flag, that's both the static and the dynamic half of deciding what a batch compiler may merge.

What an async deferred plan adds on top

The async facade is more than a coat of paint for anything hosting this inside a server:

https://github.com/tmux-python/libtmux/blob/228ff0b/tests/chainable_commands_experiment/async_deferred_plan_api.py

• The runner protocol becomes async def cmd(...) and snapshot acquisition becomes awaitable (AsyncSnapshotProvider), matching how an async server and async libtmux dispatch actually run — dispatching a layout no longer blocks the event loop or other in-flight calls.
• Snapshot reads can overlap with other awaits, and independent plans (e.g. several windows) can be resolved and dispatched concurrently.
• It stays a thin facade over the sync engine (it reuses to_sequence), so the single-native-sequence guarantee is preserved — one plan still compiles to exactly one tmux ... \; ... dispatch.

So: the sync deferred plan removes the round-trip and id-threading problem; the async deferred plan makes that same guarantee safe to use under a concurrent server without giving up the one-invocation-per-plan property.

One prerequisite worth calling out for the split-chain case specifically: an attach opt-out (so a sequence can intentionally let the current cursor walk into freshly created panes) interacts with the -d behavior linked above. The snapshot/deferred-target approach sidesteps needing that for target resolution, which is part of why it's the more attractive path.

Review: the pattern this lab should converge on

I went through the whole tests/chainable_commands_experiment/ lab — every prototype and its tests — against five axes: developer experience, typing, testability, maintainability, and expressiveness. This writes up the tradeoffs of all of them and names the single pattern they point at, building on the libtmux-mcp motivation already in this thread.

The pattern this points at

An immutable argv command-sequence IR, with a typed, target-safe query → command-plan layer as the authoring surface, served through an async facade that preserves "one plan = one native \; dispatch", and governed by a chainability contract that decides what may fold into a single invocation. Mutations fold into one dispatch; reads that must return output stay individual typed calls.

Concretely that is deferred_plan_api sitting on the shared.py IR, with async_deferred_plan as the hosted-server front door and the chainability rule from auto_batch_api deciding what merges. Everything else is either a piece of that pattern, a different ergonomic wrapper over the same IR, or a more ambitious shape that costs more than native tmux sequencing can repay.

Why this is the unlock (the MCP case in this thread)

The motivating pain is real: building a four-pane column today is four ordered round-trips, because each new pane id doesn't exist until the previous call returns — every call is its own tmux process with its own command queue. On the CLI it's one invocation (split-window -h \; split-window \; …) because the commands share tmux's current target state. Two facts make the one-invocation path the prize:

• The substrate is already the right shape: CommandSequence.argv() semicolon-joins calls and .run() dispatches through a single runner.cmd(...) (shared.py). Collapsing N round-trips into one invocation is the headline win.
• There are two ways to target panes inside one invocation, and they cover different cases:
  • Operate on objects that already exist (resize every active pane, send-keys to matching panes): deferred snapshot targets — deferred_plan_api solves this completely and target-safely.
  • Create and target within the same invocation (the layout build): the new ids don't exist at authoring time, so you lean on tmux advancing its current cursor command-to-command. That requires not forcing -d — and today Pane.split(attach=False) always appends -d, so the cursor never advances. An attach/-d opt-out is the prerequisite for that specific case; the snapshot approach sidesteps it for everything else.

The idea doing the heavy lifting: typed targets

The differentiator across the whole lab is the typed-target row in deferred_plan_api. Rows carry pane_id: PaneTarget, window_id: WindowTarget, session_id: SessionTarget, and expose .cmd / .window namespaces already bound to the right target — so select-layout can only bind a window and send-keys only a pane, and the mapper never touches a raw string. Every other prototype takes target: str | int | None positionally, which is easy to get wrong. Paired with pure-snapshot compilation (to_sequence(snapshot) is a pure function), the entire query → argv path is testable in memory with a fake snapshot — no tmux, sub-millisecond — with live tmux only at .run(). That is the strongest testability story here.

What the async facade actually buys

async_deferred_plan is more than a coat of paint for anything hosting this in a server: the runner becomes async def cmd(...) and snapshot acquisition becomes awaitable, so dispatching a layout no longer blocks the event loop, snapshot reads overlap with other awaits, and independent plans (e.g. several windows) resolve and dispatch concurrently. Crucially it stays a thin facade over the sync engine — it reuses the sync to_sequence — so the one-native-sequence-per-plan guarantee is preserved. If the host is async (an MCP server is), this isn't optional polish; it's the front door.

The chainability contract (what auto_batch_api is really for)

The valuable thing in auto_batch_api isn't the transparent-proxy ergonomics — it's the rule it encodes: a call may fold into a chain iff its output isn't consumed mid-chain. The dynamic half is demonstrated by DeferredCommandResult, whose .stdout/.stderr/.returncode raise DeferredOutputUnavailable until the chain runs, with show_option as the deliberate counterexample — a command that can't batch because it needs output immediately.

Worth stating precisely: the static half — a CommandSpec.chainable flag — exists in the IR but is not yet wired to that dynamic predicate; auto_batch_api doesn't reference it. Connecting the two (a static chainable declaration plus the runtime "output-not-consumed" guard) is exactly the contract a batch compiler needs to decide what may merge. That's the part to carry forward, not the proxy UX.

The gap that sets the scope line

The hard limit is structured per-command output (capture-pane, show-option). One semicolon invocation returns one merged result — tmux gives no per-command demultiplexing. The lab confronts this honestly but doesn't solve it (CapturePane constructs but run() is flat; deferred_plan rejects data-returning mappers; auto_batch raises). The clean resolution is to keep the plan/sequence layer mutation-only: the ORM already does single-command read-back well (split-window -P -F '#{pane_id}'), and per-command demux inside a sequence would need fragile sentinel injection and drift toward transaction semantics this work explicitly treats as a non-goal.

Tradeoffs of every prototype

Breakdown by group

The core (detailed above). shared.py + deferred_plan_api + async_deferred_plan + the chainability predicate from auto_batch_api are the pattern; see the four sections above. Everything below is measured against them.

Hand-authoring façades over the IR — command_object_api, context_api, builder_api, decorator_api. All four let you author a fixed sequence without a query; they differ only in ergonomics. command_object_api gives the most precise types (concrete frozen dataclasses, assert_type) and the best test story (pure argv plus live stop-on-error), but the most boilerplate — each command is a dataclass and a forwarding namespace method, and its output is still just a CommandCall, so it's largely redundant with composing the IR directly (CommandCall(...) >> CommandCall(...)). context_api and builder_api are smaller and keep construction cleanly separate from dispatch, but still cost one typed method per command — cheap to start, not cheap to scale. decorator_api has the nicest call site (reads like a normal typed function) but attaches metadata at runtime where static tools can't see it. Net: adopt at most one, as a thin façade over command values, and only once callers want hand-authoring beyond raw >>.

Metadata placement — descriptor_api. This is the issue's nominal Django-@admin.display framing and the only demo that hangs metadata on a still-callable attribute. The cost is the per-command @overload __get__ machinery, which is heavy and doctest-expensive. The lighter alternative already in the lab is the CommandSpec ClassVar on command values, which carries the same metadata with no extra machinery. Reach for descriptors only if attribute-level discovery (e.g. downstream tool codegen) is proven necessary.

Read / query surfaces — queryset_api, async_query_api, selection_api, expression_api, document_query_api, statement_api. A cluster exploring the read side: a familiar ORM filter/order_by/limit, awaitable reads, traversal (server().sessions().windows().panes().fields(...)), Q-object predicates, and metadata/statement filters. They're useful for typed reads, but they don't sequence mutations and their typing varies (selection/statement lean stringly-typed). They complement the snapshot the plan layer already reads rather than competing with the command core — and the plan's own map() over a snapshot covers the common "read into typed rows" need.

Over-ambitious shapes (research only) — lazy_plan_api, dag_api, runnable_api, orchestration_api, ast_api, generated_client_api. These impose graph (dag; lazy_plan.optimize() is a no-op), concurrency/workflow (runnable's stream/pipeline, orchestration's Prefect-style task.map), source-introspection (ast via inspect.getsource — can't handle lambdas or REPL-defined functions), or codegen (generated_client, contingent on a generator that isn't here) vocabularies. A single ordered semicolon dispatch has no dependencies, concurrency, or streaming to model, so these oversell what tmux provides. Keep them as probes; don't ship.

A maintainability lever worth surfacing

Every module in the lab currently carries zero doctests and passes CI only by living under tests/. The test config enables --doctest-docutils-modules and includes src/libtmux in testpaths, so the moment any shape moves into src/, the project's "every public method has a working doctest, no skips" rule applies to every method. Doctest burden scales with public surface area — the strongest practical argument for leading with the bounded-surface query-plan layer and resisting a wide command catalog (and its duplicated namespace methods) before callers need it.

Net

Carry forward shared.py as the IR, deferred_plan_api as the authoring surface, async_deferred_plan as the async front door, and the chainability predicate from auto_batch_api (wired to a static CommandSpec.chainable flag) as the merge-safety contract — plus an attach/-d opt-out for the create-within-one-invocation layout case. Keep AST, DAG, orchestration, streaming, lazy-plan, and the standalone command-object/descriptor surfaces as research until a caller proves each one earns its surface.