cto-ai-cli 1.3.0 → 3.0.1

package/README.md

@@ -1,326 +1,252 @@
-# 🔧 CTO — Claude Token Optimizer
+# CTO — Your AI is reading too much code. We fix that.
 
-> Optimize your token usage with Claude Code without modifying your projects.
+> **Early access** — This is a test version. We'd love your feedback.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org)
-
-CTO analyzes your codebase, classifies files into **hot/warm/cold tiers** based on recency and dependency structure, and generates optimized `CLAUDE.md` and `.claudeignore` files — so Claude Code reads only what matters. Includes an **MCP Server** for native Claude Code integration and **enterprise-grade security** with secret detection, audit logging, and data integrity verification.
-
-## ✨ Features
-
-- **🔍 Token Analysis** — Scan your project and estimate token usage per file (chars/4 or tiktoken)
-- **📊 File Tiering** — Classify files as 🔥 hot / 🌡️ warm / ❄️ cold based on recency + AST analysis
-- **🧠 AST Analysis** — Dependency graph, hub file detection, cyclomatic complexity via ts-morph
-- **🎯 Smart Model Routing** — Suggests Opus/Sonnet/Haiku based on file complexity
-- **📝 CLAUDE.md Generation** — Auto-generate context files optimized for Claude Code
-- **🚫 .claudeignore Generation** — Keep cold files out of Claude's context
-- **👁️ Watch Mode** — Auto-recalculate tiers and regenerate artifacts when files change
-- **📝 Session Tracking** — Track Claude Code sessions, log file reads, detect waste patterns
-- **📊 Dashboard** — Terminal dashboard with metrics, savings ratio, and suggestions
-- **📈 Reports** — Weekly reports, project comparison, CSV/JSON export
-- **🔌 MCP Server** — Native Claude Code integration via Model Context Protocol
-- **📋 Prompt Templates** — Pre-built prompts optimized by task type (debug, review, refactor, test)
-- **🔐 Secret Detection** — Scans for API keys, tokens, passwords, connection strings before generating artifacts
-- **📝 Audit Logging** — Immutable, integrity-verified audit trail of every CTO action
-- **🛡️ Data Integrity** — SHA-256 verification of artifacts, backups, and sessions
-- **🪧 CI/CD Validation** — `cto validate` for automated security checks in pipelines
-- **✂️ Smart Context Pruning** — Signatures-only for warm files, skeleton for cold — 60-80% token savings
-- **🔀 Git-Aware Tiering** — Uses `git diff`/blame for precise tier classification, auto-promotes changed files
-- **💰 Cost Estimation** — Real dollar savings per session, weekly/monthly/yearly projections
-- **🎯 Token Budget Optimizer** — Knapsack algorithm selects optimal files within a token budget
-- **🤖 Multi-AI Generator** — Generate context for Claude, Cursor, Copilot, and Gemini
-- **🔀 PR Context** — Focused context for code reviews with dependency-aware file selection
-- **💡 Explain** — Transparent tier reasoning showing all factors per file
-- **🎯 Prompt Engineering** — Enhanced prompts with role priming, chain-of-thought, constraints, and anti-hallucination
-- **🧠 Smart Model Routing** — Auto-select Haiku/Sonnet/Opus based on task complexity
-- **📜 Specification-Driven Development** — Extract specs, generate contract documents, validate implementations
-- **📁 Project-Local Config** — `cto init --local` creates `.cto/` in project root, shareable via git
-- **🔄 Reversible** — Every apply creates a backup; revert anytime
-- **📦 Autocontained** — All CTO data in `~/.config/cto/` or `.cto/` in project root
-- **⚙️ Configurable** — YAML config with global, per-project, and local overrides
-
-## 📦 Installation
+[![Tests](https://img.shields.io/badge/tests-433_passing-brightgreen.svg)](#)
+
+## Try it now (zero install)
 
 ```bash
-# From source
-git clone <repo-url>
-cd cto
-npm install
-npm run build
-npm link
+npx cto-score
+```
+
+That's it. Run it on any project. You'll see something like this:
 
-# Coming soon: npm i -g @cto/cli
+```
+  ⚡ cto-score — analyzing your project...
+
+  ╔══════════════════════════════════════════════════╗
+  ║                                                  ║
+  ║   🟢 Context Score™  87  / 100   Grade: A-      ║
+  ║                                                  ║
+  ║   Efficiency     ███████████████░░░░░  74%       ║
+  ║   Coverage       ████████████████████ 100%       ║
+  ║   Risk Control   ████████████████████ 100%       ║
+  ║                                                  ║
+  ║   💰 vs. Sending Everything:                     ║
+  ║   Tokens saved: 289K (85%)                       ║
+  ║   Monthly savings: ~$695                         ║
+  ║                                                  ║
+  ╚══════════════════════════════════════════════════╝
+
+  Scanned in 11.7s · 177 files · 340K tokens
 ```
 
-## 🚀 Quick Start
+Run `npx cto-score --benchmark` to see how CTO compares to naive (alphabetical) and random file selection.
 
-```bash
-# 1. Initialize CTO (interactive wizard)
-cto init
+No data leaves your machine. No API keys. MIT licensed.
 
-# 2. Analyze your project
-cto analyze /path/to/project
+---
 
-# 3. View file tiers
-cto tiers /path/to/project
+## What problem does CTO solve?
 
-# 4. Generate optimized artifacts
-cto generate /path/to/project
+When you ask an AI assistant to help with code, it needs context — your files. The question is: **which files?**
 
-# 5. Preview what would change
-cto diff claude-md /path/to/project
+**Most tools today** either send everything (expensive, noisy) or pick files based on what's open (misses dependencies). Neither approach is great.
 
-# 6. Apply to your project (with confirmation)
-cto apply claude-md /path/to/project
-```
+**CTO analyzes your project** — dependencies, file importance, risk of excluding each file — and picks the best subset that fits your token budget. It's like a smart assistant that knows which files matter for each task.
 
-## 📖 Commands
-
-| Command | Description |
-|---------|-------------|
-| `cto init` | Interactive setup wizard |
-| `cto analyze [path]` | Analyze token usage (read-only) |
-| `cto tiers [path]` | Show hot/warm/cold file tiers |
-| `cto generate [path]` | Generate CLAUDE.md & .claudeignore |
-| `cto show <artifact>` | Preview a generated artifact |
-| `cto diff <artifact>` | Show what would change before applying |
-| `cto apply <artifact>` | Apply artifact to project (with backup) |
-| `cto revert [artifact]` | Undo last apply using backup |
-| `cto clean [path]` | Remove all CTO data for a project |
-| `cto prompts [path]` | Show/generate optimized prompt templates |
-| `cto config [path]` | Show current configuration |
-| `cto deps [path]` | Show dependency graph, hub files & complexity |
-| `cto watch [path]` | Watch for changes, auto-recalculate tiers |
-| `cto session start\|end\|current\|list\|log` | Track Claude Code sessions |
-| `cto dashboard [path]` | Terminal dashboard with metrics |
-| `cto report weekly\|project\|export` | Usage reports and data export |
-| `cto doctor [path]` | Health check & security audit |
-| `cto audit log\|verify\|purge` | View and manage audit trail |
-| `cto validate [path]` | CI/CD validation & secret scan |
-| `cto prune preview\|file` | Smart context pruning preview |
-| `cto costs estimate\|history\|pricing` | Token cost estimation & savings |
-| `cto context budget\|pr` | Budget optimizer & PR-focused context |
-| `cto multi-gen generate\|list` | Generate for Claude/Cursor/Copilot/Gemini |
-| `cto explain <file>` | Explain why a file is in a specific tier |
-| `cto route recommend\|tasks` | Smart model routing per task type |
-| `cto multi-gen generate --enhanced` | Prompt-engineered context generation |
-| `cto sdd extract\|spec\|validate` | Specification-Driven Development |
-| `cto init --local` | Create .cto/ in project root (team-shareable) |
-
-**Artifact types:** `claude-md`, `claudeignore`, `all`
-
-## ⚙️ Configuration
-
-CTO uses YAML config files:
-
-- **Global:** `~/.config/cto/config.yaml`
-- **Per-project:** `~/.config/cto/projects/<hash>/config.yaml`
-
-```yaml
-version: "1.3.0"
-model: sonnet              # sonnet | opus | haiku
-tokenEstimation: tiktoken  # tiktoken (accurate) | chars4 (fast)
-
-tiering:
-  hotDays: 3           # Files modified within N days = hot
-  warmDays: 14         # Files modified within N days = warm
-  hotTokenLimit: 50000
-  warmTokenLimit: 200000
-
-ignoreDirs:
-  - node_modules
-  - .git
-  - dist
-  - build
-
-extensions:
-  code:
-    - ts
-    - tsx
-    - js
-    - py
-  config:
-    - json
-    - yaml
-  docs:
-    - md
-```
+### A simple example
+
+You ask the AI: *"refactor the auth middleware"*
+
+| Approach | What gets sent | Result |
+|----------|---------------|--------|
+| **Send everything** | 340K tokens (all 177 files) | Expensive. AI drowns in irrelevant code. |
+| **Send open files** | Whatever you have open | Might miss types, dependencies, config. |
+| **CTO** | 50K tokens (93 relevant files) | 85% cheaper. Includes types, deps, related files. |
+
+### Why does it matter?
 
-## 📊 How Tiering Works
+We tested something specific: when the AI generates code, does it have the type definitions it needs?
 
-| Tier | Criteria | Action |
-|------|----------|--------|
-| 🔥 **Hot** | Modified within 3 days | Read first, always include |
-| 🌡️ **Warm** | Modified within 14 days | Read if needed |
-| ❄️ **Cold** | Not modified in 14+ days | Skip unless explicitly needed |
+| | CTO | Without CTO |
+|--|-----|-------------|
+| **Type files included** | 5 out of 6 | **0 out of 6** |
+| **TypeScript compiler** | ✅ Compiles | ❌ 4 errors |
 
-CTO supports two token estimation methods:
-- **`chars4`** — Fast estimate at ~4 characters per token (default)
-- **`tiktoken`** — Accurate estimation using Claude's real tokenizer
+We ran this on 5 different tasks. Same result every time. CTO context compiles. Naive context doesn't.
 
-### AST-Enhanced Tiering (v0.5.1+)
+Without type definitions, the AI invents interfaces — wrong property names, wrong shapes. The code doesn't compile. ([Details](#compile-proof))
 
-Beyond recency, CTO uses AST analysis to boost tier priority:
-- **Hub files** (imported by 3+ files) get promoted one tier (cold→warm, warm→hot)
-- **High-complexity files** (cyclomatic complexity >30) get promoted from warm→hot
-- **Model suggestions**: Opus for complex files, Sonnet for moderate, Haiku for simple
+---
 
-The tier thresholds are fully configurable.
+## Getting started
 
-## 🏗️ Architecture
+### Option 1: Quick score (no install)
 
+```bash
+npx cto-score                 # Score your project
+npx cto-score ./my-project    # Score a specific project
+npx cto-score --benchmark     # Compare CTO vs naive vs random
+npx cto-score --json          # Machine-readable output (for CI)
+```
+
+### Option 2: Full install
+
+```bash
+npm install -g cto-ai-cli
+
+cto2 init                                    # Set up for your project
+cto2 analyze                                 # See structure + risk profile
+cto2 interact "refactor the auth middleware"  # Get optimized context for a task
+```
+
+### Option 3: Use with your AI editor (MCP)
+
+CTO works as an [MCP server](https://modelcontextprotocol.io/) — plug it into Claude, Windsurf, or Cursor.
+
+**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "cto2-mcp" }
+  }
+}
 ```
-~/.config/cto/
-├── config.yaml                # Global config
-├── audit/                     # Immutable audit logs
-│   └── audit_YYYYMMDD.json   # Daily audit entries (0600 perms)
-└── projects/
-    └── <project-hash>/
-        ├── config.yaml        # Project-specific overrides
-        ├── analysis.json      # Last analysis results
-        ├── integrity.json     # SHA-256 integrity manifest (0600)
-        ├── artifacts/
-        │   ├── CLAUDE.md      # Generated CLAUDE.md (sanitized)
-        │   └── .claudeignore  # Generated .claudeignore
-        ├── backups/
-        │   ├── manifest.json  # Backup tracking
-        │   └── <backup-files> # Original files before apply
-        └── sessions/
-            ├── current.json   # Active session
-            └── session_*.json # Archived sessions
+
+**Claude Desktop** — add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "node", "args": ["/path/to/dist/mcp/v2.js"] }
+  }
+}
 ```
 
