# search_panes

Source: https://libtmux.org/en/ts/latest/mcp/tools/search_panes/

> Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Find which panes are showing something. Searches pane contents, not their names — use list_panes for metadata. Returns the matching lines with their pane, so you can target one without capturing them all. Literal matching stops at one 256 KiB aggregate UTF-8 byte budget.

tool MCPlatest

MCP concept example

A working example of the core library. It can change without notice.

[What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha)

* **search_panes**( [maxMatchesPerPane](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FmaxMatchesPerPane)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [pattern](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fpattern): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [regex](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [scrollbackLines](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FscrollbackLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), )

  tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/search.ts#L78)][¶](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes)

  Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Find which panes are showing something. Searches pane contents, not their names — use [list_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) for metadata. Returns the matching lines with their pane, so you can target one without capturing them all. Literal matching stops at one 256 KiB aggregate UTF-8 byte budget.

  * MCP request method

    `tools/call` Send `search_panes` as the tool name, with the arguments below.

  ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.parameters)

  * **[`maxMatchesPerPane`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FmaxMatchesPerPane)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    Stop after this many matches in each pane. Defaults to the server limit.

    * maximum

      `9007199254740991`

    * exclusiveMinimum

      `0`

  * **[`pattern`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fpattern)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Non-empty literal text to find.

    * minLength

      `1`

  * **[`regex`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

    Interpret pattern using libtmux’s bounded regular-expression grammar.

  * **[`scrollbackLines`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FscrollbackLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    How far above the visible screen to search. Default 0.

    * minimum

      `0`

    * maximum

      `9007199254740991`

  * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Restrict to one session by id or name.

  ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.result)

  Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")

  * **[`capturesByteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FcapturesByteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`effectiveScrollbackLines`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FeffectiveScrollbackLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`matches`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>)

    * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)"))

      * **[`lineNumber`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FlineNumber)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

        * minimum

          `-9007199254740991`

        * maximum

          `9007199254740991`

      * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

        Stable pane id, e.g. %1.

        * pattern

          `"^%\\d+$"`

      * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>)

        * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)"))

          * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

            The window index in this session.

            * minimum

              `-9007199254740991`

            * maximum

              `9007199254740991`

          * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

            Stable session id, e.g. $1.

            * pattern

              `"^\\$\\d+$"`

          * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

          No other properties are accepted.

      * **[`text`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

      * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

      No other properties are accepted.

  * **[`matchesTruncated`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchesTruncated)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`matchingByteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingByteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`matchingLineClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingLineClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`matchingTimeClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingTimeClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`paneLimitClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpaneLimitClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  * **[`panesFailed`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpanesFailed)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`panesSearched`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpanesSearched)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`scrollbackClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FscrollbackClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

  No other properties are accepted.

  ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.annotations)

  * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint)

    `true`

  * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint)

    `false`

  * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint)

    `true`

  * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint)

    `false`

  ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.schemas)

  Use the complete advertised contract for validation and client integration.

  Input schema

  ```json
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "maxMatchesPerPane": {
        "description": "Stop after this many matches in each pane. Defaults to the server limit.",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "type": "integer"
      },
      "pattern": {
        "description": "Non-empty literal text to find.",
        "minLength": 1,
        "type": "string"
      },
      "regex": {
        "description": "Interpret pattern using libtmux's bounded regular-expression grammar.",
        "type": "boolean"
      },
      "scrollbackLines": {
        "description": "How far above the visible screen to search. Default 0.",
        "maximum": 9007199254740991,
        "minimum": 0,
        "type": "integer"
      },
      "session": {
        "description": "Restrict to one session by id or name.",
        "type": "string"
      }
    },
    "required": [
      "pattern"
    ],
    "type": "object"
  }
  ```

  Output schema

  ```json
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "additionalProperties": false,
    "properties": {
      "capturesByteClamped": {
        "type": "boolean"
      },
      "effectiveScrollbackLines": {
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "matches": {
        "items": {
          "additionalProperties": false,
          "properties": {
            "lineNumber": {
              "maximum": 9007199254740991,
              "minimum": -9007199254740991,
              "type": "integer"
            },
            "paneId": {
              "description": "Stable pane id, e.g. %1.",
              "pattern": "^%\\d+$",
              "type": "string"
            },
            "placements": {
              "items": {
                "additionalProperties": false,
                "properties": {
                  "index": {
                    "description": "The window index in this session.",
                    "maximum": 9007199254740991,
                    "minimum": -9007199254740991,
                    "type": "integer"
                  },
                  "sessionId": {
                    "description": "Stable session id, e.g. $1.",
                    "pattern": "^\\$\\d+$",
                    "type": "string"
                  },
                  "sessionName": {
                    "type": "string"
                  }
                },
                "required": [
                  "index",
                  "sessionId",
                  "sessionName"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "text": {
              "type": "string"
            },
            "windowName": {
              "type": "string"
            }
          },
          "required": [
            "lineNumber",
            "paneId",
            "placements",
            "text",
            "windowName"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "matchesTruncated": {
        "type": "boolean"
      },
      "matchingByteClamped": {
        "type": "boolean"
      },
      "matchingLineClamped": {
        "type": "boolean"
      },
      "matchingTimeClamped": {
        "type": "boolean"
      },
      "paneLimitClamped": {
        "type": "boolean"
      },
      "panesFailed": {
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "panesSearched": {
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "scrollbackClamped": {
        "type": "boolean"
      }
    },
    "required": [
      "capturesByteClamped",
      "effectiveScrollbackLines",
      "matches",
      "matchingByteClamped",
      "matchingLineClamped",
      "matchingTimeClamped",
      "matchesTruncated",
      "paneLimitClamped",
      "panesFailed",
      "panesSearched",
      "scrollbackClamped"
    ],
    "type": "object"
  }
  ```