Skip to main content
Glama

Detect tmux pane

detect_tmux_pane

Detect the actual tmux pane hosting a coding agent UI, even when the calling shell runs in a different pane, by mapping panes to ttys and inspecting real processes.

Instructions

Detect the tmux pane that is actually hosting a coding agent UI, even when the shell calling tools lives in a different pane. The detector scans tmux panes globally, maps each pane to its tty, then inspects real tty processes instead of trusting $TMUX_PANE or tmux focus state alone. Use agent to pick a built-in matcher for Codex, Claude Code, or opencode. Optional cwd, tty, and title_contains narrow the search and make cross-directory multi-agent sessions much more reliable. Returns either a single best pane, or an ambiguity/not-found result with candidates for debugging.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "agent": "<agent>"
    },
    "name": "detect_tmux_pane"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNo
ttyNo
agentYes
title_containsNo
process_patternNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: it explains the detection mechanism (global pane scan, tty mapping, real tty process inspection), warns that `$TMUX_PANE` and focus state are untrusted, and describes the three possible return shapes (best pane, ambiguity, not-found with candidates). It does not state that the operation is read-only or comment on the cost of a global scan.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences in a logical order: purpose, mechanism, parameter guidance, return values. Nothing is redundant, though the parameter sentence is dense and the mechanism sentence is longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex detection tool with no annotations and no output schema, the definition covers mechanism, filters, and result shapes, which is nearly everything an agent needs. The remaining gaps are the undocumented `process_pattern` parameter and the absence of any statement about side effects or scan cost.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does for four of five parameters: `agent` selects a named built-in matcher (Codex/Claude Code/opencode), and `cwd`, `tty`, `title_contains` are described as narrowing filters. `process_pattern` is never mentioned, and no format details (path form, substring vs exact) are given for the filters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('Detect the tmux pane ... hosting a coding agent UI') and adds a scope qualifier about cross-pane shell situations. It is not tautological and would not be confused with the sibling registration/broadcast tools, though it never explicitly contrasts itself with any named alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete conditions for use: when the shell calling tools lives in a different pane, and for 'cross-directory multi-agent sessions' where the default env-var approach is unreliable. It implies the tool's niche well but offers no explicit when-not-to-use guidance or named fallback.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.