xmarks

Capture, organize, and actually read your X (Twitter) bookmarks from the terminal — no paid API, no tokens to paste.

xmarks drives a browser with your own logged-in X session, saves every bookmark locally, enriches each one with the content behind it, and turns the pile into a searchable dashboard and AI-ready knowledge notes.

Install

npm install -g xmarks
npx playwright install chromium   # one-time browser download

Requires Node ≥ 20.

Quickstart

xmarks login              # sign in to X once, in the window that opens
xmarks capture            # pull your bookmarks
xmarks dashboard --open   # browse them

Log in again with another handle to add an account — every command spans all accounts by default (--account <handle> narrows it).

How it works

• login opens a real browser once; you sign in normally, 2FA included. No cookies or tokens to manage — the session lives in a local browser profile.
• capture reads the bookmarks page headlessly, intercepting X's own GraphQL responses as it scrolls, and appends only new tweets. Incremental by default (stops at bookmarks it already has), so scheduled runs take seconds. Each new bookmark is auto-enriched with its full content — article bodies, self-threads, quoted tweets.
• analyze clusters the unread bookmarks into a dated digest and refreshes the dashboard.
• Everything lives under XMARKS_HOME (default ~/.xmarks) — nothing private touches the repo.

Commands

| Command | What it does | |---|---| | xmarks login | Interactive X login; run once per account. | | xmarks capture [--max N] [--since 7d] [--full] | Fetch bookmarks, add new ones, auto-enrich them. Incremental unless --full. | | xmarks analyze [--llm] | Cluster + summarize unread bookmarks → digest + dashboard. | | xmarks dashboard [--open] | Rebuild the HTML dashboard: a Knowledge tab (agent notes) + a searchable Library tab (every bookmark). | | xmarks list [--new] [--limit N] [--json] | Print bookmarks newest-first. --json for tooling. | | xmarks enrich [ids…] | Backfill the content behind older bookmarks. | | xmarks notes | List the knowledge notes agents have written. | | xmarks mark [ids…] [--topic T] | Set the analyzed flag — the hand-off for external analysis tools. | | xmarks stats | Totals, backlog, top authors and domains. | | xmarks accounts | List logged-in accounts and their store sizes. | | xmarks reset [--data] | Restore a clean state. Confirms first. | | xmarks home | Print the active data directory. |

Capture bounds: capture stops as soon as it reaches bookmarks it already has — do one full first pull, then runs are fast. --full forces a complete rescan. --max N caps new bookmarks per run (good for chewing through a backlog). --since 7d|24h|2026-06-01 filters by when a tweet was written, not when you bookmarked it — so prefer the default for incremental runs.

Analyze with your AI agent

The real analysis layer is the agent you already use — Claude Code, Gemini CLI, and friends. No API key needed. Because xmarks enriches every bookmark with its full text, the agent can genuinely read what you saved, synthesize it, and save knowledge notes that later sessions build on.

xmarks skill install   # installs the skill for Claude Code + Antigravity

Then just ask: "analyze my new bookmarks." The full contract — and setup for any other agent — is in AGENTS.md.

Offline fallback: xmarks analyze groups bookmarks heuristically; add --llm to use the Claude API directly (needs ANTHROPIC_API_KEY).

Scheduling

xmarks capture is built to run unattended. Ready-made configs for launchd, cron, systemd, and Windows Task Scheduler live in schedule/. Append && xmarks analyze --llm for an automatic morning digest.

Data & privacy

• Your X credentials never leave your machine — they live only in the local browser profile. Nothing is sent anywhere but X itself (and Anthropic, only if you opt into --llm).
• xmarks automates X's internal web endpoints with your own session. Fine for personal use of your own data, but technically against X's Terms of Service, and it can break when X ships web-app changes.
• Data lives under ~/.xmarks/accounts/<handle>/: store.json (all bookmarks), notes/ (agent knowledge notes), digests/, and index.html. Override the location with XMARKS_HOME; xmarks home shows what resolved.

Development

pnpm install && pnpm build
pnpm dev -- capture   # run the CLI from source
pnpm test

PRs welcome.

License

MIT