@kkothari/tokenpilot 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# TokenPilot
+
+**Terminal-first AI assistant for vibecoders.** TokenPilot sits between you and
+your AI coding tool (Claude Code, Cursor, Codex, Gemini CLI, …). Before a prompt
+is sent, it estimates how expensive the prompt will be, flags whether it's too
+broad, and rewrites it into a focused version that keeps the AI working on the
+right part of your project instead of searching the whole codebase.
+
+> Like Grammarly for AI coding prompts — but built for the terminal.
+
+This repo is the **CLI core** (MVP). Analysis, token estimation, prompt
+rewriting, and session tracking all run **locally, offline, with no API key.**
+
+---
+
+## Quick start
+
+No install needed to try it (zero runtime dependencies, Node ≥ 18):
+
+```bash
+node bin/tokenpilot.js analyze "Fix the dashboard bug"
+```
+
+Or link it globally so `tokenpilot` is on your PATH:
+
+```bash
+npm link          # from this directory
+tokenpilot start
+```
+
+---
+
+## What you get
+
+```
+$ tokenpilot analyze "Fix the dashboard bug related to token usage"
+
+⚠ BROAD  breadth 68/100
+  ████████████████░░░░░░░░
+
+  Projected cost  ~30,867 tokens  (prompt 11 + exploration 30,856)  ≈ $0.19
+
+  Issues
+  ✕ Broad scope ("the dashboard") — likely to trigger a full-project search.
+  ✕ Vague instruction ("fix") with no specific target.
+  ! No file, path, or symbol referenced — the assistant must go find it.
+
+  Likely-relevant files
+  ▫ src/Dashboard.tsx
+  ▫ src/tokenCalc.ts
+  ▫ src/usageApi.ts
+
+  ────────────────────────────────────────────────────────────
+  Suggested prompt   saves ~25,801 tokens (84%)
+
+  Fix the dashboard bug related to token usage. Begin by checking
+  `src/Dashboard.tsx`, `src/tokenCalc.ts`, `src/usageApi.ts`. Do not
+  redesign the UI or refactor unrelated components. Make the smallest
+  change necessary. Briefly explain which files you modified and why.
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `tokenpilot start` | Interactive REPL — analyzes every prompt before you send it, tracks running savings. The primary experience. |
+| `tokenpilot analyze "<prompt>"` | Analyze one prompt and print a focused rewrite. |
+| `tokenpilot stats` | Session analytics: tokens projected, saved, $ saved, most expensive prompts. |
+| `tokenpilot history` | Every prompt analyzed this session. |
+| `tokenpilot reset` | Start a fresh session. |
+| `tokenpilot help` | Full help. |
+
+### Options
+
+| Flag | Meaning |
+| --- | --- |
+| `--provider <id>` | Pricing model for `$` estimates: `claude-opus`, `claude-sonnet` (default), `claude-haiku`, `gpt-4o`, `gemini-pro`. |
+| `--json` | Machine-readable output (for `analyze`). |
+| `--no-scan` | Skip the project file scan. |
+| `--no-track` | Don't record the prompt in the session. |
+
+In the `start` REPL: `:stats`, `:clear`, `:quit`.
+
+---
+
+## How it works
+
+Everything is local, deterministic, and dependency-free.
+
+- **`src/core/tokenizer.js`** — offline token estimator (blends chars/4 and
+  words/0.75, with a punctuation bump). Within ~10–15% of real BPE counts.
+- **`src/core/analyzer.js`** — the heuristic engine. Detects vague verbs, broad
+  scope, heavy-change verbs, missing file references, over-short/over-long
+  prompts, missing scope guards, and near-duplicate prompts. Produces a 0–100
+  **breadth score** and projects total token cost. A concrete file reference and
+  an explicit scope guard each measurably lower the projected exploration cost —
+  because those are what actually bound how far the AI wanders.
+- **`src/core/scanner.js`** — scans the working directory for source files whose
+  names/paths match your prompt keywords, so rewrites can name real files.
+- **`src/core/rewrite.js`** — turns intent + missing pieces into a focused
+  prompt: original intent → concrete starting point → scope guard → report-back.
+- **`src/core/session.js`** — local session log at `~/.tokenpilot/session.json`.
+
+---
+
+## Roadmap
+
+The MVP CLI is here. Still to come, per the product vision:
+
+- Browser-based account auth (GitHub / Google) and terminal ↔ account linking
+- Dashboard sync + web analytics
+- Optional AI-powered rewrites (hybrid: heuristics for detection, an LLM call
+  for the rewrite) via the Vercel AI Gateway
+- Landing page and `npx tokenpilot install`
+
+---
+
+## Development
+
+```bash
+npm test        # run the unit test suite (node --test)
+```
+
+MIT.

package/bin/tokenpilot.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// TokenPilot CLI entry point.
+import { run } from "../src/cli.js";
+
+const code = run();
+if (typeof code === "number" && code !== 0) {
+  process.exitCode = code;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kkothari/tokenpilot",
+  "version": "0.1.0",
+  "description": "Terminal-first AI assistant that analyzes coding prompts before they reach AI tools, flags broad prompts, estimates token cost, and rewrites vague prompts into focused ones.",
+  "type": "module",
+  "bin": {
+    "tokenpilot": "bin/tokenpilot.js"
+  },
+  "scripts": {
+    "start": "node bin/tokenpilot.js start",
+    "analyze": "node bin/tokenpilot.js analyze",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "tokens",
+    "prompt",
+    "cli",
+    "claude",
+    "cursor",
+    "llm",
+    "developer-tools"
+  ],
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,105 @@
+// Argument parsing and command dispatch for the `tokenpilot` CLI.
+
+import { runAnalyze } from "./commands/analyze.js";
+import { runStart } from "./commands/start.js";
+import { runStats, runHistory, runReset } from "./commands/stats.js";
+import { colors } from "./ui/colors.js";
+import { banner } from "./ui/format.js";
+import { PROVIDERS, DEFAULT_PROVIDER } from "./config.js";
+
+const VERSION = "0.1.0";
+
+// Minimal flag parser: separates --flags (and --key value) from positionals.
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (key.startsWith("no-")) {
+        flags[key.slice(3)] = false;
+      } else if (key === "json" || key === "help" || key === "version") {
+        flags[key] = true;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+        flags[key] = argv[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { flags, positionals };
+}
+
+function printHelp() {
+  const c = colors;
+  console.log(`
+${banner()}
+
+${c.bold("USAGE")}
+  tokenpilot <command> [options]
+
+${c.bold("COMMANDS")}
+  ${c.cyan("start")}                 Launch the interactive terminal companion (REPL)
+  ${c.cyan("analyze")} ${c.gray('"<prompt>"')}   Analyze a single prompt and suggest a focused rewrite
+  ${c.cyan("stats")}                 Show token-savings analytics for this session
+  ${c.cyan("history")}               List every prompt analyzed this session
+  ${c.cyan("reset")}                 Clear the current session and start fresh
+  ${c.cyan("help")}                  Show this help
+
+${c.bold("OPTIONS")}
+  ${c.gray("--provider <id>")}       Pricing model for $ estimates ${c.gray(
+    `(default: ${DEFAULT_PROVIDER})`
+  )}
+                        ${c.gray(Object.keys(PROVIDERS).join(", "))}
+  ${c.gray("--json")}                Machine-readable output (analyze)
+  ${c.gray("--no-scan")}             Skip the project file scan
+  ${c.gray("--no-track")}            Don't record this prompt in the session
+  ${c.gray("--version")}             Print version
+
+${c.bold("EXAMPLES")}
+  ${c.gray("$")} tokenpilot analyze ${c.gray('"Fix the dashboard bug"')}
+  ${c.gray("$")} tokenpilot analyze ${c.gray('"add auth"')} --provider claude-opus
+  ${c.gray("$")} tokenpilot start
+  ${c.gray("$")} tokenpilot stats
+`);
+}
+
+export function run(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArgs(argv);
+
+  if (flags.version) {
+    console.log(`tokenpilot ${VERSION}`);
+    return 0;
+  }
+
+  const command = positionals[0] || (flags.help ? "help" : "help");
+
+  switch (command) {
+    case "analyze": {
+      const prompt = positionals.slice(1).join(" ");
+      return runAnalyze(prompt, flags);
+    }
+    case "start":
+      return runStart(flags);
+    case "stats":
+      return runStats(flags);
+    case "history":
+      return runHistory(flags);
+    case "reset":
+      return runReset(flags);
+    case "help":
+      printHelp();
+      return 0;
+    default:
+      console.error(
+        colors.red(`Unknown command: ${command}`) +
+          "\n  Run " +
+          colors.cyan("tokenpilot help") +
+          " to see available commands."
+      );
+      return 1;
+  }
+}

package/src/commands/analyze.js

@@ -0,0 +1,72 @@
+// `tokenpilot analyze "<prompt>"` — analyze one prompt and suggest a focused
+// rewrite. Supports --json for programmatic use and --no-scan to skip the disk
+// scan.
+
+import { optimize } from "../core/rewrite.js";
+import { findRelevantFiles } from "../core/scanner.js";
+import { renderAnalysis, banner } from "../ui/format.js";
+import { colors } from "../ui/colors.js";
+import { record } from "../core/session.js";
+import { DEFAULT_PROVIDER } from "../config.js";
+
+export function runAnalyze(prompt, flags = {}) {
+  if (!prompt || !prompt.trim()) {
+    console.error(
+      colors.red("No prompt provided.") +
+        '  Usage: tokenpilot analyze "your prompt here"'
+    );
+    return 1;
+  }
+
+  const provider = flags.provider || DEFAULT_PROVIDER;
+  const relevantFiles =
+    flags.scan === false ? [] : findRelevantFiles(prompt, process.cwd());
+
+  const result = optimize(prompt, { relevantFiles });
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          prompt,
+          breadthScore: result.analysis.breadthScore,
+          rating: result.analysis.rating,
+          projectedTokens: result.analysis.projectedTokens,
+          promptTokens: result.analysis.promptTokens,
+          explorationTokens: result.analysis.explorationTokens,
+          issues: result.analysis.issues,
+          relevantFiles,
+          suggestion: result.focused.text,
+          optimizedTokens: result.rewrittenAnalysis.projectedTokens,
+          savedTokens: result.savedTokens,
+          savedPct: result.savedPct,
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(banner());
+    console.log(
+      renderAnalysis(result.analysis, {
+        optimize: result,
+        relevantFiles,
+        provider,
+      })
+    );
+  }
+
+  // Track it (best-effort) unless disabled.
+  if (flags.track !== false) {
+    record({
+      prompt,
+      breadthScore: result.analysis.breadthScore,
+      rating: result.analysis.rating,
+      projectedTokens: result.analysis.projectedTokens,
+      optimizedTokens: result.rewrittenAnalysis.projectedTokens,
+      savedTokens: result.savedTokens,
+    });
+  }
+
+  return 0;
+}

package/src/commands/start.js

@@ -0,0 +1,131 @@
+// `tokenpilot start` — the always-on terminal companion.
+//
+// Opens an interactive REPL that analyzes every prompt you paste before you
+// send it to your AI coding tool, shows a focused rewrite, and tracks running
+// token savings for the session. This is the primary TokenPilot experience.
+//
+// (Account linking / browser auth is stubbed for the MVP — see the note printed
+// on launch. Analysis and tracking work fully offline today.)
+
+import readline from "node:readline";
+import { optimize } from "../core/rewrite.js";
+import { findRelevantFiles } from "../core/scanner.js";
+import { renderAnalysis, banner, num, money } from "../ui/format.js";
+import { colors } from "../ui/colors.js";
+import { load, record, summarize } from "../core/session.js";
+import { DEFAULT_PROVIDER } from "../config.js";
+
+export function runStart(flags = {}) {
+  const provider = flags.provider || DEFAULT_PROVIDER;
+
+  console.log("");
+  console.log(banner());
+  console.log(
+    colors.gray(
+      "  Session tracking active. Paste a prompt to analyze it before you send it."
+    )
+  );
+  console.log(
+    colors.gray(
+      "  Commands: ") +
+      colors.cyan(":stats") +
+      colors.gray(" summary  ·  ") +
+      colors.cyan(":clear") +
+      colors.gray(" screen  ·  ") +
+      colors.cyan(":quit") +
+      colors.gray(" exit")
+  );
+  console.log(
+    colors.gray("  Account linking (browser auth) arrives in the next build.")
+  );
+  console.log("");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: colors.cyan("tokenpilot") + colors.gray(" › "),
+  });
+
+  // Keep an in-memory history for duplicate detection within this REPL.
+  const history = (load().prompts || []).map((p) => p.prompt);
+
+  rl.prompt();
+
+  rl.on("line", (line) => {
+    const input = line.trim();
+
+    if (!input) {
+      rl.prompt();
+      return;
+    }
+
+    // REPL commands.
+    if (input === ":quit" || input === ":q" || input === ":exit") {
+      rl.close();
+      return;
+    }
+    if (input === ":clear" || input === ":cls") {
+      console.clear();
+      rl.prompt();
+      return;
+    }
+    if (input === ":stats") {
+      printMiniStats(provider);
+      rl.prompt();
+      return;
+    }
+
+    // Analyze the prompt.
+    const relevantFiles =
+      flags.scan === false ? [] : findRelevantFiles(input, process.cwd());
+    const result = optimize(input, { relevantFiles, history });
+
+    console.log(
+      renderAnalysis(result.analysis, {
+        optimize: result,
+        relevantFiles,
+        provider,
+      })
+    );
+
+    history.push(input);
+    record({
+      prompt: input,
+      breadthScore: result.analysis.breadthScore,
+      rating: result.analysis.rating,
+      projectedTokens: result.analysis.projectedTokens,
+      optimizedTokens: result.rewrittenAnalysis.projectedTokens,
+      savedTokens: result.savedTokens,
+    });
+
+    rl.prompt();
+  });
+
+  rl.on("close", () => {
+    const s = summarize(load(), provider);
+    console.log("");
+    console.log(
+      colors.gray("  Session ended · ") +
+        `${num(s.total)} prompts analyzed, ` +
+        colors.green(`~${num(s.savedTokens)} tokens saved`) +
+        colors.gray(` (≈ ${money(s.dollarsSaved)})`)
+    );
+    console.log(colors.gray("  Run ") + colors.cyan("tokenpilot stats") + colors.gray(" any time.\n"));
+    process.exit(0);
+  });
+}
+
+function printMiniStats(provider) {
+  const s = summarize(load(), provider);
+  console.log("");
+  console.log(
+    colors.bold("  This session  ") +
+      colors.gray(`${num(s.total)} prompts · ${num(s.broad)} broad`)
+  );
+  console.log(
+    `  Projected ${colors.cyan(num(s.projectedTokens))} tokens · ` +
+      colors.green(`saved ~${num(s.savedTokens)} (${s.savedPct}%)`) +
+      colors.gray(` ≈ ${money(s.dollarsSaved)}`)
+  );
+  console.log("");
+}

package/src/commands/stats.js

@@ -0,0 +1,108 @@
+// `tokenpilot stats` — session analytics summary.
+// `tokenpilot history` — the full prompt log.
+// `tokenpilot reset` — start a fresh session.
+
+import { load, summarize, reset as resetSession, SESSION_FILE } from "../core/session.js";
+import { colors } from "../ui/colors.js";
+import { banner, num, money, bar } from "../ui/format.js";
+import { DEFAULT_PROVIDER, PROVIDERS } from "../config.js";
+
+function truncate(s, n = 52) {
+  s = String(s).replace(/\s+/g, " ");
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+export function runStats(flags = {}) {
+  const provider = flags.provider || DEFAULT_PROVIDER;
+  const s = summarize(load(), provider);
+
+  console.log("");
+  console.log(banner());
+
+  if (s.total === 0) {
+    console.log(
+      colors.gray(
+        "\n  No prompts tracked yet. Run `tokenpilot start` or `tokenpilot analyze \"…\"`.\n"
+      )
+    );
+    return 0;
+  }
+
+  const label = (PROVIDERS[provider] || PROVIDERS[DEFAULT_PROVIDER]).label;
+  console.log(
+    colors.gray(
+      `  Session ${s.id} · since ${new Date(s.startedAt).toLocaleString()} · ${label}\n`
+    )
+  );
+
+  const row = (k, v) => console.log(`  ${colors.gray(k.padEnd(20))}${v}`);
+  row("Prompts analyzed", num(s.total));
+  row("Broad prompts", `${num(s.broad)} ${colors.gray(`of ${num(s.total)}`)}`);
+  row("Projected tokens", colors.cyan(num(s.projectedTokens)));
+  row("Optimized tokens", num(s.optimizedTokens));
+  row(
+    "Tokens saved",
+    colors.green(`~${num(s.savedTokens)}`) + colors.gray(`  (${s.savedPct}%)`)
+  );
+  row("Estimated $ saved", colors.green(money(s.dollarsSaved)));
+  console.log(`  ${colors.gray("Savings".padEnd(20))}${bar(s.savedPct)}`);
+
+  if (s.mostExpensive.length) {
+    console.log("\n  " + colors.bold("Most expensive prompts"));
+    for (const p of s.mostExpensive) {
+      console.log(
+        `  ${colors.yellow(String(num(p.projectedTokens)).padStart(7))}  ${colors.gray(
+          truncate(p.prompt)
+        )}`
+      );
+    }
+  }
+
+  if (s.biggestSavers.some((p) => p.savedTokens > 0)) {
+    console.log("\n  " + colors.bold("Biggest savers"));
+    for (const p of s.biggestSavers) {
+      if (!p.savedTokens) continue;
+      console.log(
+        `  ${colors.green("-" + num(p.savedTokens)).padStart(18)}  ${colors.gray(
+          truncate(p.prompt)
+        )}`
+      );
+    }
+  }
+
+  console.log(colors.gray(`\n  Data: ${SESSION_FILE}\n`));
+  return 0;
+}
+
+export function runHistory() {
+  const session = load();
+  const prompts = session.prompts || [];
+  console.log("");
+  console.log(banner());
+  if (prompts.length === 0) {
+    console.log(colors.gray("\n  No prompt history yet.\n"));
+    return 0;
+  }
+  console.log("");
+  prompts.forEach((p, i) => {
+    const tag =
+      p.rating === "broad"
+        ? colors.red("BROAD")
+        : p.rating === "moderate"
+        ? colors.yellow("MOD ")
+        : colors.green("OK  ");
+    console.log(
+      `  ${colors.gray(String(i + 1).padStart(3))}. [${tag}] ` +
+        `${colors.cyan(String(num(p.projectedTokens)).padStart(6))}t  ` +
+        colors.gray(truncate(p.prompt, 56))
+    );
+  });
+  console.log("");
+  return 0;
+}
+
+export function runReset() {
+  resetSession();
+  console.log(colors.green("\n  ✓ Session reset. A fresh session has begun.\n"));
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,31 @@
+// Central configuration and pricing model for TokenPilot.
+// Prices are blended $ per 1M tokens (input + output averaged) and are only
+// used to turn token estimates into rough dollar figures. They are deliberately
+// approximate — the point is relative savings, not billing accuracy.
+
+export const PROVIDERS = {
+  "claude-opus": { label: "Claude Opus", pricePer1M: 30 },
+  "claude-sonnet": { label: "Claude Sonnet", pricePer1M: 6 },
+  "claude-haiku": { label: "Claude Haiku", pricePer1M: 1.5 },
+  "gpt-4o": { label: "GPT-4o", pricePer1M: 7.5 },
+  "gemini-pro": { label: "Gemini Pro", pricePer1M: 4 },
+};
+
+export const DEFAULT_PROVIDER = "claude-sonnet";
+
+// How many tokens a single unfocused prompt tends to burn once the coding
+// assistant starts searching and reading files. Used as the ceiling that a
+// maximally broad prompt (breadthScore = 100) is projected to cost.
+export const MAX_EXPLORATION_TOKENS = 45000;
+
+// Even a perfectly scoped prompt still costs *some* exploration on top of the
+// prompt text itself. This is the floor.
+export const MIN_EXPLORATION_TOKENS = 800;
+
+export function priceFor(providerKey = DEFAULT_PROVIDER) {
+  return (PROVIDERS[providerKey] || PROVIDERS[DEFAULT_PROVIDER]).pricePer1M;
+}
+
+export function dollarsFor(tokens, providerKey = DEFAULT_PROVIDER) {
+  return (tokens / 1_000_000) * priceFor(providerKey);
+}

package/src/core/analyzer.js

@@ -0,0 +1,218 @@
+// The prompt analysis engine.
+//
+// Given a raw prompt (and optional session history), it detects the patterns
+// that make AI coding assistants waste tokens, produces a 0-100 "breadth score"
+// (higher = broader = more wasteful), and projects how many tokens the prompt
+// is likely to burn once the assistant starts exploring the codebase.
+//
+// Everything here is local, rule-based, and deterministic. No network, no keys.
+
+import { estimateTokens } from "./tokenizer.js";
+import {
+  MAX_EXPLORATION_TOKENS,
+  MIN_EXPLORATION_TOKENS,
+} from "../config.js";
+
+// --- Signal dictionaries ----------------------------------------------------
+
+// Vague action verbs that describe intent without a concrete target.
+const VAGUE_VERBS = [
+  "fix", "improve", "optimize", "clean up", "cleanup", "enhance", "polish",
+  "handle", "update", "tweak", "sort out", "deal with", "work on", "look into",
+];
+
+// Words that widen scope to large or unbounded areas of the codebase.
+const BROAD_SCOPE = [
+  "everything", "the whole", "entire", "all the", "the codebase", "the project",
+  "the app", "the application", "the system", "the frontend", "the backend",
+  "the ui", "the dashboard", "the site", "the website", "throughout",
+  "across the", "anywhere", "wherever",
+];
+
+// Words that trigger large, sprawling changes.
+const HEAVY_CHANGE = [
+  "refactor", "redesign", "rewrite", "overhaul", "restructure", "rearchitect",
+  "migrate", "modernize", "revamp", "rework", "clean up the whole",
+];
+
+// A prompt that references a file, path, or symbol is already fairly scoped.
+const FILE_REF = /([\w./-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|vue|svelte|css|scss|html|json|md))\b/i;
+const PATH_REF = /(^|\s)(src|app|lib|components|pages|api|routes|packages|apps)[\\/][\w./-]+/i;
+const CODE_REF = /`[^`]+`/; // backtick-wrapped symbol or identifier
+
+// Explicit scope guards the developer might already include.
+const HAS_CONSTRAINT =
+  /(smallest change|do not refactor|don'?t refactor|only (change|modify|touch)|without (changing|touching)|minimal|just this|scope|leave .* unchanged)/i;
+
+// --- Helpers ----------------------------------------------------------------
+
+const includesAny = (text, phrases) =>
+  phrases.filter((p) => text.includes(p));
+
+function clamp(n, lo, hi) {
+  return Math.max(lo, Math.min(hi, n));
+}
+
+// --- Main analysis ----------------------------------------------------------
+
+/**
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @param {string[]} [opts.history] previously-seen prompts this session
+ * @returns {object} analysis result
+ */
+export function analyzePrompt(prompt, opts = {}) {
+  const raw = String(prompt || "").trim();
+  const text = raw.toLowerCase();
+  const words = raw.split(/\s+/).filter(Boolean);
+  const history = opts.history || [];
+
+  const issues = [];
+  const add = (id, severity, weight, message, hint) =>
+    issues.push({ id, severity, weight, message, hint });
+
+  const hasFileRef = FILE_REF.test(raw) || PATH_REF.test(raw) || CODE_REF.test(raw);
+
+  // 1. Vague action verb with no concrete target.
+  const vague = includesAny(text, VAGUE_VERBS);
+  if (vague.length && !hasFileRef) {
+    add(
+      "vague-verb",
+      "high",
+      22,
+      `Vague instruction ("${vague[0]}") with no specific target.`,
+      "Name the file, function, or exact behavior to change."
+    );
+  }
+
+  // 2. Broad scope language.
+  const broad = includesAny(text, BROAD_SCOPE);
+  if (broad.length) {
+    add(
+      "broad-scope",
+      "high",
+      24,
+      `Broad scope ("${broad[0]}") — likely to trigger a full-project search.`,
+      "Point at the specific area or files involved."
+    );
+  }
+
+  // 3. Heavy / sprawling change verbs.
+  const heavy = includesAny(text, HEAVY_CHANGE);
+  if (heavy.length) {
+    add(
+      "heavy-change",
+      "medium",
+      16,
+      `Large-change verb ("${heavy[0]}") can cause unrelated rewrites.`,
+      "Constrain it: smallest change necessary, no unrelated refactors."
+    );
+  }
+
+  // 4. No file / path / symbol reference at all.
+  if (!hasFileRef) {
+    add(
+      "no-file-ref",
+      "medium",
+      14,
+      "No file, path, or symbol referenced — the assistant must go find it.",
+      "Add a starting point, e.g. `Dashboard.tsx` or `src/api/usage.ts`."
+    );
+  }
+
+  // 5. Too short to be actionable.
+  if (words.length > 0 && words.length < 5) {
+    add(
+      "too-short",
+      "medium",
+      12,
+      `Very short prompt (${words.length} words) — likely ambiguous.`,
+      "Add the what, where, and any constraints."
+    );
+  }
+
+  // 6. Overly long / context-dumping prompt.
+  const promptTokens = estimateTokens(raw);
+  if (promptTokens > 500) {
+    add(
+      "excessive-context",
+      "low",
+      8,
+      `Long prompt (~${promptTokens} tokens) — may include unnecessary context.`,
+      "Trim to the essentials the assistant actually needs."
+    );
+  }
+
+  // 7. No explicit scope guard.
+  if (!HAS_CONSTRAINT.test(raw) && (vague.length || broad.length || heavy.length)) {
+    add(
+      "no-constraint",
+      "low",
+      8,
+      "No scope guard — nothing stops the assistant from wandering.",
+      'Add: "Make the smallest change necessary; don\'t refactor unrelated code."'
+    );
+  }
+
+  // 8. Repeated / near-duplicate of an earlier prompt this session.
+  const repeated = history.find((h) => similarity(h, raw) > 0.85);
+  if (repeated) {
+    add(
+      "repeated",
+      "medium",
+      12,
+      "Near-duplicate of an earlier prompt — risk of repeating work.",
+      "Reference the previous result instead of starting over."
+    );
+  }
+
+  // --- Score & projections --------------------------------------------------
+
+  const rawScore = issues.reduce((s, i) => s + i.weight, 0);
+  const breadthScore = clamp(Math.round(rawScore), 0, 100);
+
+  // Project total tokens the prompt is likely to burn: prompt text + an
+  // exploration cost that scales with breadth.
+  let exploration =
+    MIN_EXPLORATION_TOKENS +
+    (MAX_EXPLORATION_TOKENS - MIN_EXPLORATION_TOKENS) * (breadthScore / 100);
+
+  // Two things genuinely bound how far the assistant wanders — and they're
+  // exactly what a good rewrite adds. Reward them multiplicatively so an
+  // optimized prompt projects a realistically lower cost.
+  const hasConstraint = HAS_CONSTRAINT.test(raw);
+  if (hasFileRef) exploration *= 0.45; // a concrete starting point
+  if (hasConstraint) exploration *= 0.6; // an explicit scope guard
+  exploration = Math.round(Math.max(MIN_EXPLORATION_TOKENS, exploration));
+
+  const projectedTokens = promptTokens + exploration;
+
+  return {
+    prompt: raw,
+    empty: raw.length === 0,
+    words: words.length,
+    hasFileRef,
+    issues: issues.sort((a, b) => b.weight - a.weight),
+    breadthScore,
+    rating: ratingFor(breadthScore),
+    promptTokens,
+    explorationTokens: exploration,
+    projectedTokens,
+  };
+}
+
+export function ratingFor(score) {
+  if (score >= 55) return "broad";
+  if (score >= 25) return "moderate";
+  return "focused";
+}
+
+// Rough token-set Jaccard similarity for duplicate detection.
+function similarity(a, b) {
+  const setA = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+  const setB = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let inter = 0;
+  for (const w of setA) if (setB.has(w)) inter++;
+  return inter / (setA.size + setB.size - inter);
+}

package/src/core/rewrite.js

@@ -0,0 +1,101 @@
+// Turns an analysis result into a focused, rewritten prompt — deterministically,
+// with no AI call. The strategy: preserve the developer's intent, then layer on
+// the scoping scaffolding their prompt was missing (a starting point, a scope
+// guard, and a report-back instruction).
+//
+// When a real project is on disk, `relevantFiles` are woven in so the rewrite
+// names concrete files. Otherwise we insert a clearly-marked placeholder the
+// developer can fill in.
+
+import { analyzePrompt } from "./analyzer.js";
+import { estimateTokens } from "./tokenizer.js";
+import {
+  MAX_EXPLORATION_TOKENS,
+  MIN_EXPLORATION_TOKENS,
+} from "../config.js";
+
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// Ensure the intent sentence ends cleanly with a single period.
+function normalizeIntent(prompt) {
+  let s = prompt.trim().replace(/\s+/g, " ");
+  if (!s) return s;
+  s = capitalize(s);
+  if (!/[.!?]$/.test(s)) s += ".";
+  return s;
+}
+
+/**
+ * @param {object} analysis  result from analyzePrompt()
+ * @param {object} [opts]
+ * @param {string[]} [opts.relevantFiles]  files surfaced by the scanner
+ * @returns {{ text: string, notes: string[] }}
+ */
+export function buildFocusedPrompt(analysis, opts = {}) {
+  const relevantFiles = opts.relevantFiles || [];
+  const has = (id) => analysis.issues.some((i) => i.id === id);
+  const parts = [];
+  const notes = [];
+
+  // 1. Keep the original intent as the lead sentence.
+  parts.push(normalizeIntent(analysis.prompt));
+
+  // 2. Give the assistant a concrete starting point.
+  if (!analysis.hasFileRef) {
+    if (relevantFiles.length) {
+      const list = relevantFiles.map((f) => `\`${f}\``).join(", ");
+      parts.push(`Begin by checking ${list}.`);
+      notes.push("Added likely-relevant files from a project scan.");
+    } else {
+      parts.push(
+        "Begin by checking [name the 1-3 files most likely involved]."
+      );
+      notes.push(
+        "No project scan available — fill in the bracketed starting files."
+      );
+    }
+  }
+
+  // 3. Add a scope guard when the prompt could sprawl.
+  if (has("broad-scope") || has("heavy-change") || has("no-constraint") || has("vague-verb")) {
+    parts.push(
+      "Do not redesign the UI or refactor unrelated components. Make the smallest change necessary."
+    );
+    notes.push("Added a scope guard to prevent unrelated changes.");
+  }
+
+  // 4. Ask for a short report of what changed — cheap and keeps output tight.
+  parts.push("Briefly explain which files you modified and why.");
+
+  const text = parts.join(" ");
+
+  return { text, notes };
+}
+
+// Convenience: analyze + rewrite + compute projected savings in one call.
+export function optimize(prompt, opts = {}) {
+  const analysis = analyzePrompt(prompt, opts);
+  const focused = buildFocusedPrompt(analysis, opts);
+
+  // Re-analyze the rewritten prompt to project its (lower) token cost.
+  const rewrittenAnalysis = analyzePrompt(focused.text, opts);
+  const savedTokens = Math.max(
+    0,
+    analysis.projectedTokens - rewrittenAnalysis.projectedTokens
+  );
+
+  return {
+    analysis,
+    focused,
+    rewrittenAnalysis,
+    savedTokens,
+    savedPct:
+      analysis.projectedTokens > 0
+        ? Math.round((savedTokens / analysis.projectedTokens) * 100)
+        : 0,
+  };
+}
+
+export { estimateTokens, MAX_EXPLORATION_TOKENS, MIN_EXPLORATION_TOKENS };

