claudbg/specs/FILTER.md

Filter Queries

We want basic filtering to be able to narrow our view. Use cases include only showing sesisons...

• with sub-agents
• with a certain minimum/maximum of messages
• in a given project
• with a given model
• between a given date range

Proposed query language is a simple key:value for static single values, with support for globbing and by default fuzzy searching. Examples:

• model:haiku equivalent to model:*haiku*
• project:my-org/my-project ~= project:*my-org/my-project
• project:* project is non-empty

Also required is support for > and < to support ranges Examples:

• agents>0
• messages<10
• date>2026-03-20

We also need to support AND and OR for logical combinations Examples:

• date>2026-03-15 AND date<2026-03-20 sessions between 03-15 and 03-20.

When a query uses a malformed syntax or a key which is not found, the command should fail to evaluate with an error displayed to the user.

This integrates into the CLI by adding a `--filter` flag which accepts a string filter query. example: `claudbg sessions list --filter 'agents>0'` lists all session with sub-agents. The `--filter` query can be passed multiple times, resulting in the queryies being combined into with AND example: `caudbg sesions list --filter 'agents>0' --filter 'messages>100'` is equivalent to `claudbg sessions list --filter 'agents>0 AND messages>100'` The TUI should include a text box panel at the bottom of the sceen wich accepts a filter. When the user presses enter this query is run on the current main panel (sessions or agents). Pressing escape clears the text input. Pressing up/down arrows cycles through a scroll-back history. Users cycle through panels with Tab to get to this, or press `t` to navigate directly to the text input. When users press enter they are navigated to the main panel so they can interact with the filtered data. This text box does not (yet) interact with session/sub-agent transcripts as these objects cannot be filtered.