Field Theory CLI — X/Twitter Bookmark Manager

Skill by ara.so — Daily 2026 Skills collection.

Field Theory CLI (ft) syncs all your X/Twitter bookmarks locally, indexes them for full-text search, classifies them by category and domain, and exposes them to AI agents via shell commands. No official API required for the default sync mode.

Installation

npm install -g fieldtheory

Requirements:

• Node.js 20+

• Google Chrome (logged into X/Twitter) for default sync mode

• macOS for Chrome session sync; Linux/Windows use OAuth mode

Verify installation:

ft --version

ft status

Quick Start

# Sync bookmarks (reads Chrome session automatically)

ft sync

# Search immediately

ft search "machine learning"

# Explore with terminal dashboard

ft viz

Data is stored at ~/.ft-bookmarks/ by default.

Core Commands

Syncing

# Incremental sync (new bookmarks only)

ft sync

# Sync then auto-classify with LLM

ft sync --classify

# Full history crawl from the beginning

ft sync --full

# Sync via OAuth API (cross-platform, no Chrome needed)

ft sync --api

# Show sync status

ft status

Searching

# Full-text BM25 search

ft search "distributed systems"

ft search "rust async runtime"

ft search "cancer immunotherapy"

# Filter results

ft list --author elonmusk

ft list --category tool

ft list --domain ai

ft list --since 2024-01-01

ft list --category research --domain biology

# Show a single bookmark by ID

ft show 1234567890

Classification

# LLM-powered classification (requires LLM access)

ft classify

# Regex-based classification (no LLM needed, faster)

ft classify --regex

# Rebuild search index (preserves existing classifications)

ft index

Exploration & Stats

# Terminal dashboard with sparklines and charts

ft viz

# Category distribution

ft categories

# Subject domain distribution

ft domains

# Top authors, languages, date range

ft stats

# Print data directory path

ft path

Media

# Download static images from bookmarks

ft fetch-media

OAuth Setup (Cross-Platform / API Mode)

# Interactive OAuth setup

ft auth

# Then sync via API

ft sync --api

OAuth token stored at ~/.ft-bookmarks/oauth-token.json with chmod 600.

Configuration

Custom Data Directory

# Set in shell profile (~/.zshrc or ~/.bashrc)

export FT_DATA_DIR=/path/to/custom/dir

# Or per-command

FT_DATA_DIR=/Volumes/external/bookmarks ft sync

Data File Layout

~/.ft-bookmarks/

  bookmarks.jsonl       # raw bookmarks, one JSON object per line

  bookmarks.db          # SQLite FTS5 search index

  bookmarks-meta.json   # sync cursor and metadata

  oauth-token.json      # OAuth credentials (API mode only)

Scheduling Sync

Add to crontab (crontab -e):

# Sync every morning at 7am

0 7 * * * ft sync

# Sync and classify every morning at 7am

0 7 * * * ft sync --classify

# Full sync every Sunday at midnight

0 0 * * 0 ft sync --full

Categories Reference

Category

Description

tool

GitHub repos, CLI tools, npm packages, open-source

security

CVEs, vulnerabilities, exploits, supply chain

technique

Tutorials, demos, code patterns, how-to threads

launch

Product launches, announcements, "just shipped"

research

ArXiv papers, studies, academic findings

opinion

Takes, analysis, commentary, threads

commerce

Products, shopping, physical goods

Working with Bookmark Data (TypeScript/Node.js)

The bookmarks.jsonl file can be consumed directly in scripts:

import { createReadStream } from "fs";

import { createInterface } from "readline";

import { homedir } from "os";

import { join } from "path";

interface Bookmark {

  id: string;

  text: string;

  author: string;

  created_at: string;

  url: string;

  category?: string;

  domain?: string;

  media?: string[];

}

async function loadBookmarks(): Promise<Bookmark[]> {

  const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");

  const filePath = join(dataDir, "bookmarks.jsonl");

  const bookmarks: Bookmark[] = [];

  const rl = createInterface({

    input: createReadStream(filePath),

    crlfDelay: Infinity,

  });

  for await (const line of rl) {

    if (line.trim()) {

      bookmarks.push(JSON.parse(line));

    }

  }

  return bookmarks;

}