package/src/core/scanner.js

@@ -0,0 +1,112 @@
+// Lightweight project scanner.
+//
+// Given a prompt, we try to point the coding assistant at the files it most
+// likely needs — so its rewritten prompt can say "start by checking X, Y"
+// instead of triggering a full-project search. This is pure filename/path
+// heuristics: fast, offline, and good enough to seed a focused prompt.
+
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, basename, extname, sep } from "node:path";
+
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "vendor",
+  ".venv",
+  "__pycache__",
+]);
+
+const SOURCE_EXTS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rs", ".java", ".rb", ".php",
+  ".vue", ".svelte", ".css", ".scss", ".html",
+]);
+
+// Words too generic to be useful as file-matching signal.
+const STOPWORDS = new Set([
+  "the", "a", "an", "and", "or", "but", "to", "of", "in", "on", "for", "with",
+  "fix", "add", "make", "update", "change", "improve", "better", "please",
+  "bug", "issue", "error", "problem", "code", "file", "files", "app", "this",
+  "that", "it", "my", "our", "some", "any", "all", "new", "old", "use", "using",
+]);
+
+function walk(dir, root, files, depth) {
+  if (depth > 6) return; // keep scans shallow and fast
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") && entry.name !== ".") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      walk(full, root, files, depth + 1);
+    } else if (entry.isFile()) {
+      if (SOURCE_EXTS.has(extname(entry.name))) {
+        // Normalize to forward slashes — these paths go into prompts.
+        files.push(relative(root, full).split(sep).join("/"));
+        if (files.length > 4000) return; // safety cap for huge repos
+      }
+    }
+  }
+}
+
+export function keywordsFromPrompt(prompt) {
+  return [
+    ...new Set(
+      String(prompt)
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length >= 3 && !STOPWORDS.has(w))
+    ),
+  ];
+}
+
+// Returns up to `limit` files most relevant to the prompt keywords, each with a
+// score. Returns [] when there's no project on disk or nothing matches.
+export function findRelevantFiles(prompt, root = process.cwd(), limit = 4) {
+  let stat;
+  try {
+    stat = statSync(root);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [];
+
+  const files = [];
+  walk(root, root, files, 0);
+  if (files.length === 0) return [];
+
+  const keywords = keywordsFromPrompt(prompt);
+  if (keywords.length === 0) return [];
+
+  const scored = [];
+  for (const file of files) {
+    const lowerPath = file.toLowerCase();
+    const base = basename(lowerPath, extname(lowerPath));
+    let score = 0;
+    for (const kw of keywords) {
+      if (base === kw) score += 10; // exact filename match
+      else if (base.includes(kw)) score += 5; // filename contains keyword
+      else if (lowerPath.includes(kw)) score += 2; // somewhere in the path
+    }
+    if (score > 0) {
+      // Prefer shallower files; deep paths are usually less central.
+      const depthPenalty = lowerPath.split("/").length * 0.25;
+      scored.push({ file, score: score - depthPenalty });
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit).map((s) => s.file);
+}

package/src/core/session.js

@@ -0,0 +1,108 @@
+// Local session tracking.
+//
+// TokenPilot keeps a lightweight record of the prompts analyzed this session in
+// a JSON file under the user's home directory. This powers `tokenpilot stats`
+// and, later, dashboard sync. Everything is local and append-only within a
+// session; `reset` starts a fresh one.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dollarsFor, DEFAULT_PROVIDER } from "../config.js";
+
+const DIR = join(homedir(), ".tokenpilot");
+const FILE = join(DIR, "session.json");
+
+function emptySession() {
+  return {
+    id: `sess_${Date.now().toString(36)}`,
+    startedAt: new Date().toISOString(),
+    provider: DEFAULT_PROVIDER,
+    prompts: [],
+  };
+}
+
+export function load() {
+  try {
+    if (!existsSync(FILE)) return emptySession();
+    const data = JSON.parse(readFileSync(FILE, "utf8"));
+    if (!data || !Array.isArray(data.prompts)) return emptySession();
+    return data;
+  } catch {
+    return emptySession();
+  }
+}
+
+export function save(session) {
+  try {
+    if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true });
+    writeFileSync(FILE, JSON.stringify(session, null, 2), "utf8");
+    return true;
+  } catch {
+    return false; // tracking is best-effort; never block the user
+  }
+}
+
+export function reset() {
+  const fresh = emptySession();
+  save(fresh);
+  return fresh;
+}
+
+/**
+ * Record one analyzed prompt into the current session.
+ * @param {object} entry { prompt, breadthScore, rating, projectedTokens,
+ *                          optimizedTokens, savedTokens }
+ */
+export function record(entry) {
+  const session = load();
+  session.prompts.push({
+    at: new Date().toISOString(),
+    prompt: entry.prompt,
+    breadthScore: entry.breadthScore,
+    rating: entry.rating,
+    projectedTokens: entry.projectedTokens,
+    optimizedTokens: entry.optimizedTokens,
+    savedTokens: entry.savedTokens,
+  });
+  save(session);
+  return session;
+}
+
+export function summarize(session = load(), provider = session.provider) {
+  const prompts = session.prompts || [];
+  const total = prompts.length;
+  const projected = prompts.reduce((s, p) => s + (p.projectedTokens || 0), 0);
+  const optimized = prompts.reduce((s, p) => s + (p.optimizedTokens || 0), 0);
+  const saved = prompts.reduce((s, p) => s + (p.savedTokens || 0), 0);
+  const broad = prompts.filter((p) => p.rating === "broad").length;
+
+  const mostExpensive = [...prompts]
+    .sort((a, b) => (b.projectedTokens || 0) - (a.projectedTokens || 0))
+    .slice(0, 3);
+  const biggestSavers = [...prompts]
+    .sort((a, b) => (b.savedTokens || 0) - (a.savedTokens || 0))
+    .slice(0, 3);
+
+  return {
+    id: session.id,
+    startedAt: session.startedAt,
+    provider,
+    total,
+    broad,
+    projectedTokens: projected,
+    optimizedTokens: optimized,
+    savedTokens: saved,
+    savedPct: projected > 0 ? Math.round((saved / projected) * 100) : 0,
+    dollarsSaved: dollarsFor(saved, provider),
+    mostExpensive,
+    biggestSavers,
+  };
+}
+
+export const SESSION_FILE = FILE;

