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 --full | Full history crawl (not just incremental) | | ft sync --gaps | Backfill missing quoted tweets and expand truncated articles | | 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 | | 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 |

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 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, Brave, Arc, Firefox | Firefox | 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 platforms where session sync isn't available, 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