Field Theory CLI
Sync X bookmarks locally and make them searchable for shell-based agent workflows.
Per-dimension scores and reasoning
Evidence shows: README explicitly states data stays local, no telemetry, no analytics, and OAuth tokens are stored with chmod 600, warning users to treat tokens like passwords. SECURITY.md provides a vulnerability reporting process and emphasizes not sharing sensitive data. However, there is no explicit statement about least privilege, e.g., whether the CLI requests only the minimum permissions needed. User confirmation: README mentions some operations (e.g., `ft library delete`) move files to Trash, but does not explicitly state whether confirmation is requested before destructive actions. Data flow transparency: README explains data storage locations and network requests (only X API during sync), but does not detail all data flows. Sensitive data handling: README and SECURITY.md provide guidance on handling cookies and tokens, but no code-level verification. Dependency security: package.json lists dependencies, but no security audit or vulnerability scanning evidence. External effects: README mentions `ft install app` downloads and installs an app, but does not state whether user confirmation is requested. Rollback: README mentions `ft library delete` moves files to Trash, but no other rollback mechanisms. Source attribution: README lists the repository family, but no detailed contributor information. Deductions: lack of explicit evidence for least privilege, user confirmation, rollback, and source attribution.
Evidence shows: README and test files demonstrate CLI functionality, tests cover multiple modules, but no complete test results or coverage. Dependency availability: package.json lists dependencies, but no availability guarantees or mirrors. Failure messages: tests do not explicitly show failure message handling, but code may have error handling. Deductions: insufficient evidence for dependency availability and failure messages.
Evidence shows: README describes multiple use cases, including personal bookmark management, knowledge base construction, agent integration, and provides a platform support matrix. Capability boundaries: README lists commands and features, but does not explicitly state unsupported features. Trigger precision: commands and options are clearly described, but no detailed trigger conditions. Environment fit: README provides Windows and macOS notes, but not detailed configuration for all platforms. Deductions: insufficient evidence for capability boundaries and trigger precision.
Evidence shows: README provides clear command documentation, installation instructions, examples, and platform support, with reasonable information architecture. Naming stability: command names and options are consistent in README. Known limitations: README mentions some limitations, such as Windows `ft` alias conflict, but not comprehensive. License: MIT license file exists. Versioning: package.json has a version number, but no changelog. Maintenance responsibility: README provides issue tracking and contribution guidelines, but no explicit maintainers. Deductions: insufficient evidence for known limitations, versioning/changelog, and maintenance responsibility.
Evidence shows: README demonstrates CLI output formats, such as `ft viz` terminal dashboard, but no actual output examples. Marginal value: CLI provides multiple features, but no comparison with other tools. Cost-benefit: CLI is free and open source, but no performance or resource usage data. Deductions: insufficient evidence for output usability, marginal value, and cost-benefit.
Evidence shows: Claims in README are mostly supported by code or tests, but no independent verification. Cross-source corroboration: README mentions repository family, but no verification from other sources. Fact-inference separation: README distinguishes feature descriptions and recommendations, but does not explicitly label inferences. Deductions: insufficient evidence for claim traceability, cross-source corroboration, and fact-inference separation.
- The CLI reads browser session cookies for bookmark sync; users should ensure they use it in a trusted environment and be aware of cookie sensitivity.
- OAuth tokens are stored locally; users should ensure file permissions are correct and avoid leakage.
- `ft install app` downloads and installs an application; users should verify the source is trustworthy.
- The publisher identity is unverified; users should carefully assess trustworthiness.
What does this agent do, and when should you use it?
Field Theory CLI is a local-first command-line tool for X bookmarks and a companion to the Field Theory Mac app. It stores bookmark data as JSONL, builds a SQLite FTS5 index, and provides search, filtering, statistics, visualization, and classification commands. It can export bookmarks to Markdown, compile an interlinked knowledge base, and answer questions against that knowledge base through `ft ask`. The CLI also manages local Library pages under `~/.fieldtheory/library` and portable commands under `~/.fieldtheory/commands`. Claude Code, Codex, and other agents with shell access can use the installed `/fieldtheory` skill to work with this local context.
With ft sync, the CLI reads session cookies from a supported browser's local cookie database when that browser is logged into X, then downloads bookmarks through X's internal GraphQL API. Alternatively, ft auth followed by ft sync --api uses OAuth API sync. It writes raw data to ~/.fieldtheory/bookmarks/bookmarks.jsonl and uses the SQLite FTS5 index in bookmarks.db for BM25-ranked ft search <query> results. ft classify and ft classify-domains classify bookmarks with an LLM; ft md exports per-bookmark Markdown; ft wiki compiles an interlinked knowledge base; and ft lint checks or fixes fixable wiki issues. The ft library commands search, create, SHA-256-protected update, trash, and open Library pages, while ft commands creates, lists, and validates portable commands.
- An X power user wants a daily local bookmark sync and needs
ft searchto retrieve previously saved distributed-systems material. - A researcher wants to export bookmarked material as Markdown and use
ft wikiplusft askto organize it into a searchable knowledge base. - A developer using Claude Code or Codex wants an agent to consult personal bookmarks and the local Field Theory Library while working on a task.
- A Field Theory Mac app user needs to create or safely update Library pages from a terminal, then open them in the packaged app.
- A user maintaining several local repositories wants to use
ft possible, saved bookmark seeds, and a repository set to create opportunity prompts and background jobs.
What are this agent's strengths and limitations?
- The default sync uses a local browser session without requiring an X API, while
ft authandft sync --apiprovide an OAuth route. - Its JSONL cache, SQLite FTS5/BM25 index, and Markdown exports are all stored locally under
~/.fieldtheory. - It covers a concrete bookmark-to-knowledge-base workflow: sync, media completion, classification, wiki compilation, questioning, and linting.
- It installs a
/fieldtheoryskill for Claude Code and Codex and manages portable commands intended for Field Theory and agents.
- Its core source is X bookmarks; default sync depends on a browser logged into X and X's internal GraphQL API.
- Although most bookmark functions are documented across platforms, the product is designed for Mac and its Library-opening and app-install features are tied to the macOS ecosystem.
- Browser support and recovery steps vary by platform; Firefox on Windows requires Node.js 22.5+ or
sqlite3on PATH. - LLM classification is documented, but the available models, pricing, and offline classification option are not specified.
How do you install or deploy this agent?
Node.js 20+ is required. Install with:
npm install -g fieldtheoryFor default session sync, use a supported Chrome-family browser or Firefox that is logged into X, then run:
ft syncFor cross-platform OAuth sync, run:
ft auth
ft sync --apiHow do you use this agent?
Sync and search:
ft sync
ft search "distributed systems"Explore the collection:
ft viz
ft categories
ft statsExport and build a knowledge base:
ft md
ft wiki
ft ask "your question"Check or fix fixable wiki issues:
ft lintTo make the local context available to Claude Code or Codex, run:
ft skill installHow does this agent compare with similar options?
The repository documents two sync paths: default ft sync uses a browser session and X's internal GraphQL API, while ft auth with ft sync --api uses the official v2 OAuth API and is described as cross-platform. The CLI is separate from the Field Theory Mac app, Codex plugin, and release-feed repositories: CLI issues belong here, while app-source and plugin issues belong in their respective projects.
FAQ
Do I need to pay for an X API to sync bookmarks?
ft sync path, which uses a logged-in session from a supported browser. The official API path is configured through ft auth.Does it retain my browser cookies?
~/.fieldtheory/bookmarks/oauth-token.json with owner-only permissions.Can I use it on Windows?
fieldtheory or ft.cmd because ft is already an alias.What can an agent use directly?
ft skill install installs the /fieldtheory skill for Claude Code and Codex. Any agent with shell access can also invoke the CLI against the local data directory.