Query Language Reference¶

The Patch query language filters Patches using boolean expressions that combine string matching, property filters, and operational shorthands. It is used by the Patches sub-tab in sase tui [query] and by other Patch filters such as sase axe routine run --query.

Host-owned `limit:` cap¶

Every Artifacts pane — Agent, Patches, Stitches, Beads, Files, and every document-provider pane — accepts limit:N / limit:all as a host-owned presentation cap, not a row-matching field. sase's TUI extracts the token before dialect parse and Rust evaluation, matches rows against the remainder, then slices the visible list. Completions offer 40, 100, 200, and all. Startup injects limit:<ace.page_size> (default 100) into each pane's default query when no limit: is present. An explicit token is left alone; deleting it leaves that pane uncapped. limit:all is the unlimited synonym on every pane. The shared parser also treats limit:0 as unlimited (Stitches used that spelling first); completions offer all, not 0. On the Artifacts tab, Ctrl+J raises the cap by ace.page_size and Ctrl+K lowers it, never dropping below one page; unloading an unlimited query introduces limit:<ace.page_size>. The token cannot be negated and may appear only once. Do not add limit as a filterable profile field on Beads, Plans, Files, Patches, or provider dialects; Stitches already treats it as a cap and strips it before row eval.

Normal query surfaces use enabled-project Patch discovery. Disabled projects are omitted from CLI search and day-to-day sase's TUI/axe scans. Views that are specifically about agent history or old artifacts opt into all project lifecycle states explicitly.

This page documents Patch queries. Agent filtering uses the shared Boolean profile dialect instead: the top-level Agents tab uses the live agents-live profile, while Artifacts -> Agent and sase agent search use the catalog profile with archive and artifact-link fields. The grammar is the same across both Agent profiles; the live tab adds operational fields such as machine, pinned, unread, needs, and source and deliberately omits archive-only fields such as state, dismissed, relation, and artifact. See sase's TUI: Agent Pane and sase's TUI: Agent Search.

In the Patches sub-tab, the canonical form of the active query stays visible in a persistent filter row. Press / (or the local f) to edit it. Typing previews each valid query against the already-loaded Patch snapshot, Enter commits it and closes the editor, and Escape abandons the edit and restores the committed query, its result, and your selection. A parse error is reported inline and leaves the visible list on the last valid query. Tab accepts completions for property keys and values, shorthand sigils, predicates, and shorthands — and, while the row is empty, saved-query slots. A leading # saves or deletes a slot without changing the active query; see sase's TUI: Editing Queries.

Agent, Stitches, Beads, Plans, Files, and document-provider panes use the same idle chrome -- the committed query stays visible without opening an editor -- but each pane has its own query profile and previews against that pane's loaded snapshot, not the Patch snapshot. / still focuses the row (as does the pane-local f, except on Artifacts -> Agent); the tokens you can type are documented per pane in sase's TUI Artifacts. The top-level Agents tab hides its filter bar when idle; press / or f to edit the live Agent query there. ,/ searches the selected agent's metadata and does not edit the query.

String Matching¶

Bare words and double-quoted strings perform case-insensitive substring matching against all searchable fields. Use quoted strings when the value contains spaces, punctuation, or other characters that are not valid in a bare word:

foobar           bare word, matches "FooBar", "FOOBAR", etc.
"foo bar"        quoted string, allows spaces and special characters

Prefix a quoted string with c to force case-sensitive matching:

c"FooBar"        matches only "FooBar", not "foobar" or "FOOBAR"

Inside quoted strings, the following escape sequences are recognized: \\ (literal backslash), \" (literal quote), \n (newline), \r (carriage return), and \t (tab).

Searchable Fields¶

String matches search across these Patch fields as one combined text corpus:

name -- the Patch name
description -- the Patch description text
status -- the status text as stored on the Patch
project -- project directory basename (derived from file path)
parent -- parent Patch name (if set)
cl -- PR identifier (if set)
pr_origin -- normalized PR_ORIGIN value (sase, external, or unknown)
commits -- history entry notes and suffixes
hooks -- hook display commands and status line suffixes
comments -- reviewer names, file paths, and suffixes
mentors -- mentor status line suffixes

For normalized status matching, prefer the status: property filter instead of a plain string match. status: strips workspace suffixes and the legacy READY TO MAIL suffix before comparing.

Property Filters¶

Property filters match against a specific Patch field rather than performing a full-text substring search. The supported property filters are exact and case-insensitive:

status:WIP            match Patches with base status "WIP"
project:myproject     match Patches whose effective project name is "myproject"
ancestor:parent_cl    match if name or parent chain includes "parent_cl"
name:foo              match Patches whose name is exactly "foo"
sibling:bar           match Patches in the same sibling family as "bar"
origin:external       match Patches whose PR_ORIGIN is "external"

Valid property keys: status, project, ancestor, name, sibling, and origin. Values can be bare words (starting with a letter, digit, or _ and continuing with letters, digits, _, -, ., or *) or quoted strings (e.g. status:"in progress").

The project: filter uses the ProjectSpec's configured PROJECT_NAME when present and valid; otherwise it falls back to the canonical project directory key. A configured name replaces the directory key for this exact filter rather than adding a second alias. PROJECT_ALIASES are not matched by project: or the + shorthand, and storage paths, workspace lookup, and VCS operations continue using the canonical directory key.

Wildcards¶

A * inside a string-field property value is a wildcard matching any run of characters, including an empty run. Matching stays case-insensitive, consecutive * collapse, and ? is not special. Values without * behave exactly as before.

Query panes use one of two dialects, and globs compose with each dialect's own syntax:

Flat dialects (Beads, Plans, Files, Stitches, and document-provider panes) accept - negation (-id:sase-x7.*) and comma lists (id:sase-16n,sase-16n.*), and bare values may start with * or contain / (path:202609/*tags).
Boolean dialects (the Patch query language on this page, the Agents tab filter, and Artifacts ▸ Agent / sase agent search) use NOT (or !) and OR instead of - and commas. Their bare values must start with a letter, digit, or _ and contain only letters, digits, _, -, ., and *, so quote anything else, as in name:"*_fix" or model:"*opus*". The Agents tab filter's tab: field is exact (main for rows with no stored tab) and is specified in the ace.md Agent Search table. tab: is an Agents field, not a Patch property.

In the Patch query language documented on this page, all six property filters are exact-match fields, so a * in any of them is an anchored whole-value glob: status: globs the base status and sibling: compares the family name with any __<N> suffix removed.

Field kind	`*` semantics	Example
Exact-match string fields (`id`, `name`, `project`, ...) and `sha`	Anchored whole-value glob	`id:sase-16n.*` matches `sase-16n.1` and `sase-16n.10`, but not `sase-16n` or `sase-16n5`
Substring string fields (`path`, `assignee`, `model`, ...)	Unanchored glob: may match anywhere in the value	`path:202609/*tags` matches `docs/202609/tags.md`
Enum, bool, int, and date fields	`*` is literal, so value validation rejects it	`status:clo*` fails with `must be one of ...`

Property Shorthand Prefixes¶

Shorthand	Expands To	Description
`+myproject`	`project:myproject`	Filter by project
`^parent_cl`	`ancestor:parent_cl`	Filter by ancestor (name or parent chain)
`~bar`	`sibling:bar`	Filter by sibling family
`&foo`	`name:foo`	Filter by exact name

In sase's TUI filter rows, a +myproject shorthand that names a known enabled project is highlighted in that project's accent color, the same color as its +<project> prompt tag chip.

Status Shorthands¶

Shorthand	Expands To
`%d`	`status:DRAFT`
`%m`	`status:MAILED`
`%r`	`status:REVERTED`
`%s`	`status:SUBMITTED`
`%w`	`status:WIP`
`%y`	`status:READY`

Status shorthands are case-insensitive (%D and %d are equivalent).

Status Matching¶

The status: filter compares the base status only. For example, a Patch whose stored status is Ready (sase_102) matches status:Ready. It also treats the legacy Ready - (!: READY TO MAIL) form as base status Ready.

Ancestor Matching¶

The ancestor: filter (and ^ shorthand) walks the parent chain recursively. A Patch matches if its own name equals the value, or if any parent, grandparent, etc. in the chain equals the value. Cycle detection prevents infinite loops.

Sibling Matching¶

The sibling: filter (and ~ shorthand) strips any __<N> revert suffix from both the search value and the Patch name, then compares base names. This matches all members of a "family" -- the original plus its __1, __2, etc. variants.

Origin Matching¶

The origin: filter compares the normalized PR_ORIGIN value: sase (created by SASE's tracked PR workflow), external (adopted from a PR SASE did not create), or unknown (no evidence either way -- absent PR_ORIGIN normalizes to unknown). It has no shorthand prefix. It is a UI/manual-filtering convenience only, not a safety mechanism -- external Patches are structurally excluded from AXE work regardless of any query.

Boolean Operators¶

AND (Implicit and Explicit)¶

Adjacent terms are combined with implicit AND. The AND keyword can also be used explicitly:

feature test          implicit AND
feature AND test      explicit AND

OR¶

The OR keyword combines alternatives (lower precedence than AND):

feature OR bugfix

NOT¶

The ! operator or NOT keyword negates the following expression:

!draft                exclude Patches containing "draft"
NOT draft             same as above
!"work in progress"   negate a quoted string

Multiple ! operators stack (double negation cancels out).

Precedence¶

From tightest to loosest binding:

! / NOT (unary negation)
AND (explicit or implicit juxtaposition)
OR

Parentheses override precedence:

(feature OR bugfix) AND !skip
feature AND (test OR lint)

Special Shorthands¶

These shorthands filter Patches by error, agent, or process state recorded in status or suffix fields.

Error Suffix¶

Syntax	Meaning
`!!!`	Match Patches that have an error suffix in status, commits, hooks, or comments
`!`	Same as `!!!` when standalone: followed by whitespace or at end
`!!`	Match Patches with no error suffix (equivalent to `NOT !!!`; standalone only)

Running Agents¶

Syntax	Meaning
`@@@`	Match Patches with a running agent marker in hooks, comments, or mentors
`@`	Same as `@@@` when standalone
`!@`	Match Patches with no running agents (equivalent to `NOT @@@`)

Running Processes¶

Syntax	Meaning
`$$$`	Match Patches with a running process marker in hooks or comments
`$`	Same as `$$$` when standalone
`!$`	Match Patches with no running processes (equivalent to `NOT $$$`)

Any Special¶

Syntax	Meaning
`*`	Errors OR agents OR processes (equivalent to `!!! OR @@@ OR $$$`)

Note: !, @, $, !!, !@, !$, and * are only treated as special shorthands when standalone (at end of input or followed by whitespace). When ! is followed by other characters, as in !"foo", it acts as the NOT operator.

Practical Examples¶

%w                           all WIP Patches
%w +myproject                WIP Patches in "myproject"
feature %d                   drafted Patches containing "feature"
!!! %m                       mailed Patches with errors
!! !@ !$                     no errors, no agents, no processes
^base_cl %w                  WIP descendants of "base_cl"
~my_cl                       all siblings of "my_cl" (including reverted variants)
"fix bug" OR "refactor"      Patches matching either phrase
(bug OR fix) AND !test       bug/fix Patches excluding test ones
c"README" +docs              case-sensitive "README" in the docs project
*                            anything with errors, agents, or processes