-## 🔐 Security
+Once connected, your AI editor can use tools like `cto_analyze`, `cto_select_context`, `cto_score`, and `cto_benchmark` automatically.
 
-CTO is built with enterprise security requirements in mind.
+---
 
-### Secret Detection
+## How it works (the short version)
 
-Before generating CLAUDE.md, CTO scans for and redacts:
-- **API keys** — OpenAI, Anthropic, generic API keys
-- **Cloud credentials** — AWS access keys, secret keys
-- **Private keys** — RSA, EC, DSA, OpenSSH
-- **Passwords** — Hardcoded passwords, database passwords
-- **Tokens** — GitHub, GitLab, npm, OAuth, bearer tokens
-- **Connection strings** — PostgreSQL, MongoDB, MySQL, Redis, AMQP
-- **Custom patterns** — Define your own regex patterns in config
+1. **Scans** your project — files, imports, dependencies, structure
+2. **Scores** each file — how important is it? What breaks if we exclude it?
+3. **Selects** the best files for your task — within your token budget
+4. **Proves** the result — coverage score, benchmark comparison, cost savings
 
-### Audit Logging
+CTO doesn't use AI for selection. It uses dependency analysis, risk modeling, and optimization algorithms. Same input always produces the same output.
 
-Every CTO action is logged to an immutable audit trail:
-- Each entry includes: timestamp, user, action, project, and details
-- Entries are **integrity-protected** with SHA-256 hashes
-- Tampering is detected with `cto audit verify`
-- Auto-purge after configurable retention period (default: 90 days)
+---
 
