Field Theory CLI

Sync and store locally all of your X/Twitter bookmarks. Search, classify, and make them available to Claude Code, Codex, or any agent with shell access.

Free and open source. Designed for Mac.

Install

npm install -g fieldtheory

Requires Node.js 20+. Chrome recommended for session sync; OAuth available for all platforms.

Quick start

# 1. Sync your bookmarks (needs Chrome logged into X)
ft sync

# 2. Search them
ft search "distributed systems"

# 3. Explore
ft viz
ft categories
ft stats

On first run, ft sync extracts your X session from Chrome and downloads your bookmarks into ~/.ft-bookmarks/.

Commands

Sync

Command	Description
ft sync	Download and sync bookmarks (no API required)
ft sync --rebuild	Full re-crawl of all bookmarks
ft sync --continue	Resume an interrupted sync from the saved cursor
ft sync --gaps	Backfill quoted tweets, expand truncated articles, enrich linked article content
ft sync --folders	Also sync X bookmark folder tags (read-only mirror of X state)
ft sync --folder <name>	Sync a single folder by name (exact or unambiguous prefix)
ft sync --classify	Sync then classify new bookmarks with LLM
ft sync --api	Sync via OAuth API (cross-platform)
ft auth	Set up OAuth for API-based sync (optional)

Search and browse

Command	Description
ft search <query>	Full-text search with BM25 ranking
ft list	Filter by author, date, category, domain, or folder
ft list --folder <name>	Show bookmarks in an X bookmark folder
ft show <id>	Show one bookmark in detail
ft sample <category>	Random sample from a category
ft stats	Top authors, languages, date range
ft viz	Terminal dashboard with sparklines, categories, and domains
ft categories	Show category distribution
ft domains	Subject domain distribution
ft folders	Show X bookmark folder distribution (requires ft sync --folders first)

Classification

Command	Description
ft classify	Classify by category and domain using LLM
ft classify --regex	Classify by category using simple regex
ft classify-domains	Classify by subject domain only (LLM)
ft classify --engine <name>	Override the LLM engine for one run (also works on ft sync --classify and ft classify-domains)
ft model	View or change the default LLM engine

Knowledge base

Command	Description
ft md	Export bookmarks as individual markdown files
ft wiki	Compile a Karpathy-style interlinked knowledge base
ft ask <question>	Ask questions against the knowledge base
ft ask <question> --save	Ask and save the answer as a concept page
ft lint	Health-check the wiki for broken links and missing pages
ft lint --fix	Auto-fix fixable wiki issues

Agent integration

Command	Description
ft skill install	Install /fieldtheory skill for Claude Code and Codex
ft skill show	Print skill content to stdout
ft skill uninstall	Remove installed skill files

Utilities

Command	Description
ft index	Rebuild search index from JSONL cache (preserves classifications)
ft fetch-media	Download media assets (static images only)
ft status	Show sync status and data location
ft path	Print data directory path

Agent integration

Install the /fieldtheory skill so your agent automatically searches your bookmarks when relevant:

ft skill install     # Auto-detects Claude Code and Codex

Then ask your agent:

"What have I bookmarked about cancer research in the last three years and how has it progressed?"

"I bookmarked a number of new open source AI memory tools. Pick the best one and figure out how to incorporate it in this repo."

"Every day please sync any new X bookmarks using the Field Theory CLI."

Works with Claude Code, Codex, or any agent with shell access.

Scheduling

# Sync every morning at 7am
0 7 * * * ft sync

# Sync and classify every morning
0 7 * * * ft sync --classify

Data

All data is stored locally at ~/.ft-bookmarks/:

~/.ft-bookmarks/
  bookmarks.jsonl         # raw bookmark cache (one per line)
  bookmarks.db            # SQLite FTS5 search index
  bookmarks-meta.json     # sync metadata
  oauth-token.json        # OAuth token (if using API mode, chmod 600)
  md/                     # markdown knowledge base (ft wiki / ft md)

Override the location with FT_DATA_DIR:

export FT_DATA_DIR=/path/to/custom/dir

To remove all data: rm -rf ~/.ft-bookmarks

Categories

Category	What it catches
tool	GitHub repos, CLI tools, npm packages, open-source projects
security	CVEs, vulnerabilities, exploits, supply chain
technique	Tutorials, demos, code patterns, "how I built X"
launch	Product launches, announcements, "just shipped"
research	ArXiv papers, studies, academic findings
opinion	Takes, analysis, commentary, threads
commerce	Products, shopping, physical goods

Use ft classify for LLM-powered classification that catches what regex misses.

Platform support

Feature	macOS	Linux	Windows
Session sync (ft sync)	Chrome, Chromium, Brave, Helium, Comet, Firefox	Chrome, Chromium, Brave, Firefox	Chrome, Chromium, Brave, Firefox
OAuth API sync (ft sync --api)	Yes	Yes	Yes
Search, list, classify, viz, wiki	Yes	Yes	Yes

Session sync extracts cookies from your browser's local database. Use ft sync --browser <name> to pick a browser. On Windows, Firefox requires Node.js 22.5+ or sqlite3 on PATH. For unsupported browsers or platforms, use ft auth + ft sync --api.

Security

Your data stays local. No telemetry, no analytics, nothing phoned home. The CLI only makes network requests to X's API during sync.

Chrome session sync reads cookies from Chrome's local database, uses them for the sync request, and discards them. Cookies are never stored separately.

OAuth tokens are stored with chmod 600 (owner-only). Treat ~/.ft-bookmarks/oauth-token.json like a password.

The default sync uses X's internal GraphQL API, the same API that x.com uses in your browser. For the official v2 API, use ft auth + ft sync --api.

License

MIT — fieldtheory.dev/cli

Star History