Back to AIWatcher

Getting started with AIWatcher.

One dashboard for AI cost and behavior across your developers’ local AI tools and your product’s AI agents.

Path A

Your Local

Passive collector for Claude Code, Codex, Cursor, Ollama, Aider, and Continue.dev. Zero code changes.

Jump to setup
Path B

Your Apps

One-line SDK wrapper for your product's AI calls. Python and JavaScript supported.

Jump to setup

Use one or both.

Before you start

  1. 1Sign in at ai-watcher-pi.vercel.app
  2. 2For Your Local: no app needed — the collector uses a shared org key
  3. 3For Your Apps: go to Your Apps → New App and copy your API key

Path A

Path A — Your Local (zero code changes)

Reads session files written by local AI tools on any developer machine. Supports Claude Code, Claude Desktop, Codex CLI, Ollama, Cursor, Aider, and Continue.dev.

Requirements: Python 3.9+, Mac or Linux

1

Install

bash
git clone https://github.com/Kmaralla/ai-watcher.git
cd ai-watcher/collector

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
2

Run

bash
export AIWATCHER_API_KEY=aw_live_...
export AIWATCHER_API_URL=https://ai-watcher-pi.vercel.app

python3 main.py

The collector runs in the foreground and polls every 30 seconds. Sessions appear in Your Local → Sessions within one polling cycle.

3

What it reads

ToolSource path
Claude Code~/.claude/telemetry/ and ~/.claude/projects/
Claude Desktop~/Library/Application Support/Claude/local-agent-mode-sessions/
Codex CLI~/.codex/state_5.sqlite
Ollamahttp://localhost:11434 (local API)
Cursor~/Library/Application Support/Cursor/logs/
Aider~/.aider/
Continue.dev~/.continue/logs/

The collector never sends prompt content — only session metadata, token counts, model names, and timing.

Path B

Path B — Your Apps (SDK)

Wraps your product’s AI calls and sends telemetry to AIWatcher. Each wrapped call creates a session in Your Apps with cost, token counts, and a full event timeline.

Pick your stack

Works with any Python backend: FastAPI, Flask, Django, AWS Lambda, scripts, or any other runtime.

Install

bash
# Local install (PyPI publish coming soon)
pip install -e /path/to/ai-watcher/sdk

Environment variables

bash
export AIWATCHER_API_KEY=aw_live_...
export AIWATCHER_API_URL=https://ai-watcher-pi.vercel.app

Single AI call

python
from ai_watcher import track_llm

result = track_llm(
    'classify-document',                          # action name
    lambda: openai.chat.completions.create(       # your existing call
        model='gpt-4o',
        messages=[{'role': 'user', 'content': doc_text}]
    ),
    {
        'human_id': current_user.email,           # who triggered this
        'agent_name': 'doc-classifier',           # your agent name
        'model': 'gpt-4o',                        # model being called
        'session_name': 'Classify: invoice',      # shown in dashboard
        'input': {'doc_type': 'invoice'}          # metadata, no PII
    }
)
# result is unchanged — track_llm returns exactly what your fn returns

Chained calls (one session, multiple model calls)

python
from ai_watcher import track_chain

results = track_chain(
    steps=[
        {
            'action': 'extract',
            'model': 'gpt-4o',
            'input': {'pages': 3},
            'fn': lambda: openai.chat.completions.create(...)
        },
        {
            'action': 'classify',
            'model': 'claude-sonnet-4-20250514',
            'input': {'text_preview': preview[:100]},
            'fn': lambda: anthropic.messages.create(...)
        }
    ],
    opts={
        'human_id': customer_id,
        'agent_name': 'shipping-pipeline',
        'session_name': 'Process Shipping Document',
        'framework': 'python'
    }
)
# results is a list matching the order of steps

AWS Lambda

Same pattern. Add env vars to your Lambda configuration:

text
AIWATCHER_API_KEY  = aw_live_...
AIWATCHER_API_URL  = https://ai-watcher-pi.vercel.app
python
from ai_watcher import track_llm

def handler(event, context):
    return track_llm(
        'classify-document',
        lambda: openai.chat.completions.create(
            model='gpt-4o',
            messages=[{'role': 'user', 'content': event['text']}]
        ),
        {
            'human_id': event.get('customer_id', 'unknown'),
            'agent_name': 'doc-classifier',
            'model': 'gpt-4o',
            'framework': 'aws-lambda',
            'session_name': f"Classify: {event.get('doc_type', 'document')}",
            'input': {'doc_type': event.get('doc_type')}
        }
    )

track_llm uses only the Python standard library (urllib). No extra dependencies are added to your Lambda bundle.

Verify it's working

After your first instrumented call, open the dashboard:

  • Your Local → Sessions — appears within 30 seconds of collector start
  • Your Apps → [your app] → Sessions — appears within seconds of first call

Each session shows the human ID, session name, model and token counts, estimated cost, and a full event timeline with input metadata.

What is and isn't captured

Captured

  • Session metadata: human_id, agent_name, framework, model
  • Token counts per call
  • Estimated cost at current rates
  • Latency per call
  • Input metadata you pass
  • Output summary you pass

Not captured

  • Raw prompt text (unless explicitly passed)
  • Raw model output (unless explicitly passed)
  • Anything from your database or user records

Supported models and cost rates

ModelProviderPricing (per 1M tokens in / out)
claude-sonnet-4-20250514Anthropic$3.00 / $15.00
claude-haiku-4-5-20251001Anthropic$0.80 / $4.00
claude-opus-4-20250514Anthropic$5.00 / $25.00
gpt-4oOpenAI$2.50 / $10.00
gpt-4o-miniOpenAI$0.15 / $0.60
llama3 via OllamaLocal$0

Codex CLI and Claude Code sessions are subscription-billed. Token usage is shown in the dashboard but no dollar cost is applied. Configure this under Settings → AI Provider Billing.

Questions

Contact the team directly:

Get on the early access list.

We’re working with a small number of design partners in 2026.

We reply within 48 hours.