termlens

  ████████╗███████╗██████╗ ███╗   ███╗██╗     ███████╗███╗   ██╗███████╗
  ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║     ██╔════╝████╗  ██║██╔════╝
     ██║   █████╗  ██████╔╝██╔████╔██║██║     █████╗  ██╔██╗ ██║███████╗
     ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║     ██╔══╝  ██║╚██╗██║╚════██║
     ██║   ███████╗██║  ██║██║ ╚═╝ ██║███████╗███████╗██║ ╚████║███████║
     ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝

┌──────────────────────────────────────────────┐       ┌──────────────────────────────────────────────┐
│        BEFORE: WITHOUT TERMLENS              │       │          AFTER: WITH TERMLENS                │
├──────────────────────────────────────────────┤       ├──────────────────────────────────────────────┤
│  PASS src/math.test.ts (1.2s)                │       │  🔍 termlens v0.2.0 [lens: jest]             │
│  PASS src/string.test.ts (0.8s)              │       │  ──────────────────────────────────────────  │
│  PASS src/auth/hash.test.ts (2.1s)           │       │  ✗ FAILED (exit 1) npm test                  │
│  PASS src/database/client.test.ts (3.4s)     │  ──►  │    1 test failure isolated                   │
│  ... [84 passing tests hidden]               │       │                                              │
│  FAIL src/auth/jwt.test.ts (4.1s)            │       │  [#1] src/auth/jwt.test.ts:42:29             │
│    ● should reject expired token signature   │       │      Expected: 401                           │
│      Expected: 401, Received: 200            │       │      Received: 200                           │
│      at Object.<anonymous> (...)             │       │      Code: expect(response.status).toBe(401) │
│      at Promise.then.completed (...)         │       │  ──────────────────────────────────────────  │
│  ... [400 lines of node_modules stack trace] │       │  ⏱️ 842ms │ 📉 1,482 lines → 4 lines (-97.3%)│
│  Test Suites: 1 failed, 10 passed            │       │  Tokens: ~3,840 → ~74 tokens ($0.011 saved)  │
└──────────────────────────────────────────────┘       └──────────────────────────────────────────────┘

# Run Jest / Vitest test suites
npx termlens npm test

# Run Go tests or builds
npx termlens go test ./...

# Run Python Pytest suites or linters (Ruff / Mypy / Flake8)
npx termlens pytest tests/
npx termlens ruff check .

# Run JavaScript / TypeScript linters (ESLint / Biome)
npx termlens npx eslint src/

# Run TypeScript compiler checks
npx termlens tsc --noEmit

# Run C/C++ builds (Make, CMake, GCC, Clang)
npx termlens make -j4

# Run .NET tests or builds
npx termlens dotnet test

# Run Rust Cargo checks or tests
npx termlens cargo test

# Run Docker container builds
npx termlens docker build .

npm install -g termlens
termlens npm test

termlens npm test

termlens -a npm test

### ✗ Command Failed (exit 1): `npm test`
- **Lens**: jest
- **Summary**: 1 test failure isolated

**Isolated Failures:**
1. **`src/auth/jwt.test.ts:42:29`**: Test assertion failure
   - Expected: `401`
   - Received: `200`

*(termlens reduced 1482 lines to 4 lines: -97.3% tokens)*

termlens -j npm test

{
  "mcpServers": {
    "termlens": {
      "command": "npx",
      "args": ["-y", "termlens", "--mcp"]
    }
  }
}

termlens --list-lenses

Found 42 errors across 18 files. Clustered into 2 root patterns:
  [Cluster 1] TS2304: Cannot find name 'User' (38 occurrences)
      Exemplar: src/auth/jwt.ts:14:2
      Locations: src/api/users.ts:8:5, src/routes/auth.ts:22:10 (+36 more)
  [Cluster 2] TS2345: Argument of type 'string' is not assignable to 'number' (4 occurrences)
      Exemplar: src/utils/math.ts:89:12

termlens -a -q npm test
# Output: ✓ Passed

termlens --ci npm test
# Emits: ::error file=src/auth.ts,line=42,col=3,title=Test Failure::Expected 401, got 200

termlens --init

{
  "defaultLens": "auto",
  "tailLines": 8,
  "clusterErrors": true,
  "maxErrors": 10,
  "quietSuccess": false,
  "customLenses": [
    {
      "name": "rubocop",
      "matchCommand": "rubocop",
      "errorPattern": "([^:]+):(\\d+):(\\d+):\\s+([CWE]):\\s+(.*)",
      "fileGroup": 1,
      "lineGroup": 2,
      "colGroup": 3,
      "codeGroup": 4,
      "messageGroup": 5
    }
  ]
}

termlens -a -o report.md npm test

flowchart TD
    A["User / Agent Command<br/>(termlens npm test)"] --> B["Child Process Spawn<br/>(PTY / stdio stream)"]
    B --> C["Rolling RingBuffer<br/>(Memory bounded: 1000 lines)"]
    C --> D["ANSI & Carriage-Return Normalizer<br/>(Strips spinners & cursor escapes)"]
    D --> E{"Semantic Lens Matcher"}
    E -->|"Jest / Vitest"| L1["JestVitestLens"]
    E -->|"Python Pytest"| L2["PytestLens"]
    E -->|"TypeScript Compiler"| L3["TscLens"]
    E -->|"Rust Cargo"| L4["CargoLens"]
    E -->|"Docker Build"| L5["DockerLens"]
    E -->|"Go Toolchain"| L6["GolangLens"]
    E -->|"Python Linters"| L7["PythonLintLens"]
    E -->|"JS / TS Linters"| L8["JsLintLens"]
    E -->|"C / C++ Compiler"| L9["ClangLens"]
    E -->|".NET C#"| L10["DotnetLens"]
    E -->|"User Defined"| L11["CustomLens"]
    E -->|"Fallback"| L12["GenericLens"]
    L1 & L2 & L3 & L4 & L5 & L6 & L7 & L8 & L9 & L10 & L11 & L12 --> F["Error Isolator & Parser"]
    F --> CL["Smart Clustering Engine<br/>(Deduplication & Similarity Grouping)"]
    CL --> TM["Telemetry & Cost Savings<br/>(Tokens Saved & USD Valuation)"]
    TM --> G["Human ANSI Terminal Card<br/>(Default CLI)"]
    TM --> H["Agent Markdown (<100 tokens)<br/>(--agent / -a)"]
    TM --> I["JSON Telemetry<br/>(--json / -j)"]
    TM --> CI["GitHub Actions Annotations<br/>(--ci)"]
    TM --> J["Model Context Protocol<br/>(--mcp stdio)"]
    TM --> FO["File Output Stream<br/>(-o / --output)"]

Usage: termlens [options] <command...>
       cat noisy.log | termlens [options]

Options:
  -a, --agent              Format output as ultra-compact Markdown for AI agent prompts
  -j, --json               Format output as structured JSON
  -l, --lens <name>        Explicitly specify a lens (jest, pytest, tsc, cargo, docker, go, python-lint, js-lint, clang, dotnet, generic)
  --tail <lines>           Number of raw tail lines to retain in output (default: 8)
  -q, --quiet-success      Emit minimal zero-token output on clean command execution
  --max-errors <number>    Maximum number of errors to report before truncating
  --no-cluster             Disable error clustering and deduplication
  --ci                     Generate GitHub Actions workflow command annotations
  -o, --output <file>      Write compacted output directly to a file
  --init                   Scaffold a starter termlens.config.json file
  --raw                    Pass through uncompressed output (dry/debug mode)
  --mcp                    Start the Model Context Protocol (MCP) stdio server
  --list-lenses            List all registered semantic lenses
  -v, --version            Display current version
  -h, --help               Display help manual

# Build TypeScript
npm run build

# Run unit, integration, benchmark, and MCP tests
npm test