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.

Host-owned `in:` scope¶

in:inbox and in:archive are host-owned scope tokens for Agents-tab and sase agent search queries. The CLI keeps its catalog behavior when the token is absent; in:inbox searches non-dismissed catalog rows, while in:archive searches the shared hidden archive corpus with the agents-archive profile. That profile adds outcome, restorable, tab, tribe, clan_tribe, linked, relation, and artifact to the shared agent fields. Inbox-only fields such as unread, pinned, needs, source, cl, and machine do not belong to the archive profile.

The token is extracted before profile evaluation. It may appear once at top level and cannot be negated or appear inside OR or parentheses. On the Agents tab it validates the query and provides field-scope hints; it does not switch the visible view. An archive-only field without in:archive, or an inbox-only field with in:archive, gives a hint naming the required scope.

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 the default sase agent search path uses the catalog profile. The CLI's in:archive path uses agents-archive against the compiled archive corpus. The live profile includes operational fields such as machine, pinned, unread, needs, and source; the archive profile adds outcome, restorable, tab, clan_tribe, and archive link facets. See sase's TUI: Archive 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.

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); 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-<other>.*) and comma lists (id:sase-<root>,sase-<root>.*), and bare values may start with * or contain / (path:202609/*tags).
Boolean dialects (the Patch query language on this page, the Agents tab filter with its in:inbox / in:archive scopes, and 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 Agents tab 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-<root>.*` matches `sase-<root>.1` and `sase-<root>.10`, but not `sase-<root>` or `sase-<root>5`
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

CLI command groups — generated flags and subcommands.
Patches — Patch records the query language filters.

`sase agent search`¶

sase agent search [QUERY ...] searches the historical agent catalog behind the Agents tab Archive, rather than the live operational rows returned by agent list. Without an in: token it keeps the current catalog behavior. Queries use AND, OR, NOT, parentheses, free text, and the catalog's identity, lineage, lifecycle, time/runtime, and artifact-link fields. For example:

sase agent search 'revivable:true AND project:sase AND role:code'
sase agent search 'provider:codex AND status:FAILED AND since:7d'
sase agent search 'linked:true AND relation:read'
sase agent search 'in:inbox AND status:FAILED'
sase agent search 'in:archive AND outcome:failed AND project:sase'

A bare search applies the default presentation scope: hidden rows and kind:workflow-child rows are omitted unless the query explicitly asks for them. The default cap is 40; -l 0, --limit 0, or limit:all removes it, and an explicit -l/--limit overrides a limit: token inside the query. -p/--project accepts a project key, alias, or display name. Options may appear before or after the query, and -j/--json emits a stable array.

in:inbox keeps the catalog query path and restricts matches to non-dismissed rows. in:archive searches hidden archive rows through the shared archive corpus; it supports the archive profile fields outcome, restorable, tab, tribe, clan_tribe, linked, relation, and artifact. Archive output is ordered by last activity, and JSON contains the corpus's light derived rows. The token is host-owned, may appear once at top level, and cannot be negated or appear inside OR or parentheses.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.