tmux-python / tmux-python/libtmux-mcp
Nudge agents toward batching: a post-single-call system-reminder
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 13
- Forks
- 0
- Avg merge
- 13h 52m
- Merged PRs (30d)
- 4
Description
The ask
After an agent makes a lone tmux tool call that could have travelled in a batch, deliver a
short system-reminder-style nudge encouraging it to batch next turn — the way
claude-in-chrome nudges toward browser_batch after a single MCP call:
You used a single tool call this turn. Prefer
tmux_batchto execute multiple actions in
one call — it is significantly faster. Batch your next sequence of sends, waits, captures,
and layout changes together.
This is the runtime, in-loop counterpart to the tmux_batch front door (#101): the tool
gives the agent something to reach for; the reminder teaches it to actually reach.
Why
Every MCP tool call is a round-trip and an agent turn. The batch surface exists — and under
engine-ops (#87) it is genuinely powerful, with two levels of folding/pipelining — but
agents rarely find or use it. The generic wrappers appear in no server instructions
segment, and nothing at runtime points an agent back toward batching once it has fallen into
one-call-at-a-time behavior. Every reactive string the server emits today is error-path only
(bad-argument suggestions, tier denials, per-op batch rejections); none fires on a clean
single call. Static docs do not change in-loop habits; a per-call reminder does.
Desired behavior (acceptance)
- After a qualifying single (non-batch) tmux call, the agent receives brief guidance —
delivered as guidance, not an error — that names the concrete batch tool to use. - Tier-aware target. Name the engine-ops plan tools (
execute_plan/build_workspace)
whenLIBTMUX_MCP_ENGINE_OPS=1; otherwisesend_keys_batch/call_*_tools_batch(or
tmux_batchonce #101 lands). - Never blocks, delays, or alters the tool's own result. Batching stays opt-in — the
reminder never forces a batch or rejects a single call. - Restrained enough not to fire on every call forever (behavioral intent — thresholds and
suppression are for the implementer).
Non-goals
- Not prescribing middleware / hook design, per-turn call-count tracking, or thresholds.
- Not forcing batches, changing tool results, or altering safety tiers.
- Not a new batch tool — that is #101; this issue only adds the reactive nudge toward it.
Prior art / relationship
- No existing ticket does this. #96 / #93 (PR #99) surface invocation context /
self-location through static instruction segments frozen at import — not a post-call
adaptive reminder. #18 merely quotes Claude Code's own client-side MCP-disconnect message. - The nudge points agents at the batch surface tracked by #49 / #78 (
send_keys_batch),
#79 (call_*_tools_batch), #81 (run_tmux_operations), #87 (engine-ops plan tools), and
thetmux_batchfront door (#101).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the runtime path that handles completed non-batch tmux tool calls and inspect how guidance or other reactive messages are delivered. Check the LIBTMUX_MCP_ENGINE_OPS setting and the named batch tools, then implement a non-blocking, restrained reminder whose acceptance behavior preserves the original result and leaves batching optional.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100