// Usage

const bookmarks = await loadBookmarks();

const tools = bookmarks.filter((b) => b.category === "tool");

console.log(`Found ${tools.length} tool bookmarks`);

Query SQLite Index Directly

import Database from "better-sqlite3";

import { join } from "path";

import { homedir } from "os";

const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");

const db = new Database(join(dataDir, "bookmarks.db"), { readonly: true });

// Full-text search using SQLite FTS5

function searchBookmarks(query: string, limit = 20) {

  const stmt = db.prepare(`

    SELECT id, text, author, created_at, category, domain

    FROM bookmarks

    WHERE bookmarks MATCH ?

    ORDER BY rank

    LIMIT ?

  `);

  return stmt.all(query, limit);

}

// Filter by category

function getByCategory(category: string) {

  const stmt = db.prepare(`

    SELECT * FROM bookmarks WHERE category = ? ORDER BY created_at DESC

  `);

  return stmt.all(category);

}

const results = searchBookmarks("transformer architecture");

console.log(results);

Shell Integration in Agent Scripts

import { execSync } from "child_process";

// Run ft commands from Node.js

function ftSearch(query: string): string {

  return execSync(`ft search "${query}"`, { encoding: "utf8" });

}

function ftList(options: { category?: string; since?: string; author?: string }) {

  const flags = [

    options.category ? `--category ${options.category}` : "",

    options.since ? `--since ${options.since}` : "",

    options.author ? `--author ${options.author}` : "",

  ]

    .filter(Boolean)

    .join(" ");

  return execSync(`ft list ${flags}`, { encoding: "utf8" });

}

// Example: find AI memory tools bookmarked this year

const memoryTools = ftSearch("AI memory");

const recentTools = ftList({ category: "tool", since: "2025-01-01" });

Agent Integration Patterns

Tell your AI agent to use ft directly in natural language:

"Search my bookmarks for distributed tracing tools and summarize the top 5."

"Sync any new X bookmarks, then list all research papers from 2025."

"Find everything I've bookmarked about Rust and categorize it by subtopic."

"Every morning, run ft sync --classify to keep my bookmarks up to date."

Claude Code example prompt:

Use the `ft` CLI to search my bookmarks for "vector database"

and pick the best open-source option to add to this project.

Run: ft search "vector database" --category tool

Troubleshooting

Chrome session not found

# Ensure Chrome is open and logged into X

# Then retry

ft sync

# If Chrome session still fails, use OAuth mode

ft auth

ft sync --api

Sync stalls or returns 0 bookmarks

# Check sync status and metadata

ft status

# Force full re-crawl

ft sync --full

# Check data directory permissions

ls -la ~/.ft-bookmarks/

Search returns no results

# Rebuild the search index

ft index

# Verify bookmarks exist

ft stats

wc -l ~/.ft-bookmarks/bookmarks.jsonl

Classification not running

# LLM classify requires an LLM — use regex fallback

ft classify --regex

# Or sync with regex classify

ft sync --classify --regex

Reset all data

rm -rf ~/.ft-bookmarks

ft sync

Custom data directory issues

# Confirm the env var is set

echo $FT_DATA_DIR

ft path

# Ensure directory is writable

mkdir -p "$FT_DATA_DIR"

chmod 755 "$FT_DATA_DIR"

Security Notes

• All data is local only — no telemetry or external calls except to X during sync

• Chrome cookies are read temporarily for sync and never stored separately

• OAuth token is stored chmod 600 — treat it like a password

• Default sync uses X's internal GraphQL API (same as browser); --api uses official v2 API

Platform Support

Feature

macOS

Linux

Windows

ft sync (Chrome session)

✅

❌

❌

ft sync --api (OAuth)

✅

✅

✅

Search, classify, viz

✅

✅

✅

Linux/Windows users must run ft auth first, then use ft sync --api.

Resources

• Homepage: fieldtheory.dev/cli

• Repository: github.com/afar1/fieldtheory-cli

• License: MIT