Field Theory CLI (Fieldtheory)
Self-custody for your X/Twitter bookmarks: a free, open-source CLI that syncs every bookmark locally (no API), indexes them with SQLite FTS5 + BM25, and exposes them to Claude Code, Codex, or any shell-capable agent. It is the first stage of Kevin's bookmark → wiki pipeline.
What it is
fieldtheory (binary ft) is a macOS-first command-line tool by Andrew Farah (@andrewfarah, GitHub afar1/fieldtheory-cli) that downloads and locally stores all of a user's X/Twitter bookmarks, then makes them searchable, classifiable, and agent-readable. Tagline: "Self-custody for your X/Twitter bookmarks. Local sync, full-text search, classification, and terminal dashboards." Source: npm fieldtheory, https://registry.npmjs.org/fieldtheory, 2026-06-12
Install is one command:
npm install -g fieldtheory@latest # binary: ft (Node 20+, Chrome)
ft sync # extract X session from browser, download all bookmarks
Source: fieldtheory.dev/cli, https://www.fieldtheory.dev/cli, 2026-06-12
The key insight — session extraction beats the API
X's official API caps bookmark retrieval at 99 items, which makes a real personal archive impossible through the documented endpoints. ft sidesteps this: on first run it extracts the logged-in X session from a local browser (via the macOS Keychain) and crawls the full bookmark list directly — no API key, no 99-item ceiling. The author notes he had bookmarked 6,577 posts since 2008, none reachable through the API. OAuth API sync (ft sync --api) exists as a cross-platform fallback. Source: fieldtheory.dev/cli, https://www.fieldtheory.dev/cli, 2026-06-12
Commands
| Command | What it does |
|---|---|
ft sync |
Download + sync all bookmarks, then fetch missing media (photos, video posters, capped videos). No API. |
ft sync --gaps |
Backfill quoted tweets, expand truncated / X Article text, enrich linked articles, fill media gaps |
ft sync --rebuild |
Full re-crawl of all bookmarks |
ft sync --continue |
Resume an interrupted sync from the saved cursor |
ft sync --folders / --folder <name> |
Mirror X bookmark folder tags (read-only) |
ft sync --classify |
Sync, then LLM-classify new bookmarks |
ft sync --api / ft auth |
OAuth API sync (cross-platform) / set up OAuth |
ft search |
Full-text search over the local archive (BM25 ranking) |
ft classify |
Categorize bookmarks via LLM or regex |
ft viz |
Interactive terminal dashboard of categories + stats |
ft wiki |
Generate a markdown wiki from bookmarks |
ft md |
Export bookmarks as markdown |
ft skill install |
Register the /fieldtheory skill for agents (Claude Code, Codex, …) |
Source snapshot
As of 2026-07-04, npm fieldtheory is 1.3.22 (latest), with registry time.modified at 2026-06-15T05:49:36Z. The GitHub repo afar1/fieldtheory-cli is MIT-licensed, default branch main, HEAD 4b4a0f677e7077ac76848408b22091fc34330391, pushed 2026-06-15T05:16:47Z, with 1,938 stars, 201 forks, and 35 open issues. No release tags were returned by the source check. Source: npm/GitHub source checks, 2026-07-04
Data layout & platforms
All data lives locally at ~/.ft-bookmarks/ — raw bookmarks (bookmarks.db, an SQLite FTS5 index), JSON, downloaded media, and exported md/. Search is BM25 over FTS5, the same lexical-ranking foundation Kevin's QMD - Local Wiki Search Engine uses for its keyword layer. Source: fieldtheory-cli README, https://github.com/afar1/fieldtheory-cli, 2026-06-12
| Capability | macOS | Linux / Windows |
|---|---|---|
Session sync (ft sync) |
Chrome, Chromium, Brave, Edge, Helium, Comet, Dia, Firefox | Chrome/Chromium/Brave/Edge/Firefox |
OAuth API sync (ft sync --api) |
Yes | Yes |
| Search, list, classify, viz, wiki | Yes | Yes |
Session extraction is macOS-only (Keychain); Linux/Windows users sync through ft auth + --api. Source: fieldtheory-cli README, 2026-06-12
Where it fits Kevin's stack
fieldtheory is the collector at the head of Kevin's bookmark → wiki pipeline. scripts/sync-x-bookmarks.sh runs ft sync to pull bookmarks into raw/x-bookmarks/; the Cloud, Data, and Service Skills skill then enriches and absorbs them into the wiki graph (the very process producing this page). AGENTS.md lists ft sync as the X-bookmarks capture source. It is an exemplar Agent-Native CLIs: local SQLite mirror, shell-driven, BM25 search, zero API fees — the same design philosophy as PrintingPress pp-clis. Distinct from a full personal-brain tool like Nia Vault: ft owns capture + local search, while the wiki/agent layer owns synthesis. Source: compiled from AGENTS.md + repo, 2026-06-12
Timeline
- 2026-04-06 | @andrewfarah reported "6,300 bookmarks for a bookmarking cli" as early demand evidence for the
fieldtheorybookmark-sync wedge. The row is a social-proof signal; the current command surface and version authority remain the npm/GitHub snapshot above. Source: X/@andrewfarah, 2026-04-06 - 2026-04-08 | @andrewfarah's "love letter" post documented the install + command surface (
npm i -g fieldtheory,ft sync --gaps,ft wiki,ft md,ft skill install) after thousands of downloads in 48h. 619 likes, 966 bookmarks. Source: X/@andrewfarah, 2026-04-08 - 2026-06-12 | Page created during the domain-2a bookmark-absorption pass. Repo
afar1/fieldtheory-cliat 1,905 stars; npmfieldtheoryv1.3.19; tagline "self-custody for your X/Twitter bookmarks." Confirmed as the collector feeding Kevin'ssync-x-bookmarks.sh+ Cloud, Data, and Service Skills pipeline. Source: afar1/fieldtheory-cli, https://github.com/afar1/fieldtheory-cli, 2026-06-12 - 2026-07-04 | Source-reviewed the April 8 "love letter" row and refreshed the version snapshot: npm
fieldtheory@1.3.22, repo HEAD4b4a0f677e7077ac76848408b22091fc34330391, MIT, 1,938 stars, 201 forks, 35 open issues, no release tags returned. The row reinforcesft sync --gaps,ft wiki,ft md, andft skill installas the command surface behind Kevin's bookmark pipeline. Source: npm/GitHub source checks, 2026-07-04; X/@andrewfarah, 2026-04-08