ctx — Smart Context & Cost Tracker for AI Coding

Every token you send costs money. Most of them are wasted.

Developers routinely dump entire files or entire repos into AI prompts — paying for context the model never needed. There is no feedback on what was useful, no visibility into what it cost, and no way to improve over time.

ctx is an AI coding CLI that solves this. It scans your codebase, scores and selects only the files relevant to your prompt, shows the estimated cost before sending, and tracks every request to a local database. Context selection for LLMs, done deterministically, with full cost transparency.

Everything runs locally. No embeddings. No external indexing services. Only the selected context is sent to your chosen AI provider.

cd your-project
ctx ask "explain the OAuth callback flow in src/lib/auth.ts" --explain

✔ 12 files selected (8,204 tokens)

File Selection Reasoning:
──────────────────────────────────────────────────────────────────────
  File                                       kw  rec  prox  type   tot
──────────────────────────────────────────────────────────────────────
  ✔ src/lib/auth.ts                          35    8     0    10    53
  ✔ src/app/api/auth/[...nextauth]/route.ts  30    8     0    10    48
  ✔ src/middleware.ts                         15    8     0    10    33
  ✔ src/app/login/page.tsx                   15    8     0    10    33
  ...
──────────────────────────────────────────────────────────────────────

Estimated Cost: $0.07  (claude-sonnet-4)

No manual file selection. No guessing what to include. No surprise bills.

---

Why ctx?

	Copy-paste	Claude CLI / Cursor	ctx
Context selection	Manual	Whole repo or manual	Auto-scored by relevance
Token optimization	None	Varies	Deterministic, budget-aware
AI cost tracking	None	None	Per-request + per-project
Cost confirmation	No	No	Estimate shown before sending
Prompt feedback	No	No	Scores quality 0–10
Multi-provider	No	Single provider	Claude + Qwen
Works on any repo	Depends	IDE-specific	Any directory

---

Why Not Just Use Claude CLI?

Claude CLI is a good tool. ctx is not a replacement — it serves a different purpose.

Claude CLI sends your entire codebase (or large parts of it) as context. This works, but you have limited visibility into how many tokens are consumed, what it costs per request, or which files actually contributed to the response.

ctx takes a different approach: deterministic file selection based on keyword relevance, git recency, and file type scoring. You see exactly which files are included, the estimated cost before the request is sent, and actual cost logged afterward. Over many requests across multiple projects, the savings and visibility compound.

If you need an interactive coding agent, use Claude CLI. If you need token-efficient Q&A with cost tracking, ctx is built for that.

---

Real-World Impact

A typical Next.js project (~80 files, 45K total tokens if you include everything):

Approach	Tokens sent	Estimated cost (Sonnet)
Dump entire src/	~45,000	$0.18
Manual file selection	~15,000	$0.08
ctx auto-select	~9,000	$0.06
ctx diff	~500–2,000	$0.005–0.01

Over 50 requests/week, that compounds. And you never have to think about which files to include — ctx handles token optimization automatically.

---

Install

git clone https://github.com/Winter279/claude-ctx.git
cd claude-ctx
npm install && npm run build
npm link   # makes `ctx` available globally

Setup

Set your API key once — works across all projects:

ctx config set DASHSCOPE_API_KEY sk-your-key    # Qwen
ctx config set ANTHROPIC_API_KEY sk-ant-your-key # Claude

That's it. Keys are stored in ~/.config/claude-ctx/.env and loaded automatically.

Quick Start

cd /path/to/any-project

# Ask about code — ctx picks the right files automatically
ctx ask "explain the OAuth authentication flow"

# Preview file selection + cost estimate without calling the API
ctx ask "how does auth work" --dry-run --explain

# Use a specific model, skip cost confirmation
ctx ask "refactor the login handler" -m qwen3-coder-plus -y

# Compare original vs improved prompt before sending
ctx ask "fix auth" --compare --dry-run

# Send only git diff as context (cheapest mode)
ctx diff "review my changes" --dry-run --explain
ctx diff "generate a commit message" -y
ctx diff "review staged changes" --staged
ctx diff "review feature branch" --branch main

# Check your spending
ctx stats
ctx stats --range 7d --project my-app

---

Typical Workflow

1. cd into your project
2. ctx ask "your question" --dry-run --explain
   → See which files get selected + estimated cost
3. Refine prompt if needed (add file paths, narrow scope)
4. ctx ask "your refined question" -y
   → Get streamed response with actual cost summary
5. ctx stats
   → Track spending over time

---

Commands

