# Verbs: Search

URL: https://tuios.dev/docs/control-protocol/verbs-search

> Verbs: Search: part of the Control Protocol of TUIOS.

This page is one part of `docs/protocol.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/protocol.md). The [Control Protocol](https://tuios.dev/docs/control-protocol) page lists every part.

## search-panes

Find text in the history and the screen of every pane on this machine.

Params: `query` (required, at most 512 bytes), `regex` (bool, default false:
`query` is literal text), `case` (`smart`, the default, ignores case unless
the query has a capital letter; `sensitive`; `insensitive`), `sessions`
(list, default every session), `max` (default 200, at most 1000), `per_pane`
(default 20, at most 200). A pattern is a Go regular expression, which runs in
linear time. A pattern that matches an empty line is `invalid_params`.

```json
{"verb": "search-panes", "params": {"query": "panic:"}}
```

```json
{"result": {
  "matches": [
    {"session": "work", "window": "7e02...", "name": "build", "workspace": 1,
     "row": 812, "text": "panic: runtime error", "start": 0, "end": 6,
     "age_rows": 30}
  ],
  "panes_searched": 4,
  "truncated": false
}}
```

`row` counts the pane's history rows from the top, then its screen rows: row
`history_rows` is the top row of the screen. `age_rows` is how many rows the
row is above the bottom of the screen. `text` is the row, cut to 400
characters around the match, and `start` and `end` are the first match's
character offsets in `text`. In each pane the newest match comes first, and
the pane with the newest output comes first. Each pane gets 50 ms. `truncated`
is true when `max` or `per_pane` cut the matches, or when a pane took longer.

A restricted connection under scope own may not call it. Over a link it needs
`list`.

## command-history

The commands that shells in panes on this machine ran, newest first. Only a
shell that sends OSC 133 marks reports its commands (see [run](https://tuios.dev/docs/control-protocol/verbs-input-and-output#run)). A pane
keeps its last 200 finished commands. A command that ran again in the same
pane is listed once, at its newest run.

Params: `session` and `window` (both optional; without either, every pane),
`limit` (default 200, at most 2000), `query` (only the commands whose text
holds it; smart case, as for `search-panes`).

```json
{"result": {"commands": [
  {"session": "work", "window": "7e02...", "name": "build", "seq": 41,
   "cmdline": "go test ./...", "exit": 1, "at": 1791712193354,
   "duration_ms": 8120, "cwd": "/home/me/src/api", "row": 790}
]}}
```

`seq` is the pane's `command_seq` when the command finished. `cmdline` is cut
to 512 bytes, with likely secrets masked. `exit` is null when the shell sent
no status. `at` is when the command started, in Unix milliseconds. `cwd` is
the folder the shell last reported over OSC 7 when the command started, empty
when it never reported one. `row` is the history row of the command's prompt,
numbered as in `search-panes`, and -1 when the prompt has left the history.

## list-ports

The TCP ports that processes in panes on this machine listen on. A pane's
processes are its program and every process under it. A process that left the
pane's process tree, such as a daemon that detached, is not listed.

Params: `session` (optional; default every session).

```json
{"result": {"supported": true, "ports": [
  {"session": "api-feat", "window": "7e02...", "port": 5173,
   "addr": "127.0.0.1", "pid": 41234, "comm": "node",
   "worktree": "/home/me/.local/share/tuios/worktrees/api/feat"}
]}}
```

On Linux the daemon reads `/proc/net/tcp`, `/proc/net/tcp6` and each
process's open files. On macOS it runs `lsof` for the panes' processes, with a
1 second limit. Elsewhere `supported` is false and `ports` is empty. `addr` is
the address the socket listens on (`0.0.0.0` or `::` for every address).
`worktree` is the session's worktree folder, empty for a session that is not a
worktree session. An answer can be up to 1 second old.

Over a link it needs `list`.

## Which pane started a pane

When a process in a pane calls `new-window`, `split-window`, `start-agent`,
`fan` or `new-worktree`, each pane the call makes records the caller's pane as
`started_by`, `{"session": "work", "window": "7e02..."}`. The daemon finds the
caller's pane the way pane grants do, from the kernel's record of its pid. A
call from outside every pane, or over a link, records nothing. `list-windows`,
`get-window` and `list-agents` show it, and it is saved with the session. A
session rename updates it.
