modelstat 0.0.6 → 0.0.10

package/README.md

@@ -1,59 +1,96 @@
-# @modelstat/agent
+# modelstat
 
-> Local companion for [modelstat](https://github.com/0xflair/modelstat). Reads
-> your AI coding tools' JSONL/SQLite logs (Claude Code, Codex, Cursor,
-> Gemini, Aider, …), tokenises events on-device, and uploads them to the
-> modelstat backend.
+> **See every AI token your team spends.** Local companion for [modelstat](https://modelstat.ai) — reads the session logs your AI coding tools already write (Claude Code, Codex, Cursor, Cline, Continue, Aider, Windsurf, Zed, Copilot, Claude Desktop), tokenises events on-device, and uploads only metadata to your modelstat dashboard.
 
-**Your prompts never leave your machine.** The agent only uploads
-tokenised metadata (token counts, model ids, git remote, tool call
-counts, redacted summaries). See the
-[source](https://github.com/0xflair/modelstat/tree/main/apps/agent-dev)
-— discovery and redaction live in
-[`@modelstat/parsers`](https://github.com/0xflair/modelstat/tree/main/packages/parsers).
+**Your prompts never leave your machine.** The agent uploads only token counts, model ids, timestamps, and a provider-assigned session id. Source is auditable on [GitHub](https://github.com/modelstat/modelstat/tree/main/apps/agent-dev).
 
 ## Install
 
+The fastest way:
+
+```bash
+curl -fsSL https://install.modelstat.ai | sh
+```
+
+Or via Homebrew:
+
 ```bash
-# npm
-npm install -g @modelstat/agent
+brew install modelstat/tap/modelstat
+modelstat connect
+```
 
-# pnpm
-pnpm add -g @modelstat/agent
+Or via npm / pnpm / bun:
 
-# bun
-bun install -g @modelstat/agent
+```bash
+npm install -g @modelstat/agent && modelstat connect
+pnpm add -g @modelstat/agent && modelstat connect
+bun add -g @modelstat/agent && modelstat connect
 ```
 
-Requires Node 20+.
+`modelstat connect` installs a **launchd user agent** on macOS (at `~/Library/LaunchAgents/ai.modelstat.agent.plist`) or a **systemd user unit** on Linux (at `~/.config/systemd/user/modelstat.service`). The daemon starts automatically on login.
+
+Requires Node 20+ (or skip Node entirely with the Homebrew route). macOS and Linux (x86_64, arm64) supported.
 
-## Connect
+## Commands
 
 ```bash
-# 1. Pair with your modelstat account (OAuth device-code)
-modelstat connect
+modelstat connect              # pair + install background service, then exit
+modelstat status               # show pairing + service state
+modelstat paths [--json]       # print state file + log paths + API URL
+modelstat stop                 # stop and uninstall the service
+modelstat scan                 # one-shot parse + upload of local JSONL
+modelstat watch                # foreground watcher (no service install)
+modelstat discover             # report detected tool installs + identities
+```
+
+**Programmatic pairing** (used by harness skills for OpenClaw, NanoClaw, etc.):
 
-# It prints a 6-char code; enter it at the URL it opens in your browser.
+```bash
+modelstat connect --json --no-browser
+```
+
+Emits one NDJSON event per line. Schema documented at [integrations/harness-skills/modelstat-connect/README.md](https://github.com/modelstat/modelstat/tree/main/integrations/harness-skills/modelstat-connect).
 
-# 2. Report detected tool installs + identities
-modelstat discover
+## Shared state across install methods
 
-# 3. One-shot backfill of all local JSONL
-modelstat scan
+Installing via both Homebrew and npm on the same laptop produces the **same binary reading the same state file** — on macOS that's `~/Library/Preferences/modelstat-agent-dev-nodejs/config.json`. Your device UUID, bearer token, and pairing state persist across install methods. No duplicate devices on the server side either — the API upserts on `(user_id, machine_id)`.
 
-# 4. Continuous watcher (chokidar + periodic backstop)
-modelstat watch
+## MCP server
+
+Pair the agent, then install [`@modelstat/mcp`](https://www.npmjs.com/package/@modelstat/mcp) to query your own spend from inside Claude Desktop, Cursor, Cline, Continue, or Zed:
+
+```bash
+# Claude Code
+claude mcp add modelstat -- npx -y @modelstat/mcp
 ```
 
+Full wire-up docs per client: https://modelstat.ai/mcp
+
 ## Self-host
 
-If you're pointing at your own modelstat API (not the hosted SaaS):
+To point the agent at your own modelstat API (not the hosted SaaS):
 
 ```bash
 export AGENT_API_URL=https://your-modelstat-api.example.com
 modelstat connect
 ```
 
+`AGENT_API_URL` can also be set persistently via `.env` or in the systemd/launchd unit.
+
+## Privacy
+
+- Agent reads local session logs written by the tools you use. Nothing is intercepted — the tools already write these files.
+- Upload payload: token counts, model name, timestamps, provider-assigned session id, git remote URL (redactable), redacted work-type summary.
+- Never uploaded: prompt text, model responses, file contents, tool-call arguments, environment variables, SSH keys, secrets.
+- Redaction is on-device via [`@modelstat/parsers`](https://github.com/modelstat/modelstat/tree/main/packages/parsers).
+- Offline mode: buffered locally, uploaded when network returns. `modelstat scan --dry-run` for local-only analytics.
+
+## Pricing
+
+- **Free**: 100M tokens/month, 1 device, no card.
+- **Team**: $5/seat/month with 250M pooled tokens; overage at $25/billion.
+- **Enterprise**: SSO/SCIM, on-prem ingest, SLAs — contact `hello@modelstat.ai`.
+
 ## License
 
-Apache-2.0 — the code that reads files on your machine must be auditable.
+Apache-2.0. Source at https://github.com/modelstat/modelstat/tree/main/apps/agent-dev.