# LibTmux::Server#search_panes

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Ruby
- **Kind:** method
- **Source:** https://github.com/libtmux/libtmux-ruby/blob/da7b6191b9439e3c84fa1c9eeaa9168263ee7af4/gems/libtmux/lib/libtmux/server.rb#L343
- **Page:** https://libtmux.org/en/ruby/v0.1.1/reference/libtmux-server-search_panes/

```
def search_panes: (
  ?where: untyped,
  ?pushdown: ::Symbol,
  **untyped
) -> ::LibTmux::Selection[::LibTmux::PaneSnapshot]
```

Behavior: Source query execution.

Behavior contract: Source query execution.

## Examples

Filter a captured snapshot, distinguish a missing session, and acquire a fresh pane selection. one raises unless exactly one record matches; one_or_nil returns nil only for zero matches. Use Ruby 3.3 or newer with Bundler, and tmux 3.3a or newer, on Unix with `/bin/cat` and `/bin/sh` available. In an empty directory, save this `Gemfile`:

```ruby
source "https://rubygems.org"

gem "libtmux", "0.1.1"
```

Save this complete program as `query.rb`. Its `Server.start` block owns a private tmux server and stops it on exit, including after an error.

[Source example](https://github.com/libtmux/libtmux-ruby/blob/da7b6191b9439e3c84fa1c9eeaa9168263ee7af4/examples/api/query.rb).

```ruby
# frozen_string_literal: true

begin
  # docs:begin main
  require "libtmux"

  LibTmux::Server.start do |server|
    work = server.new_session(name: "work", command: ["/bin/cat"], receipt: true)
    server.new_session(name: "logs", command: ["/bin/cat"])
    snapshot = server.snapshot
    session = snapshot.sessions.where(name: "work").one
    puts "matching session: #{session.name}"
    missing = snapshot.sessions.one_or_nil(name: "missing")
    puts "missing session: #{missing.nil?}"
    panes = server.search_panes(where: {id: work.pane.id})
    puts "matching pane: #{panes.one.id}"
  end
  # docs:end main
rescue StandardError => error
  warn "#{error.class}: #{error.message}"
  exit 1
end
```

Install the gem and run the program. An operation or cleanup error makes it exit unsuccessfully:

```console
$ bundle install && \
  bundle exec ruby query.rb
```

Expected output:

```text
matching session: work
missing session: true
matching pane: %0
```

## Parameters

- `where` (`untyped`)
- `pushdown` (`::Symbol`)
- `kwargs` (`untyped`)

## tmux command

The tmux commands behind `search_panes`.

- [`list-panes`](/en/tmux/latest/manual/list-panes/) `-a` server scope, [`cmd_list_panes_server`](/en/tmux/latest/reference/c-function-cmd-list-panes-c-cmd_list_panes_server/) (source: `gems/libtmux/lib/libtmux/capture.rb:93`)

## tmux C API

The C declarations in tmux that implement these commands.

- [`cmd_list_panes_entry`](/en/tmux/latest/reference/c-variable-cmd_list_panes_entry/) (attribute)
- [`cmd_list_panes_server`](/en/tmux/latest/reference/c-function-cmd-list-panes-c-cmd_list_panes_server/) (function)

## In other ports

Filter every pane with a tmux expression

| Language | Equivalent |
| --- | --- |
| Python | [`libtmux.Server.search_panes`](/en/py/latest/reference/libtmux-server-search_panes/) (method) |
| Lua | [`libtmux.Server:query_panes`](/en/lua/latest/reference/libtmux-server-query_panes/) (method) |
| TypeScript | no equivalent on `Server` |
| Rust | no equivalent on `Server` |
| Go | [`tmux.Server.SearchPanes`](/en/go/latest/reference/tmux-server-searchpanes/) (method) |
| Java | no equivalent on `Server` |
| C# | [`LibTmux.Server.SearchPanesAsync`](/en/csharp/latest/reference/libtmux-server-searchpanesasync/) (method) |
| C++ | no equivalent on `Server` |
| Swift | no equivalent on `Server` |

No equivalent is recorded in PowerShell, Julia, Elixir, Kotlin, Scala or F#.