-### Data Integrity
+## Real numbers
 
-- **SHA-256 hashes** for all artifacts, backups, and sessions
-- `cto validate` verifies integrity on demand (CI/CD ready)
-- Exits with code 1 on failure — use `--strict` to fail on warnings
+We ran CTO on three open-source projects. No cherry-picking — you can reproduce these with `npx cto-score --benchmark`.
 
-### Secure File Permissions
+| Project | Files | Score | What CTO does |
+|---------|-------|-------|---------------|
+| **Zod** | 441 files, 804K tokens | 92/100 (A) | Selects 64 files, 100% coverage, $1,809/mo savings |
+| **This project** | 177 files, 340K tokens | 87/100 (A-) | Selects 93 files, 100% coverage, $695/mo savings |
+| **Express.js** | 158 files, 171K tokens | 74/100 (B-) | Needs only 895 tokens for full coverage |
 
-- All CTO data files: `0600` (owner read/write only)
-- All CTO directories: `0700` (owner access only)
-- `cto doctor --fix` enforces permissions automatically
+"Coverage" means: all the files that are important for your task are included. "Savings" is estimated based on 800 AI interactions per month.
 
-### CI/CD Integration
+<details>
+<summary><b>Detailed comparison: CTO vs Naive vs Random</b></summary>
 
