Mentions

birdclaw mentions export is the agent-and-script-friendly view onto your mentions queue. It always emits JSON, supports three modes, and caches every live response so repeated reads do not keep spending the API budget.

#Three modes

#`birdclaw` (default)

Returns normalized items from the local SQLite store with rendered text variants:

3 mentions 4 0 1 2 10

Each item carries:

raw text
rendered plainText with URLs/handles expanded
rendered markdown for chat or doc embeds
canonical tweet URL
author metadata (handle, display name, avatar URL, follower count, verified)
reply-state metadata (replied / unreplied, last-replied-at)

This is what an agent should consume by default — it stays inside the local cache and never touches the live API.

#`xurl`

Mirrors the xurl mentions response shape: data, includes.users, meta. The payload is cached in SQLite and reused until the cache TTL expires:

2 mentions 3 0 4 1 5
3 mentions 4 0 5 1 2 5
5 mentions 6 0 7 1 2 3 9 4 100
3 mentions 4 0 1 5 2 5

In paged xurl mode, --limit is the page size, not the total returned count.

#`bird`

Shells out to your local bird CLI, normalizes the response into the same xurl-compatible shape, and caches it. Useful when xurl is rate-limited or when an account only has cookie-backed access:

2 mentions 3 0 4 1 20
3 mentions 4 0 5 1 2 20

#Common flags

--account <account-id> — pick the account when multiple are configured
--mode birdclaw|xurl|bird
--replied / --unreplied
--refresh — force a live fetch
--cache-ttl <seconds> — tune cache freshness
--all — paginate until exhausted (paged modes only)
--max-pages <n> — cap the paged scan; implies --all
--limit <n> — page size in paged modes, total otherwise

#Filters keep working in cached live modes

Query filters ("agent", --replied, --unreplied) and reply-state filters still apply in --mode xurl and --mode bird. The filtered payload is rebuilt from the local canonical store after the response cache lands, so the response shape stays xurl-compatible while the filter behavior matches the local view.

#Default source via config

If you use bird for mentions most of the time, set it once:

Now birdclaw mentions export defaults to --mode bird for that user. --mode xurl still works for one-off live API checks.

#Wiring it into an agent

The birdclaw mode is designed for agents:

4 mentions 5 1 2 20 3 | 6 0

Pair with the profile reply scan below to pre-flight whether a mention came from a likely AI/templated account before drafting a response.

#Profile reply scan

When one mention feels borderline ("is this actually a person?"), look at the recent replies that account sent across other threads:

2 profiles replies @borderline_handle 0 12 1

What it does:

pulls the live authored timeline
excludes retweets, keeps replies only
surfaces repeated generic praise, abstraction soup, and templated cadence

Typical tells:

the same upbeat, generic reply shape across unrelated threads in a short time window
replies that praise the OP without engaging with the content
short replies that map 1:1 to a small set of templates

Use this to bucket "definitely a person", "unsure", and "obviously templated" before deciding whether to mute, block, or just archive.

#Live mention threads

If you want the conversation context for each mention (the parent tweet, the reply chain), run sync mention-threads first. That populates ancestor tweets in the local store so mentions export can reference them without an extra live call per mention.

#See also

Inbox — same items, ranked by heuristics or OpenAI
Sync — cursor / pagination behavior
Moderation — turn a borderline reply scan into a block decision