# ffctk — FF AI Coding Tools Usage Tracker

Captures usage events from Claude Code and Codex CLI JSONL logs and uploads them
to FF AI Workspace. Zero-config aside from a personal access token.

> 📖 Module docs: `docs/modules/it-operations/ai-usage/`
> 🔒 Privacy: ffctk uploads token counts + metadata only. **Never** message content,
> prompts, tool results, or code.

---

## Install (Linux / macOS)

```bash
curl -fsSL https://ffai.faradayfuture.com/install.sh | bash
ffctk login ffai_xxxxxxxxxxxxxx
ffctk start
```

## Install (Windows PowerShell)

```powershell
iwr -useb https://ffai.faradayfuture.com/install.ps1 | iex
ffctk login ffai_xxxxxxxxxxxxxx
ffctk start
```

> Generate a token at FF AI Workspace → `/ai-usage/me/tokens`.

---

## Commands

```
ffctk login <token>     Save token to ~/.config/ffctk/credentials (0600)
ffctk start             Watch JSONL + upload to server (foreground daemon)
ffctk flush             One-shot upload of queued events
ffctk status            Show queue depth, device id, pricing version
ffctk logout            Remove credentials
```

---

## Files

```
~/.config/ffctk/
  credentials       0600 — personal access token (plaintext, never sync to git)
  config.json       agent config (api base, batch size, etc.)
  device_id         this machine's UUID
~/.cache/ffctk/
  offsets.json      JSONL byte offsets (resume after restart)
  queue.db          SQLite buffer (≤100MB)
  pricing.json      Cost estimation pricing table (refreshed daily)
  ffctk.log         stdout/stderr if run as service
```

---

## Build from source

```bash
cd tools/ffctk
npm install
npm run build              # → dist/cli.js
npm run pkg                # → dist-bin/ffctk-{linux,macos,win}-{x64,arm64}
```

Cross-platform single binaries via `@yao-pkg/pkg`. macOS unsigned; install.sh
strips `com.apple.quarantine` xattr. Windows unsigned; install.ps1 runs
`Unblock-File`. Internal-tool tradeoff documented in PRD § 1.

---

## Service install (auto-start on boot)

| Platform | Command |
|----------|---------|
| Linux (systemd user) | `ffctk install-service` *(not yet implemented, Phase 1.5)* |
| macOS (launchd) | same |
| Windows (Service) | same |

For MVP, run `ffctk start` in tmux / screen / a terminal that stays open.