Field Theory CLI: X bookmark sync, local search, and agent context in one tool

Browser session extraction means ft sync needs no X API key

X bookmark sync works without any API key or developer account. Running ft sync extracts your X session from a Chrome-family browser or Firefox, then downloads your bookmarks and fetches associated media including photos, video posters, and capped videos. Bookmarks land in ~/.fieldtheory/bookmarks/ after that first run.

9 flags modify this default behavior. Skipping media entirely uses --no-media; keeping post media but dropping author profile images uses --skip-profile-images. Interrupted runs resume from a saved cursor with --continue. Full re-crawls require --rebuild. Content gaps get addressed by --gaps, which backfills quoted tweets, expands truncated X Article text, enriches linked articles, and fills any media gaps the original pass missed.

Folder sync is separate from the main bookmark pass. Passing --folders mirrors your X bookmark folder tags as a read-only copy. Syncing a single folder by exact name or unambiguous prefix uses --folder <name>. Running --classify adds an LLM classification step after sync completes, making sync and classify a one-pass operation.

Users who prefer an API-based approach can set up OAuth first with ft auth, then pass --api to any sync command. That route is described as cross-platform, unlike the browser session path.

npm install -g fieldtheory at version 1.3.22, and three commands to start

fieldtheory is published on npm under that exact name. A global install gives two binaries pointing to the same entry point at bin/ft.mjs: ft and fieldtheory.

npm install -g fieldtheory

Node.js 20 or newer is the only system requirement. After installation, the quick start sequence from the README runs three commands.

ft sync
ft search "distributed systems"
ft viz

ft sync downloads bookmarks to ~/.fieldtheory/bookmarks/. ft search runs a BM25-ranked full-text query across them. ft viz opens a terminal dashboard with sparklines, categories, and domains. Running ft categories and ft stats afterward adds a category breakdown and a summary of top authors, languages, and the date range the collection spans.

Version 1.3.22 is what package.json records. No GitHub releases exist in the repository, and the last push was on 2026-09-05. Anyone who needs a reproducible environment should pin the exact npm version rather than relying on latest.

sql.js-fts5 and BM25 are the local search engine under ft search

package.json lists two SQLite dependencies as production requirements: sql.js at version 1.14.1 and sql.js-fts5 at version 1.4.0. SQLite runs in WebAssembly, so the database travels with the npm package and requires no system SQLite installation. FTS5 is the SQLite full-text extension; BM25 is its ranking function.

Search goes beyond a single query string. ft list filters by author, date, category, domain, or folder. Adding --folder <name> narrows results to a single X bookmark folder. For a random sample from a named category, ft sample <category> picks one bookmark without any query.

Two commands give aggregate views of the collection. ft stats shows top authors, languages, and the date range. ft viz combines sparklines with category and domain breakdowns in a terminal dashboard. ft domains isolates subject domain distribution separately from the category view ft categories provides.

One trade-off with running SQLite via WebAssembly is size. sql.js carries the full SQLite binary as a WASM file, adding more to the npm package than linking against a native library would. Database file location is not documented in the README body, but ft paths --json prints the canonical paths for bookmarks, Library, and commands.

LLM classification assigns categories and domains, with a per-run engine override

Classification is a separate pass from sync. Running ft classify sends unclassified bookmarks to an LLM and assigns a category and domain to each. For an offline alternative, --regex switches to simple regex-based categorization with no network call. ft classify-domains limits a run to subject domain assignment only, without touching category labels.

Selecting an LLM engine is not fixed at install time. ft model shows the current default and lets you change it. A per-run override uses --engine <name> directly on ft classify; that flag also works on ft sync --classify and on ft classify-domains, letting you test a different engine without changing the default.

What the README does not document is which specific engines are available by name, what the token cost looks like per bookmark, or what happens when the LLM returns a classification format the tool cannot parse. Those gaps matter before running classification against a large collection, because cost and error handling are entirely outside the documented behavior.

ft wiki compiles a Karpathy-style interlinked knowledge base from local markdown

Knowledge base commands build on top of the bookmark index. Start with ft md, which exports each bookmark as an individual markdown file including enriched article text. Running ft md --changed re-exports only files whose source data changed since the last export, keeping the process fast as a collection grows.

ft wiki compiles those markdown files into what the README calls a Karpathy-style interlinked knowledge base. What that structure looks like in practice is not described in the README, but the lint tooling implies the output is a set of linked pages: ft lint health-checks for broken links and missing pages, and ft lint --fix applies auto-fixes to whatever issues it considers fixable.

Asking questions against the knowledge base uses ft ask <question>. Adding --save records the answer as a concept page under the local store. That path goes from raw bookmarks to a searchable, linked reference collection without any cloud dependency, since everything lives under ~/.fieldtheory.

ft possible runs seed-and-repo workflows, with background mode and a macOS nightly installer

Possibility runs are the least documented section of the README. ft possible is described as an interactive seed, repo, and frame wizard, but the README gives four commands as a table without defining what seeds, repos, or frames mean in this workflow.

4 commands cover the workflow: ft seeds search "<query>" --create saves a bookmark-grounded seed, ft repos add <path> adds a local repo to the default set, ft possible run --defaults re-runs with the most recently used seed and repos, and ft possible run --background starts a run as a background job. Installing a nightly scheduled run uses ft possible nightly install, which is specific to macOS.

ft possible prompt <node-id> prints the goal prompt for one plotted node, which implies the workflow produces a graph of nodes rather than a linear output, but that graph structure is not explained anywhere in the repository files available here. Evaluating whether possibility runs fit a specific workflow requires reading the source under src/ or the documentation at https://fieldtheory.dev/cli.

Designed for Mac: three environment variables and four sibling repositories

Several commands in the CLI require the companion Mac app. ft install app downloads and installs the latest release from the afar1/field-releases repository. ft library open <path> opens a Library page in the packaged app using its bundle id com.fieldtheory.app, rather than a system-wide URL scheme. That design avoids accidentally triggering a development build when another local checkout has registered the same fieldtheory:// handler.

3 environment variables control how the app companion behaves. FT_APP_DEV_DIR set to a local checkout path redirects ft library open to that development instance instead of the packaged app. FT_APP_BUNDLE_ID overrides the default bundle id for packaged variants. FT_APP_OPEN_COMMAND accepts an executable that receives the deep-link URL as its first argument, for custom launchers.

4 sibling repositories split the project: afar1/fieldtheory-cli holds this CLI under MIT, afar1/fieldtheory holds the Mac app source, afar1/fieldtheory-plugin holds the Codex plugin and skills, and afar1/field-releases holds packaged app releases and updater metadata. Issues for each component go to their respective repository, as the README specifies.

Outside macOS, OAuth sync works and the search and classification commands carry no documented platform restriction. ft install app, ft library open, and ft possible nightly install all assume macOS.

Editorial conclusion

Use Field Theory CLI if you bookmark X posts regularly and want a local, searchable archive that also serves as context for Claude Code or Codex. Skip it if you do not use X or if Windows is your primary platform, because the repository explicitly describes the tool as designed for Mac and several commands require the Mac app. Before relying on it, run ft sync once and confirm that browser session extraction picks up your bookmarks, since that path requires a logged-in Chrome-family browser or Firefox. OAuth via ft auth is the stated cross-platform fallback, but there are no GitHub releases, so pin a specific npm version when you install.

Frequently asked questions

Official sources

1. afar1/fieldtheory-cli on GitHub
2. Issues
3. License: MIT
4. Project website
5. README