Query Message History Skill

Process steps in order. Do not skip ahead.

Step 1 — Run the query

Run the helper with at least one filter set:

python3 /home/node/.claude/skills/tessl__query-history/scripts/query-message-history.py --keyword "<text>"

Provide at least one of --keyword <text> (matches content) or --sender <name> (matches sender_name); both can be combined and AND together. --limit N defaults to 20 and is capped at 50 rows per rules/query-size-limits.md — the script rejects higher values at exit 2. --offset N (default 0, negative rejected at exit 2) pages past earlier batches when a result set exceeds the row cap. Chat scope comes from the NANOCLAW_CHAT_JID env var, set automatically inside every container; no chat selection happens at the call site. The script wraps LIKE matches with explicit escape, so user-supplied % / _ / \ characters match literally. The DB is opened read-only via file:…?mode=ro, so a missing or mistyped NANOCLAW_DB fails at connect time rather than silently creating a bogus empty database. Proceed immediately to Step 2.

Step 2 — Read the JSON output and act on it

The script prints a single-line JSON payload to stdout: {rows, chat_jid, query, truncated, rows_dropped, error}. Each entry in rows carries id, timestamp, sender_name, content, is_from_me, content_truncated. Newest-first ordering. The serialized output honors the rules/query-size-limits.md tool-result budget on every path. truncated reports that the cap engaged, content_truncated marks a clipped row, and rows_dropped counts rows cut from the result (cap mechanics: see scripts/query-message-history.py, cap_payload). On a truncated result, narrow the filters or batch with --offset instead of treating the rows as complete. error is null on clean success and a short string on runtime failure (DB unreadable, missing env var), exit 1 with the JSON still emitted. Usage errors (bad flags: exit 2) print the diagnostic to stderr only — no JSON on stdout; do not parse stdout on exit 2. If rows is empty AND error is null, the search ran cleanly with no matches — proceed silently with that information; do not fabricate matches. If error is non-null, surface the error to the caller and stop. Otherwise return the matched rows in the format the caller needs. Finish here.