Getting Started

Quick Start

One command sets everything up:

npx @getverbal/cli init

Init opens your browser to sign in, detects which AI tools you have installed, and injects the Verbal MCP server into each one. When it finishes you'll see:

Done! Dashboard → https://www.getverbal.ai/dashboard

What Init Does

1. Authenticates — opens your browser for sign-in, then stores credentials at ~/.config/getverbal/credentials.json with restricted file permissions (mode 0600).
2. Detects AI tools — scans for Claude Code, Claude Desktop, Cursor, and Codex in parallel by checking their known config file paths.
3. Configures MCP — injects a mcpServers.verbal entry into each detected tool's config. Existing config is preserved; only the verbal key is written.
4. Verifies — sends a test event to confirm the connection before exiting.

Supported Tools

Billing type: API tools report token counts; Verbal calculates cost from model pricing. Subscription tools track cost as $0 per event — subscription spend is tracked separately.

Note: For Claude Code, init writes .mcp.json to the current working directory. Consider adding it to .gitignore if it contains your API key.

What Gets Tracked Automatically

• Token counts (input, output, cache read / cache write)
• Cost — auto-calculated from tokens and model pricing
• Model and provider
• Git context (repo, branch, commit)
• Prompt content (with built-in secret / PII redaction)

Capture mode defaults to full. Set VERBAL_CAPTURE_MODE=usage in your MCP env block to track only tokens and cost without capturing prompt text.

Enhanced Tracking for Claude Code

The MCP server provides baseline tracking. For Claude Code specifically, hooks add richer data using provider-reported token counts from the session transcript.

getverbal hooks install --claude

Three hooks are installed:

• Stop hook — after each response, incrementally ingests transcript entries with accurate provider-reported token counts.
• Session end hook — catches entries missed by the stop hook when the session terminates.
• Session review prompt — after 25 minutes of active work, prompts you to rate session usefulness. Feeds ROI metrics in the dashboard.

Hooks read config from the .mcp.json created by init. No additional configuration needed.

Codex Watcher

For Codex (OpenAI CLI), a file watcher replays session logs as events:

getverbal hooks watch --codex

To auto-start on macOS:

getverbal hooks install --codex
launchctl load ~/Library/LaunchAgents/ai.verbal.codex-hooks.plist

Agent Instructions (AGENTS.md / CLAUDE.md)

The MCP server exposes tools your AI agent can call proactively. Add the following block to your project's AGENTS.md or CLAUDE.md so the agent uses them automatically:

## AI Spend Tracking

This project uses Verbal for AI spend tracking. The Verbal MCP server
is configured and provides these tools:

- optimize_prompt — Score and improve a prompt before complex tasks.
  Call this before any multi-step or underspecified request.
- get_usage_summary — Show aggregated spend by provider, model, or project.
- get_cost_breakdown — Analyze spending trends with breakdowns.
- submit_session_review — Rate the session when wrapping up.
  Include usefulness (1-5), effectiveness (1-5), and time saved.
- get_budget_status — Check budget alerts before expensive operations.

At the end of each session, submit a session review to help track ROI.

This is especially useful for Cursor and Claude Desktop where hooks are not available — the agent instructions prompt the model to call Verbal tools directly.

Configuration

All variables go in the env block of the mcpServers.verbal entry written by init.

Redaction

When VERBAL_CAPTURE_MODE=full, prompt text is auto-redacted before transmission. Built-in patterns strip:

• API keys (OpenAI, GitHub, AWS, Google, Slack)
• Bearer tokens and JWTs
• PEM private keys
• Email addresses, phone numbers, SSNs, credit card numbers

Add custom patterns with VERBAL_REDACTION_PATTERNS (comma-separated regexes).

Disable built-in patterns with VERBAL_REDACTION_DISABLE_DEFAULT=true.

Import History

Claude Export

1. Go to claude.ai → Settings → Export Data
2. Download the export JSON file
3. In Verbal, go to Manage → Import
4. Upload the JSON — conversations are processed and deduped automatically

Files under 10 MB process immediately. Larger files are queued in the background.

ChatGPT Export

1. Go to chatgpt.com → Settings → Data Controls → Export
2. OpenAI emails you a download link (usually within a few minutes)
3. Upload via API: POST /api/v1/import/chatgpt with your conversations.json

See the API Reference for request format. Re-importing is safe — deduplication prevents double-counting.

Browser Extension

The extension tracks usage from web AI interfaces — ChatGPT, Claude.ai, Gemini, Perplexity, Microsoft Copilot, and others — without API access.

Currently in development. Join the waitlist to be notified when it launches.

CLI Commands

API Keys

npx @getverbal/cli init generates and stores your API key automatically. For additional keys:

• Generate from Manage → Settings → API Keys
• Keys are scoped to your organization
• Rotate or revoke any key at any time
• Pass keys in the x-api-key header on API requests