Docs/Getting Started/Local Proxy

Local Proxy

Automatically track AI usage from Claude Code, Cursor, and Kiro — no code changes needed.

How it works

The CostLens proxy runs on your machine and intercepts LLM API calls. It extracts metadata (model, tokens, cost, git branch) and sends it to CostLens. Your prompts and responses never leave your machine.

Your AI tool → localhost:19456 → provider API

Metadata only → costlens.dev (tokens, cost, branch)

1. Install

brew tap costlens-dev/tap
brew install costlens

2. Run setup

This prompts for your API key and auto-configures your shell (zsh/bash/fish).

costlens setup

Get your API key from Settings → API Keys.

3. Start the proxy

source ~/.zshrc   # or restart your terminal
costlens start

The proxy runs on localhost:19456. Your AI tools will automatically route through it.

Supported tools

Claude CodeWorks via ANTHROPIC_BASE_URL

Cursor (own API key)Works via OPENAI_BASE_URL

KiroWorks via ANTHROPIC_BASE_URL

Cursor Pro / CopilotUse GitHub-only mode instead

Platform install

macOS (Homebrew)

brew tap costlens-dev/tap
brew install costlens

macOS (direct download)

curl -L https://github.com/Costlens-dev/prompt-craft/releases/latest/download/costlens_darwin_arm64.tar.gz | tar xz
sudo mv costlens /usr/local/bin/

Linux

curl -L https://github.com/Costlens-dev/prompt-craft/releases/latest/download/costlens_linux_amd64.tar.gz | tar xz
sudo mv costlens /usr/local/bin/

Windows (PowerShell)

Invoke-WebRequest -Uri "https://github.com/Costlens-dev/prompt-craft/releases/latest/download/costlens_windows_amd64.tar.gz" -OutFile costlens.tar.gz
tar -xzf costlens.tar.gz
Move-Item costlens.exe $env:USERPROFILE\bin\

Ensure %USERPROFILE%\bin is in your PATH.

Privacy

Sent to CostLens: model name, token counts, cost, git branch, repo, tool name, timestamp.

Never sent: prompt content, response content, API keys, source code.

All processing happens locally. The proxy only sends numerical metadata upstream.

How AI detection works

CostLens correlates your LLM usage with your git activity to determine which commits were AI-assisted. We use a multi-signal confidence scoring model:

Time proximityLLM call close to commit = higher confidence

Content overlapFiles in prompt match files in commit

Velocity anomalyUnusually large commit vs your baseline

Session densityMore LLM calls before commit = higher confidence

A confidence score ≥ 0.6 marks the commit as AI-assisted. This data feeds into your AI ROI reports.

GitHub App

The proxy tracks LLM usage. The GitHub App tracks commits, PRs, and reviews automatically via webhooks. Together, they produce your AI ROI report.

Go to Settings → GitHub to install the App on your org.

What happens next

1. The proxy silently tracks your AI usage as you code.

2. GitHub webhooks capture your commits and PRs.

3. CostLens matches them using confidence scoring.

4. After 7 days, your first AI ROI report is generated.

← Introduction

SDK Quick Start →