One‑Command Scan: Reveal All AI Tools, Token Consumption, and Costs on Your Machine

surface is a cross‑platform (macOS, Linux, Windows) Rust CLI that audits AI usage on a local machine. A single command scans installed AI agents, visited AI websites, and quantifies token consumption and monetary cost.

Project Overview

Scanning proceeds in three sequential stages (tools → sites → usage). Results are persisted incrementally in a ledger; pricing is applied at read time, allowing automatic re‑evaluation when price tables change.

Core Capabilities

Detects 18 AI tools via five channels (executables, config directories, installed apps, editor extensions, running processes). Each detection records a FOUND BY list, distinguishing residual configuration from active agents.

Marks tools with an autonomous flag to indicate whether the tool can execute code locally, separating chat‑window agents from shell‑based agents.

Collects browsing records for 30 AI domains across ten browsers; non‑AI history is filtered out at the SQLite query level.

Incremental token accounting for Claude Code, Codex CLI, and OpenCode, storing data as day × tool × model entries and reading only new increments after a cold start.

Cross‑scan deduplication reduces 18,268 raw records to 8,672 unique entries; deduplication keys are persisted in the ledger.

Distinguishes cumulative vs. incremental semantics; for example, Codex’s per‑session totals would otherwise inflate totals by 15× (34,935,584 vs. 2,274,321).

Repository attribution stores only the owner/name slug, never full paths, usernames, or branch names.

Three‑state cost model: known (priced), local (free local models), and unpriced (displayed as ▲ unpriced, not $0.00); ≥ indicates a lower bound.

Six‑view TUI dashboard (Overview, Tools, Sites, Usage, Cost, Projects) supports mouse clicks, scroll wheel, and Vim‑style keys, with day/week/month regrouping.

JSON pipeline output via --json can be piped directly to jq, including a failed_sections field for CI assertions.

Privacy safeguards: no message content is read, browser databases are opened read‑only, no absolute paths are stored, no privilege escalation occurs, and unreadable data is reported explicitly.

Command Reference

surface

– Scan the machine and open the six‑view dashboard. surface --json – Print structured JSON to stdout for piping to jq. surface --offline – Disable network access; use cached price table or built‑in defaults. surface --check – Show parsed paths and settings without scanning. surface --demo – Run in demo mode with mock data; costs are calculated from real price tables. -h / --help – Display help. -V / --version – Show version.

Dashboard Shortcuts

tab / → / l

– Next view. shift‑tab / ← / h – Previous view. 1–6 – Jump to a specific view (out‑of‑range numbers do nothing). j / k / ↓ / ↑ – Move selection. g / G / home / end – Go to first/last line. pageup / pagedown – Scroll ten lines. mouse wheel – Scroll three lines in the active panel. click – Select or focus. enter – Switch focus between panels in split view. d – Toggle token detail rows. u – Toggle Overview chart between cost and token. [ / ] – Move chart cursor one bucket. backspace – Clear chart cursor. w – Regroup chart by day/week/month. ? – Show help overlay. q / esc / ctrl‑c – Quit.

Supported AI Tools

Claude Code – executable detected, token readable.

Claude Desktop – not executable, not token readable.

Codex CLI – executable detected, token readable.

ChatGPT Desktop – not executable, not token readable.

OpenCode – executable detected, token readable.

OpenClaw – executable detected, token not readable.

Cursor – executable detected, token not readable.

Windsurf – executable detected, token not readable.

GitHub Copilot – not executable, not token readable.

Aider – executable detected, token not readable.

Goose – executable detected, token not readable.

Hermes Agent – executable detected, token not readable.

Gemini CLI – executable detected, token not readable.

Amp – executable detected, token not readable.

Cline – executable detected, token not readable.

Continue – executable detected, token not readable.

Ollama – not executable, not token readable.

LM Studio – not executable, not token readable.

Configuration & Environment Variables

Configuration is optional and follows three‑level precedence: environment variables > surface.toml > defaults.

[web]
scan_history = true            # false skips browser history (view shows disabled)
history_lookback_days = 30     # days a domain must have been visited to appear
extra_ai_domains = []           # additional domains, e.g., internal model gateways

[usage]
scan = true                     # false skips transcription scan
window_days = 30                # ledger retains daily totals for this many days

[cost.subscriptions]
# claude_code = 100.0
# codex = 30.0

SURFACE_STATE_DIR

– overrides the state directory (ledger, price cache). SURFACE_CONFIG_DIR – overrides the location of surface.toml. SURFACE_SCAN_HISTORY – set to false to disable browser‑history scanning. SURFACE_HISTORY_LOOKBACK_DAYS – controls the domain look‑back window. SURFACE_SCAN_USAGE – set to false to skip transcription scanning. SURFACE_USAGE_WINDOW_DAYS – token accounting window size.

Usage Examples

# Install (macOS / Linux; installer verifies SHA256, no sudo needed)
curl -fsSL https://raw.githubusercontent.com/holistic-ai/surface/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/holistic-ai/surface/main/install.ps1 | iex

# Cargo (crate name is surface-cli, binary is surface)
cargo install surface-cli

# Scan and open dashboard
surface

# Scan and output JSON for further processing
surface --json | jq '.usage.by_repo'

# Offline scan with CI assertion of no failures
surface --json --offline | jq -e '.failed_sections | length == 0' > /dev/null

# Show parsed paths and settings without scanning
surface --check

# Demo mode with mock data (costs calculated from real price tables)
surface --demo

Privacy & Security Design

Message content is never read; the transcription parser extracts only token counts, model name, and timestamps.

Browser history is filtered at the SQL level; non‑AI entries are never loaded into memory, and AI domains are limited to the domain name.

The ledger stores only owner/name slugs; absolute paths, home directories, usernames, branch names, and origin are never persisted.

All operations are read‑only and run without elevated privileges; browser databases are opened read‑only and immutable, and tool detection never executes external commands.

Blind spots are explicitly reported – unreadable data appears as “unreadable” rather than zero.

Conclusion

surface is a ~2 MB Rust binary that provides local‑first AI footprint auditing: it enumerates installed AI agents, captures AI‑related website visits, accounts token usage per model, and computes cost with three pricing states, all without uploading data, requiring privileges, or leaking personal paths.

Typical use cases include auditing multiple coding agents to determine monthly token consumption, monetary cost, and subscription ROI, as well as generating CI‑compatible JSON reports of AI tools and usage for compliance or budgeting.

References

Project repository: https://github.com/holistic-ai/surface
Model price source: https://github.com/BerriAI/litellm (model_prices_and_context_window.json)