-```bash
-# Add to your CI pipeline
-cto validate /path/to/project --strict --json
+> Budget: 50K tokens · Task: "refactor the core module"
 
-# Fails on: leaked secrets, corrupted data, stale artifacts
-```
+| Project | Strategy | Files | Tokens | Coverage | High-Risk Included |
+|---------|----------|-------|--------|----------|-------------------|
+| **Zod** | **CTO** | 64 | 50.0K | **100%** | **6/6** |
+| | Naive (alphabetical) | 71 | 50.0K | 16% | 2/6 |
+| | Random | 45 | 50.0K | 10% | 1/6 |
+| **CTO** | **CTO** | 163 | 47.4K | **100%** | **11/11** |
+| | Naive | 25 | 50.0K | 15% | 0/11 |
+| | Random | 38 | 50.0K | 23% | 6/11 |
+| **Express** | **CTO** | 158 | 0.9K | **100%** | n/a |
+| | Naive | 64 | 50.0K | 41% | n/a |
+| | Random | 61 | 50.0K | 39% | n/a |
 
-## 🔒 Principles
+**Note:** "Naive" means alphabetical file order (a common default). "Random" is random selection. These are simple baselines — real-world tools like Cursor use smarter heuristics, so we don't claim CTO beats them. We just show the difference between informed and uninformed selection.
 