package/src/core/tokenizer.js

@@ -0,0 +1,36 @@
+// Lightweight token estimator.
+//
+// Real tokenizers (tiktoken, the Claude tokenizer) require large vocab files or
+// a network call. For a terminal companion we want an instant, offline, "close
+// enough" estimate. We blend two well-known heuristics and take the larger,
+// which tracks actual BPE token counts within ~10-15% for typical English +
+// code prompts:
+//
+//   • ~4 characters per token
+//   • ~0.75 tokens per word (i.e. ~1.33 words per token)
+//
+// Code and punctuation tokenize denser than prose, so we nudge the estimate up
+// when the text is punctuation-heavy.
+
+export function estimateTokens(text) {
+  if (!text) return 0;
+  const trimmed = String(text).trim();
+  if (!trimmed) return 0;
+
+  const chars = trimmed.length;
+  const words = trimmed.split(/\s+/).filter(Boolean).length;
+
+  const byChars = chars / 4;
+  const byWords = words / 0.75;
+
+  // Punctuation / symbol density bumps token count (each often its own token).
+  const punctuation = (trimmed.match(/[^\w\s]/g) || []).length;
+  const punctuationBoost = punctuation * 0.5;
+
+  return Math.max(1, Math.round(Math.max(byChars, byWords) + punctuationBoost));
+}
+
+// Convenience: estimate tokens for many strings at once.
+export function estimateTokensBatch(texts) {
+  return texts.reduce((sum, t) => sum + estimateTokens(t), 0);
+}

