Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
CLI Query Pagination and Read-Only SQL Plan
Background
Agent-facing list commands currently return all matching records. vibe runs list
only exposes --status, while vibe show list only exposes --visibility.
As Agent Runs and Show Pages accumulate, these commands need bounded defaults,
clear next-page hints, and a reusable path for future list commands.
Agents also need a more flexible exploration path for ad hoc conditions that do not deserve first-class CLI flags. That path should be read-only SQL, not a write-capable database escape hatch.
Goals
- Add a shared pagination contract for CLI list/query commands.
- Default list commands to 20 records and include a next-page hint when more records exist.
- Add high-value filters to
vibe runs listandvibe show list. - Add a guarded
vibe data queryread-only SQLite query command. - Keep simple, stable CLI flags as the primary day-to-day interface; use SQL for exploratory and low-frequency conditions.
Design
Shared Pagination
Introduce a small reusable module with:
PageRequest(page=1, limit=20, max_limit=100)PageResult(items, page_request, has_more)- helpers to clamp/validate CLI input, slice
limit + 1, and build JSON pagination payloads.
All list/query commands should return:
pagination.pagepagination.limitpagination.returnedpagination.has_morepagination.next_pagepagination.next_command
pagination.next_command is the only continuation: no top-level prose repeats
it. A page whose command cannot be replayed (SQL piped on stdin, which has no
next_command) adds one message telling the caller to add --page.
Task and Watch Lists
vibe task list and vibe watch list take --q with the same substring
semantics as vibe runs list --q, searching the store's definition text fields
(the Workbench search), and carry it into next_command. Enabled definitions
come first, each group ordered by most recent activity.
Runs List
Extend vibe runs list with:
--page,--limit(always bounded; no unpaginated bypass)--status--type--agent--backend--session-id--definition-id--created-after--created-before--q
SQLite-backed runs should filter in SQL. File-backed fallback can filter in memory; it is compatibility-only.
Show Page List
Extend vibe show list with:
--page,--limit(always bounded; no unpaginated bypass)--visibility--session-id--updated-after--updated-before--q
ShowPageStore.list() should support these filters and pagination using the
same shared result type.
Read-Only SQL
Add vibe data query:
vibe data query --sql "select id,status,created_at from agent_runs order by created_at desc"
vibe data query --sql-file query.sql --limit 50
Safety layers:
- open SQLite with
file:...?mode=ro - set
PRAGMA query_only = ON - use
sqlite3.Connection.set_authorizer()to deny writes, schema changes, attaching databases, transactions, and every PRAGMA except the schema-readingtable_list,table_info,table_xinfo,index_list,index_info, andforeign_key_list(statement orpragma_*table-valued form), so Agents can discover the schema with the query they already reach for - execute one statement with
execute(), neverexecutescript() - use progress handler limits to avoid runaway queries
- force pagination/default limit behavior on result output
- on
no such table/no such column, return ahintwith the closest names and the table list or the referenced tables' columns; on a refused PRAGMA, name the allowed ones. The hint is advisory: if reading the schema fails, the query's own error is returned unchanged - the connection keeps Python's default 5 s busy timeout, the same bound as
storage/db.py; WAL readers do not wait on writers
The SQL command is Agent-facing and should emit JSON by default through the same CLI payload style.
Validation
- Unit tests for pagination helpers.
- Runs store tests for filtering and pagination.
- Show Page store/CLI tests for pagination hints and filters.
- SQL query tests for SELECT success and write/DDL/multi-statement rejection.
- CLI parser tests for new arguments.
- Targeted ruff and pytest checks.