-| Principle | Guarantee |
-|-----------|-----------|
-| 🔒 **Transparent** | Zero files created inside your project unless you explicitly `apply` |
-| 📖 **Read-only by default** | Analysis never modifies anything |
-| 🔄 **Reversible** | Every `apply` creates a backup, every change can be reverted |
-| 📦 **Autocontained** | `~/.config/cto/` is the only location CTO writes to |
-| 🚫 **No secrets leak** | All generated artifacts are sanitized for secrets |
-| 📝 **Auditable** | Every action is logged with tamper-proof integrity hashes |
-| ⚡ **Minimal deps** | No databases, no Docker, no external services |
-| 🎯 **Quality first** | Optimizing tokens ≠ losing context |
+</details>
 
-## 🧪 Development
+<details id="compile-proof">
+<summary><b>Compile Proof: real TypeScript compiler output</b></summary>
 
-```bash
-# Install dependencies
-npm install
+We ran the actual `tsc` compiler to verify this isn't just theory.
 
-# Build
-npm run build
+**How it works:**
+1. Copy only the selected files (CTO or naive) to a temp directory
+2. Generate TypeScript code that imports and uses the project's types
+3. Run `tsc --noEmit`
+4. Count real compiler errors
 
-# Run tests
-npm test
+| Task | CTO | Naive | Naive missing |
+|------|-----|-------|--------------|
+| Refactor selector | ✅ 0 errors | ❌ 4 errors | All type files |
+| Optimize risk scoring | ✅ 0 errors | ❌ 4 errors | All type files |
+| MCP error handling | ✅ 0 errors | ❌ 4 errors | All type files |
+| Cache invalidation | ✅ 0 errors | ❌ 4 errors | All type files |
+| Add semantic tool | ✅ 0 errors | ❌ 4 errors | All type files |
 
-# Watch mode
-npm run test:watch
+The naive selection (alphabetical) consistently misses all type definition files. The compiler output:
 
-# Type check
-npm run typecheck
+```
+error TS2307: Cannot find module './src/types/engine.js'
+error TS2307: Cannot find module './src/types/config.js'
+error TS2307: Cannot find module './src/types/govern.js'
+error TS2307: Cannot find module './src/types/interact.js'
 ```
 
-## 🔌 MCP Server
+Without these files, the AI has to guess the shape of `AnalyzedFile`, `ContextSelection`, `TaskType`, etc. It will get them wrong.
 
-CTO includes a Model Context Protocol server for native Claude Code integration.
+</details>
 
-### Setup
+---
 
-Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
+## What you can do with CTO
 
-```json
-{
-  "mcpServers": {
-    "cto": {
-      "command": "cto-mcp",
-      "args": []
-    }
-  }
-}
-```
+| Use case | How |
+|----------|-----|
+| **Score your project** | `npx cto-score` |
+| **Compare strategies** | `npx cto-score --benchmark` |
+| **Get optimized context for a task** | `cto2 interact "your task"` |
+| **PR-focused context** | `cto2 interact --pr "review this PR"` |
+| **Use in your AI editor** | Add MCP server (see setup above) |
+| **Use in CI/CD** | GitHub Action posts score on every PR |
+| **Use as an API** | `cto2-api` starts an HTTP server |
+| **JSON output (scripting)** | `npx cto-score --json` |
+
+---
+
+## Honest limitations
 
-### Available Tools
+This is an early test version. Here's what we know:
 
-| Tool | Description |
-|------|-------------|
-| `cto_analyze_project` | Analyze project token usage and tier breakdown |
-| `cto_get_hot_files` | Get hot-tier files (read these first) |
-| `cto_should_read_file` | Check if a file is hot/warm/cold with recommendation |
-| `cto_get_context` | Get the optimized CLAUDE.md context |
-| `cto_session_log` | Start/end sessions and log file reads |
-| `cto_get_prompt` | Get an optimized prompt template |
-| `cto_dashboard` | Get dashboard metrics (sessions, tokens, savings) |
+- **TypeScript/JavaScript projects work best.** We support other languages (Python, Go, Rust, Java) for basic analysis, but TypeScript gets the deepest understanding.
+- **Our benchmarks use simple baselines** (alphabetical, random). We haven't compared against Cursor's or Copilot's internal context selection.
+- **The savings numbers are estimates** based on average API pricing. Your actual savings depend on your model, pricing tier, and usage patterns.
+- **We need more projects to test on.** If you try it and share your score, that helps us a lot.
 
-### MCP Resources
+---
 
-- `cto://context/{projectPath}` — Project context as markdown
+## What's next
 
