Reading & Triage

Research

GitHub Edit page

Research

birdclaw research is a bookmark-driven thinking tool. Point it at a query (or just an account) and it walks the bookmarked tweets that match, expands their threads, and produces a markdown brief with grouped quotes, extracted links, and handles you might want to follow up with.

#Basic use

4 research 0 1 20 2 10 3
2 research 0 acct_primary 1 ~/research/codex.md

What it does:

  • queries the local tweets table for matches inside the bookmarks collection
  • expands each match into its full thread using the local store first
  • when ancestors are missing locally, falls back to live thread lookup through bird thread
  • renders one markdown file with each thread as a section: original tweet + replies as block quotes
  • pulls out https:// URLs and @handle references into a deduped list at the end

The output is meant to be read in Obsidian, a chat draft, or piped into another tool.

#Flags

  • --limit <n> — max number of bookmarked tweets to expand into threads
  • --thread-depth <n> — how many ancestor levels to walk
  • --account <id> — multi-account selector
  • --out <path> — write the brief to a file instead of stdout (auto-creates parent directories)
  • --json — emit a JSON envelope instead of markdown (useful for chaining into agents)

#Live thread expansion

When a thread ancestor is not in the local store, research makes a single bird thread call per missing chain. This is gentle on the live API by design — rate-limit-aware with --delay-ms semantics inherited from sync mention-threads.

If you do this kind of expansion regularly, run birdclaw sync mention-threads and birdclaw sync bookmarks --all first. That populates the local store with everything research needs and removes the live calls from the hot path.

#Example output

# Research: "codex"

## Bookmark · 2026-04-12

> @author: Original tweet about codex agents.
>
> @reply1: Adds context about scaling.
> @reply2: Pushes back on the framing.

## Bookmark · 2026-04-09

> @another: Different angle on the same topic.

## Links

- https://example.com/codex-explainer
- https://other.example/talk

## Handles

- @author
- @reply1
- @reply2
- @another

The --json shape mirrors that structure with an items array (one per bookmark), links, and handles.

#See also

  • Search — base query model
  • Sync — top up bookmarks before researching
  • Mentions — same idea applied to a single account