X data
For X reads in any project, use this order and stop when the requested evidence is sufficient:
- Local Birdclaw snapshot. Search the current indexed archive first, including supplied post URLs and recent content. Use the installed
birdclawCLI or read-only SQLite at~/.birdclaw/birdclaw.sqlite. A URL supplies a tweet ID; it does not bypass the archive. - Globally installed
bird. Fill archive gaps through the existing authenticated browser session. The personal account is@transitive_bs; verify it withbird --plain whoamibefore account-specific reads or syncs. Use installed command help rather than assuming a command exists. - Public FxTwitter API. If
birdfails or lacks the required operation, tryhttps://api.fxtwitter.comfor public data. It cannot supply private DMs, authenticated bookmarks, or other account-private data; mark that tier inapplicable for those requests. - Paid
xurl. Use the xurl reference only after the cheaper applicable sources failed or could not provide the required evidence. Keep calls bounded and report why the paid fallback was needed.
Freshness is part of sufficiency. Check the archive's observation/sync timestamps; if the request needs current engagement, profile state, or posts beyond its coverage, retrieve only those missing or stale fields in the same order. Preserve archive context and distinguish cached observations from live results. An empty result is a coverage gap, not proof that a post or person never existed.
Common reads
birdclaw --json show tweet POST_ID
birdclaw --json show thread POST_ID
birdclaw --json search tweets "query" --limit 50
birdclaw --json search tweets --author transitive_bs --since YYYY-MM-DD --limit 100
For archive analysis, local DMs, identity resolution, or synchronization, read the Birdclaw skill when installed. Its optional enrichment can touch live transports: use --no-xurl-fallback for identity/DM enrichment, and explicit --mode bird for syncs. auto may fall back to paid xurl before trying FxTwitter.
After the local probe, common bird reads are:
bird read POST_ID_OR_URL --json
bird thread POST_ID_OR_URL --max-pages 2 --json
bird search "from:transitive_bs query" -n 20 --json
bird user-tweets transitive_bs -n 20 --json
After bird fails, fetch a public post with:
curl --fail --silent --show-error --max-time 30 \
-H 'User-Agent: personal-x-data/1.0' \
"https://api.fxtwitter.com/2/status/POST_ID"
Validate both HTTP status and the JSON code, and require a usable status object. Other v2 endpoints and response shapes are documented by FxEmbed; the live spec is https://api.fxtwitter.com/2/openapi.json. Send only the public identifier or query needed for the lookup. Private archive/DM context stays local.
Writes and account actions
The archive and FxTwitter are read sources. For an authorized X post or reply, prefer a supported bird command; use xurl if that operation is unavailable or fails. Apply the lookup order to any reads needed to prepare the action. A read or sync request does not authorize posting, messaging, or changing the account.
Use existing authentication without printing cookies, tokens, or credential files. If sandbox restrictions block an installed transport, use the normal tool approval path when available before treating it as an authentication failure.