-### MCP Prompts
+We're working on:
+- **More language support** — deeper analysis for Python and Go
+- **VS Code extension** — see risk scores and context suggestions inline
+- **Model-specific optimization** — different context for GPT-4 vs Claude vs Gemini
+- **Team features** — share learned patterns across your team
+- **Your feedback** — [open an issue](https://github.com/cto-ai/cto-ai-cli/issues) or reach out
 
-- `optimize-task` — Optimized prompt for a task with minimal token usage
-- `review-code` — Optimized prompt for code review
+---
 
-## 🗺️ Roadmap
+## For contributors
+
+```bash
+git clone <repo-url>
+cd cto
+npm install
+npm run build
+npm test          # 433 tests
+npm run typecheck # strict TypeScript
+```
 
-- [x] **v0.5.0** — TypeScript CLI with full analysis, tiering, generation, apply/revert
-- [x] **v0.5.1** — AST-based analysis (ts-morph), tiktoken integration, dependency graph
-- [x] **v0.5.2** — Watch mode with chokidar, auto-regeneration, tier change notifications
-- [x] **v0.7.x** — Session tracking, terminal dashboard, weekly reports, metrics export
-- [x] **v0.9.x** — MCP Server with 7 tools, resources, and prompt templates
-- [x] **v1.0.0** — Enterprise security: secret detection, audit logging, integrity verification, CI/CD validation
-- [x] **v1.1.0** — Smart context pruning, git-aware tiering, cost estimation in real dollars
-- [x] **v1.2.0** — Token budget optimizer, multi-AI generator, PR context, explain command
-- [x] **v1.3.0** — Smart model routing, prompt engineering, SDD, project-local config
-- [ ] **v1.x+** — Plugin system, GitHub Action, VS Code extension
+Full CLI docs, MCP server setup, API server, and programmatic API are documented in [DOCS.md](DOCS.md).
 
-## 📄 License
+## License
 
 [MIT](LICENSE)