package/src/ui/colors.js

@@ -0,0 +1,39 @@
+// Zero-dependency ANSI color helpers.
+// Colors are disabled automatically when output is not a TTY, when NO_COLOR is
+// set, or when TOKENPILOT_NO_COLOR is set — so piped output stays clean.
+
+const enabled =
+  Boolean(process.stdout.isTTY) &&
+  !process.env.NO_COLOR &&
+  !process.env.TOKENPILOT_NO_COLOR;
+
+const ESC = String.fromCharCode(27); // the ASCII escape character
+const code = (open, close) => (text) =>
+  enabled ? `${ESC}[${open}m${text}${ESC}[${close}m` : String(text);
+
+export const colors = {
+  enabled,
+  bold: code(1, 22),
+  dim: code(2, 22),
+  italic: code(3, 23),
+  underline: code(4, 24),
+
+  red: code(31, 39),
+  green: code(32, 39),
+  yellow: code(33, 39),
+  blue: code(34, 39),
+  magenta: code(35, 39),
+  cyan: code(36, 39),
+  gray: code(90, 39),
+
+  bgRed: code(41, 49),
+  bgYellow: code(43, 49),
+  bgGreen: code(42, 49),
+};
+
+// Severity → color mapping used across the UI.
+export const severityColor = {
+  high: colors.red,
+  medium: colors.yellow,
+  low: colors.blue,
+};