Command	Description
ctx ask "<prompt>"	Send prompt with auto-selected context
ctx ask "<prompt>" --dry-run	Preview files + cost estimate only
ctx ask "<prompt>" --explain	Show file selection scoring table
ctx ask "<prompt>" -m <model>	Use specific model
ctx ask "<prompt>" -p <provider>	Force provider: anthropic or qwen
ctx ask "<prompt>" -y	Skip cost confirmation
ctx ask "<prompt>" --files src/api/**	Boost files near these directories
ctx ask "<prompt>" --max-tokens <n>	Set max output tokens
ctx stats	Show today's usage and cost
ctx stats --range 7d	Last 7 days (7d, 30d, all)
ctx stats --project <name>	Filter by project name
ctx stats --top-files	Show most frequently included context files
ctx ask "<prompt>" --compare	Compare original vs improved prompt before sending
ctx diff "<prompt>"	Send git diff as context (cheapest mode)
ctx diff "<prompt>" --staged	Only staged changes
ctx diff "<prompt>" --branch <base>	Diff against a base branch
ctx diff "<prompt>" --dry-run	Preview cost without sending
ctx diff "<prompt>" --explain	Show list of changed files
ctx follow "<prompt>"	Start multi-turn conversation with cached context
ctx follow "<prompt>" -y	Skip cost confirmation on first turn
ctx config set <key> <value>	Set global config key (API keys, etc.)
ctx config get <key>	Show a global config key
ctx config list	List all global config keys (masked)
ctx dashboard	Open local web dashboard for usage analytics
ctx dashboard --port <n>	Use custom port (default: 3847)
ctx init	Create .claude-ctx.json config in current dir

---

How It Works

  ctx ask "explain auth flow in src/lib/auth.ts"
                    │
                    ▼
  ┌─────────────────────────────────┐
  │ 1. SCAN REPO                    │
  │    Walk files, skip .gitignore  │
  │    + .ctxignore + hard ignores  │
  │    (node_modules, .git, locks)  │
  │    Skip files > 50KB            │
  └────────────┬────────────────────┘
               ▼
  ┌─────────────────────────────────┐
  │ 2. SCORE & RANK FILES           │
  │    4 scoring dimensions:        │
  │    • keyword: path +15,         │
  │              content +5         │
  │    • recency: git log → +8     │
  │    • proximity: --files → +10  │
  │    • type: .ts=10, .json=5     │
  │    Top 20 files selected        │
  └────────────┬────────────────────┘
               ▼
  ┌─────────────────────────────────┐
  │ 3. BUILD CONTEXT                │
  │    Assemble file contents       │
  │    Truncate oversized files     │
  │    (head 60% + tail 30%)        │
  │    Stay within token budget     │
  └────────────┬────────────────────┘
               ▼
  ┌─────────────────────────────────┐
  │ 4. ESTIMATE COST & CONFIRM      │
  │    Show price before sending    │
  │    (skip with -y or --dry-run)  │
  └────────────┬────────────────────┘
               ▼
  ┌─────────────────────────────────┐
  │ 5. STREAM RESPONSE              │
  │    Send to Claude or Qwen       │
  │    Stream output to terminal    │
  │    Auto-retry on 429/5xx        │
  └────────────┬────────────────────┘
               ▼
  ┌─────────────────────────────────┐
  │ 6. LOG USAGE                    │
  │    Actual cost → SQLite         │
  │    Estimated vs actual tracked  │
  │    Per-project, per-model       │
  └─────────────────────────────────┘

Two-level file scanning keeps context selection fast: keywords are matched against file paths first (instant), then against file contents only for high-value candidates under 50KB. No embeddings, no vector databases, no external services. Fully deterministic.

---

Prompt Comparison (--compare)

Vague prompts waste tokens. Use --compare to auto-improve your prompt and choose which version to send:

$ ctx ask "fix auth" --compare --dry-run

──────────────────────────────────────────────────
  Prompt Comparison
──────────────────────────────────────────────────

  Original:
  "fix auth"
  Score: 2/10  │  20 files  │  9,800 tokens  │  $0.07

  Suggested:
  "explain fix auth in src/lib/auth.ts, step by step"
  Score: 8/10  │  15 files  │  6,200 tokens  │  $0.04

  Improvement:  -37% tokens  │  -43% cost
──────────────────────────────────────────────────

  [1] Original  [2] Suggested  [3] Edit  [n] Abort:

In non-interactive environments (CI, Claude Code), the suggested prompt is auto-selected.

---

Git Diff Mode (ctx diff)

When you only need AI to look at your changes — not the whole repo — ctx diff is the cheapest way to get help. It sends the raw git diff output as context, skipping the full repo scan entirely.

# Review unstaged changes (default: git diff HEAD)
ctx diff "review these changes for bugs"

# Only staged changes (what you're about to commit)
ctx diff "generate a commit message" --staged -y

# Compare current branch against main
ctx diff "summarize what this feature branch does" --branch main

# Preview cost + changed files
ctx diff "explain" --dry-run --explain

✔ 3 file(s) changed  [unstaged]

Changed files:
  src/cli/commands.ts
  src/cli/ask-send-handler.ts
  src/context/diff-parser.ts

Diff: 794 tokens | Prompt: 5 tokens

Estimated Cost: $0.0024  (claude-sonnet-4)

Typical diff requests cost $0.005–0.01 — 5–10x cheaper than ctx ask on the same project.

---

File Exclusions (.ctxignore)

Create a .ctxignore file in your project root to exclude files from context selection. Uses .gitignore syntax — globs, negation (!), comments (#).

# .ctxignore — files ctx should never include as context
dist/
coverage/
*.test.ts
*.spec.ts
__mocks__/
generated/
*.min.js
docs/

.ctxignore rules are applied on top of .gitignore and the built-in hard ignores. No config needed — just create the file and ctx picks it up automatically.

---

Multi-Turn Conversations (ctx follow)

Ask a question, get a response, ask a follow-up — without re-scanning the repo or losing conversation history.

# Start a conversation
ctx follow "explain the auth flow"

# With options (same as ctx ask)
ctx follow "explain the auth flow" -m qwen3-coder-plus -y --explain

✔ 142 files indexed
✔ 12 files selected (8,204 tokens)

The auth flow starts with...

  $0.0312 this turn | $0.0312 session total

  follow> what about the middleware?
  ✔ 15 files selected (9,100 tokens) [turn 2]

  The middleware handles JWT validation...

  $0.0287 this turn | $0.0599 session total

  follow> exit
  Session: 2 turns, $0.0599 total

How it works:

• Repo scan cached from turn 1 — no re-scanning on follow-ups
• Files re-scored per turn using new prompt keywords
• Conversation history included in context (compressed when over budget)
• Token budget split: 30% history, 60% file context, 10% prompt overhead
• Each turn logged to usage DB with command_type: 'follow'
• Type exit, quit, or press Ctrl+C to end the session

---

Supported Providers

Anthropic (Claude)

• Key: ANTHROPIC_API_KEY
• Models: claude-sonnet-4-20250514, claude-opus-4-20250514, claude-haiku-3-5-20241022

Alibaba Cloud (Qwen)

• Key: DASHSCOPE_API_KEY
• Models: qwen3-coder-plus, qwen-plus, qwen-turbo, qwen-max, qwen-long
• Auto-detects Coding Plan endpoint from sk-sp- key prefix

Provider is auto-detected from model name (qwen* → Qwen, otherwise → Anthropic). Override with -p qwen or -p anthropic.

---

Per-Project Config

Run ctx init to create a .claude-ctx.json in your project root:

{
  "model": "claude-sonnet-4-20250514",
  "tokenBudget": 30000,
  "maxTokens": 4096
}

Key	Default	Description
model	claude-sonnet-4-20250514	Default model per project
tokenBudget	30000	Max context tokens to send
maxTokens	4096	Max output tokens

---

Configuration

ctx loads configuration from three layers (highest priority wins):

Priority	Source	Purpose
1 (highest)	process.env	Runtime overrides
2	./.env	Project-level keys
3 (lowest)	~/.config/claude-ctx/.env	Global API keys

Global Config (one-time setup)

# Set API keys globally — works in any project
ctx config set DASHSCOPE_API_KEY sk-your-key
ctx config set ANTHROPIC_API_KEY sk-ant-your-key

# View stored keys (values are masked)
ctx config list

# Check a specific key
ctx config get DASHSCOPE_API_KEY

Keys are stored in ~/.config/claude-ctx/.env. No need to export env variables in your shell profile.

Project Override

Create a .env in any project to override global keys:

# /path/to/my-project/.env
DASHSCOPE_API_KEY=sk-project-specific-key

How It Works

On startup, ctx loads the global .env first, then the project .env on top. Existing process.env variables are never overwritten — they always take highest priority.

---

Cost Tracking

Every request is logged to a local SQLite database at ~/.config/claude-ctx/usage.db. Usage data never leaves your machine — no telemetry, no external reporting.

$ ctx stats --range 7d

Usage Statistics (last 7 days)
─────────────────────────────────────
  Requests:    12
  Total cost:  $0.87  (est: $1.02)
  Avg/request: $0.07
  Models:      claude-sonnet-4 (8), qwen3-coder-plus (4)

Tracks estimated vs actual cost, per-project breakdown, and most frequently included files (--top-files).

Web Dashboard (ctx dashboard)

For richer visualization, open the local web dashboard:

ctx dashboard          # opens http://localhost:3847
ctx dashboard --port 8080

Features:

• Summary cards — total cost, requests, avg cost/request, total tokens
• Daily cost trend — line chart (last 30 days)
• Cost by model — doughnut chart breakdown
• Recent requests — table with timestamp, project, model, cost, prompt preview
• Date range selector — today / 7d / 30d / all time
• Auto-refreshes every 10s. All data stays local — served from localhost only.

---

Who Is This For?

• Solo developers using AI APIs directly who want cost control and token optimization
• Team leads who need visibility into AI spend across multiple projects
• Cost-conscious builders who want AI assistance without runaway bills
• Prompt engineers who want to improve prompt quality systematically
• Anyone tired of manually selecting which files to paste into AI prompts

---

Architecture

src/
├── index.ts                 # Entry point
├── cli/
│   ├── commands.ts               # CLI commands (ask, diff, follow, stats, dashboard, config, init)
│   ├── formatter.ts              # Terminal output formatting
│   ├── ask-send-handler.ts       # Shared send + log handler
│   ├── ask-compare-handler.ts    # --compare flow handler
│   ├── diff-send-handler.ts      # ctx diff flow handler
│   └── follow-session-handler.ts # ctx follow multi-turn session handler
├── context/
│   ├── analyzer.ts          # Repo scanner (.gitignore + .ctxignore + hard ignore)
│   ├── selector.ts          # File scoring (keyword, recency, proximity, type)
│   ├── optimizer.ts         # Context assembly + truncation
│   ├── tokenizer.ts         # Token counting (js-tiktoken cl100k_base)
│   └── diff-parser.ts       # Git diff extraction (unstaged/staged/branch)
├── api/
│   └── claude-client.ts     # Anthropic + Qwen streaming with retry
├── cost/
│   ├── calculator.ts        # Price table + cost estimation
│   ├── tracker.ts           # SQLite usage logging
│   └── reporter.ts          # Stats aggregation + display
├── prompt/
│   ├── scorer.ts            # Rule-based scoring (0-10)
│   ├── prompt-improver.ts   # Rule-based prompt enhancement
│   └── comparison-display.ts # Side-by-side comparison output
├── storage/
│   ├── database.ts          # SQLite connection + migrations
│   └── schema.sql           # Table definitions
├── dashboard/
│   ├── dashboard-api.ts     # API query functions (summary, daily, models, recent)
│   ├── dashboard-server.ts  # HTTP server (localhost only, serves HTML + JSON API)
│   └── dashboard-ui.html    # Single-file dashboard (Chart.js, dark theme, auto-refresh)
├── config/
│   ├── config.ts            # Config loading (XDG + per-project)
│   └── global-env-writer.ts # Read/write global .env keys
└── utils/
    └── logger.ts            # Colored logging helpers

Tech stack: Node.js 20+ / TypeScript (ESM), Commander.js, @anthropic-ai/sdk, openai, js-tiktoken, better-sqlite3, chalk, ora, vitest.

---

Roadmap

v0.1 — shipped:

• Intelligent context selection (keyword + recency + proximity + type scoring)
• Cost estimation before sending
• Streaming responses
• Per-project + per-model AI cost tracking (SQLite)
• Prompt comparison with auto-improvement (--compare)
• Claude + Qwen multi-provider support
• Auto-retry on transient errors (429, 5xx)

v0.2 — in progress:

• ctx diff — send only git diff as context (cheapest mode)
• ctx dashboard — local web dashboard for usage analytics (Chart.js, zero deps)
• ctx follow — multi-turn conversations with cached repo context
• .ctxignore — per-project file exclusions (gitignore syntax)
• OpenRouter support (unified key for multiple providers)
• Interactive file picker (ctx ask --pick)

Future — exploring:

• Embedding-based file selection (semantic search)
• Team usage aggregation and shared budgets
• Budget alerts and spending limits
• npm install -g claude-ctx (published package)

Interested in team features, shared dashboards, or enterprise cost controls? Open an issue — we'd like to hear what matters to your workflow.

---

Contributing

Issues and PRs welcome at github.com/Winter279/claude-ctx.

License

MIT