Pagination¶

Protocol-level list calls¶

tools/list / prompts/list / resources/list / resources/templates/list are registry-list calls. In this server’s current configuration, clients should expect those lists to arrive in one response unless libtmux-mcp later enables FastMCP’s list_page_size setting.

Search result paging¶

One libtmux-mcp tool owns its own paging surface because a single tmux server can carry tens of thousands of pane lines:

• search_panes readonly returns a SearchPanesResult wrapper with matches, truncated, truncated_panes, total_panes_matched, offset, and limit.

• Agents detect truncated=True and re-call with a higher offset to page through the match set.

This is application-level paging (not MCP-cursor pagination) — the agent decides how many matches it needs and when to stop.

Observation cursors¶

capture_since readonly also has a cursor parameter, but it is not a pagination cursor. The first call captures the current visible pane and returns an opaque observation checkpoint. Follow-up calls pass that cursor back to receive only rows written or rewritten after the checkpoint while tmux still retains the needed history.

Because the cursor points into live tmux grid state, it has different failure modes from protocol pagination:

• If the pane output scrolls into retained history, the cursor can still produce an exact delta.

• If tmux clears or trims the needed history, the response sets lines_missed=True and returns a conservative current visible capture with a fresh cursor.

• If the pane dies or is respawned, the cursor is invalid because it would otherwise point at a different process’s terminal state.

This is application-level observation, not a stable collection scan. Use it to reduce repeated pane reads, not to page through search matches.