package/src/ui/format.js

@@ -0,0 +1,133 @@
+// Terminal rendering for TokenPilot. Boxes, bars, and the analysis report.
+
+import { colors, severityColor } from "./colors.js";
+import { dollarsFor } from "../config.js";
+
+const RATING_STYLE = {
+  focused: { color: colors.green, icon: "✓", label: "FOCUSED" },
+  moderate: { color: colors.yellow, icon: "○", label: "MODERATE" },
+  broad: { color: colors.red, icon: "⚠", label: "BROAD" },
+};
+
+const SEV_ICON = { high: "✕", medium: "!", low: "·" };
+
+export function num(n) {
+  return Number(n).toLocaleString("en-US");
+}
+
+export function money(n) {
+  return `$${n.toFixed(n < 1 ? 4 : 2)}`;
+}
+
+// A compact horizontal meter, e.g. breadth score.
+export function bar(value, max = 100, width = 24) {
+  const filled = Math.round((Math.min(value, max) / max) * width);
+  const color =
+    value >= 55 ? colors.red : value >= 25 ? colors.yellow : colors.green;
+  return color("█".repeat(filled)) + colors.gray("░".repeat(width - filled));
+}
+
+// Wrap text to a width, preserving words.
+export function wrap(text, width = 66, indent = "  ") {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let line = "";
+  for (const w of words) {
+    if ((line + " " + w).trim().length > width) {
+      lines.push(line);
+      line = w;
+    } else {
+      line = (line + " " + w).trim();
+    }
+  }
+  if (line) lines.push(line);
+  return lines.map((l) => indent + l).join("\n");
+}
+
+function rule(char = "─", width = 60) {
+  return colors.gray(char.repeat(width));
+}
+
+// The full analysis report for a single prompt.
+export function renderAnalysis(result, opts = {}) {
+  const { optimize, relevantFiles = [], provider } = opts;
+  const a = result;
+  const style = RATING_STYLE[a.rating] || RATING_STYLE.moderate;
+  const out = [];
+
+  out.push("");
+  out.push(
+    `${style.color(colors.bold(`${style.icon} ${style.label}`))}  ` +
+      colors.gray(`breadth ${a.breadthScore}/100`)
+  );
+  out.push(`  ${bar(a.breadthScore)}`);
+  out.push("");
+
+  // Projected cost line.
+  const dollars = provider ? dollarsFor(a.projectedTokens, provider) : null;
+  out.push(
+    colors.bold("  Projected cost  ") +
+      `~${colors.cyan(num(a.projectedTokens))} tokens` +
+      colors.gray(
+        `  (prompt ${num(a.promptTokens)} + exploration ${num(
+          a.explorationTokens
+        )})`
+      ) +
+      (dollars !== null ? colors.gray(`  ≈ ${money(dollars)}`) : "")
+  );
+
+  // Issues.
+  if (a.issues.length) {
+    out.push("");
+    out.push(colors.bold("  Issues"));
+    for (const issue of a.issues) {
+      const sc = severityColor[issue.severity] || colors.gray;
+      out.push(`  ${sc(SEV_ICON[issue.severity] || "·")} ${issue.message}`);
+      if (issue.hint) out.push(colors.gray(`     → ${issue.hint}`));
+    }
+  } else {
+    out.push("");
+    out.push(colors.green("  ✓ No issues detected — this prompt is well scoped."));
+  }
+
+  // Relevant files (from scan) shown when we have them and the prompt lacked refs.
+  if (relevantFiles.length && !a.hasFileRef) {
+    out.push("");
+    out.push(colors.bold("  Likely-relevant files"));
+    for (const f of relevantFiles) out.push(`  ${colors.magenta("▫")} ${f}`);
+  }
+
+  // Optimized rewrite — only worth showing when it meaningfully helps.
+  if (optimize && optimize.savedTokens < 100) {
+    out.push("");
+    out.push(rule());
+    out.push(
+      colors.green("  ✓ Already well-scoped — no rewrite needed.")
+    );
+  } else if (optimize) {
+    out.push("");
+    out.push(rule());
+    out.push(
+      colors.green(colors.bold("  Suggested prompt")) +
+        colors.gray(
+          `   saves ~${num(optimize.savedTokens)} tokens (${optimize.savedPct}%)`
+        )
+    );
+    out.push("");
+    out.push(colors.green(wrap(optimize.focused.text, 64, "  ")));
+    if (optimize.focused.notes.length) {
+      out.push("");
+      for (const n of optimize.focused.notes) {
+        out.push(colors.gray(`  · ${n}`));
+      }
+    }
+  }
+
+  out.push("");
+  return out.join("\n");
+}
+
+export function banner() {
+  const name = colors.cyan(colors.bold("TokenPilot"));
+  return `${name} ${colors.gray("— focus your prompts, save your tokens")}`;
+}