lakonai 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bargadev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+<p align="center">
+  <img src="./assets/logo.svg" width="140" alt="lakon" />
+</p>
+
+<h1 align="center">lakon</h1>
+
+<p align="center">
+  <strong>Cut LLM tokens by up to 94% — without losing a single identifier.</strong>
+</p>
+
+<p align="center">
+  <em>Spartan replies for AI agents. Less words. Win wars.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/lakon"><img src="https://img.shields.io/npm/v/lakon?color=0F0F0F&label=npm" alt="npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F0F0F" alt="MIT" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-0F0F0F" alt="node ≥18" />
+  <img src="https://img.shields.io/badge/deps-0-0F0F0F" alt="zero dependencies" />
+  <img src="https://img.shields.io/badge/agents-6-0F0F0F" alt="6 AI agents" />
+</p>
+
+<p align="center">
+  One command. <strong>Three fronts</strong>: terse model output · filtered shell output · blocked junk reads.<br/>
+  Plus session-level token tracking and one-day update notifications.<br/>
+  Works across <strong>Claude Code, Codex, Cursor, Windsurf, Cline, Gemini CLI</strong>.
+</p>
+
+---
+
+## At a glance — measured savings
+
+| Command                          | Raw tokens | Filtered | Saved   |
+|----------------------------------|-----------:|---------:|--------:|
+| `git log -p -10`                 |     10,497 |       78 | **-94%** |
+| `ls -laR` (deep directory)       |     23,624 |      117 | **-94%** |
+| `git diff HEAD~5`                |     13,230 |      798 | **-89%** |
+| `git log --stat -50`             |      4,845 |      439 | **-86%** |
+| `git status`                     |         17 |        1 | **-89%** |
+| `Read pnpm-lock.yaml`            |    ~56,000 | **blocked** | **-95%** |
+| `Grep` (auto `head_limit`)       |  unbounded | 30 matches | **capped** |
+
+Conservative numbers — peaks go higher in practice. Run `lakon inspect <cmd>` on your own commands to measure.
+
+---
+
+## The story behind the name
+
+In 346 BC, Philip II of Macedon — father of Alexander the Great — sent the Spartans a message:
+
+> *"If I invade Lakonía, I will raze your cities to the ground."*
+
+The Spartans replied with a single word:
+
+> *"If."*
+
+That region was **Lakonía**. Its people gave the English language the word **laconic** — using as few words as possible. They didn't waste breath, didn't waste arrows, didn't waste anything.
+
+Your AI coding agent does. It opens with *"Sure! I'd be happy to help…"*, repeats your question back, and explains what the diff already shows. It reads `git log` in full when one line per commit would do. Every wasted token is a soldier you didn't need to send.
+
+**lakon trims both sides.**
+
+---
+
+## Three fronts. One install.
+
+| Front                          | Wasted tokens look like…                              | lakon fixes it by…                                                                  |
+|--------------------------------|-------------------------------------------------------|-------------------------------------------------------------------------------------|
+| **Output** (the model)         | *"Great question! Let me explain…"*                   | Installing a terse-response rule. No preamble, no recap, no restating.              |
+| **Input** (your shell tools)   | `git log` dumping 1.8 k tokens of author metadata     | Wrapping `git`/`ls`/`grep`/`cat`/`tree`/`head`/`tail` and compressing before context. |
+| **Reads** (file ingestion)     | Agent runs `Read` on `pnpm-lock.yaml` → 80 k of nothing | A `PreToolUse` hook on `Read` blocks lockfiles & `node_modules`, caps files >800 lines. |
+| **Search** (Grep tool)         | `Grep` returns 800 matches and you re-read every one  | A `PreToolUse` hook on `Grep` auto-caps `head_limit` at 30 with a one-shot hint.        |
+| **Analysis** (the rule)        | `Read` 5k of logs to count errors in your head        | "Think in code" — write `node -e '…filter…count'`, consume only the answer.            |
+
+Other tools stop at one front. lakon does all three transparently — your agent doesn't have to remember anything.
+
+---
+
+## Quick start
+
+```bash
+npm install -g lakon
+lakon install
+```
+
+That's it. `lakon install` configures your **global** agents — Claude Code, Codex, Gemini CLI — by writing rule blocks under `~/` only. It never touches your current directory by default.
+
+Working inside a repo and want **per-project** rules (Cursor, Windsurf, Cline)? Add `--here`:
+
+```bash
+cd path/to/your/repo
+lakon install --here       # globals + per-project rules in this dir
+```
+
+From the next session forward your agent:
+
+1. **Responds tersely** — no preamble, no restating, no recap. (rule in `CLAUDE.md` / equivalent)
+2. **Has its `Bash` calls auto-rewritten** — `PreToolUse` hook intercepts `git`/`ls`/`cat`/`grep`/etc and prefixes them with `lakon` transparently.
+3. **Has its `Read` calls guarded** — a second hook denies `node_modules/`, lockfiles, and build artifacts (with a hint to `grep` instead), and auto-caps reads over 800 lines.
+4. **Has its `Grep` calls capped** — a third hook auto-sets `head_limit` to 30 if you didn't, with a once-per-session hint to use `output_mode:"count"` for tallies.
+5. **Is told to "think in code"** — for any count/filter/parse task, the rule pushes the agent toward a one-shot `node -e` (or `awk`) script that consumes the data so the agent consumes only the answer.
+6. **Logs per-turn LLM token usage** — a `Stop` hook records `input_tokens` / `output_tokens` / `cache_read` after each model turn so `lakon gain` shows model-side savings alongside shell-side savings.
+7. **Tells you about new versions** — a `SessionStart` hook checks npm once per day and surfaces a `lakon X.Y.Z available` notice inside the session (opt-out: `LAKON_NO_UPDATE_CHECK=1`).
+
+You'll see savings stack up immediately in `lakon gain`.
+
+> Hooks are currently Claude Code-only (the only platform with documented hook APIs). For Codex/Cursor/Windsurf/Cline/Gemini, the rule asks the model to grep-before-Read and use the `lakon` prefix itself.
+
+> **Worried?** Every install backs up the target file first. `lakon revert` puts it back byte-for-byte.
+
+---
+
+## Use the filter directly
+
+The CLI works as a standalone tool too. Run any shell command through `lakon` (or the short alias `lak`) to filter its output:
+
+```bash
+lakon git status        # compressed git status
+lakon git log -50       # one line per commit (hash + subject)
+lakon git diff          # only +/- lines, no noise
+lakon ls -la            # size + name only
+lakon grep -r foo src/  # truncates at 40 matches
+```
+
+Unsupported commands run unchanged.
+
+---
+
+## See your savings
+
+```bash
+lakon gain
+```
+
+```
+lakon  — savings this week:  36.4k tok saved across 512 shell calls (67%)
+
+shell + read/grep guards  (tokens filtered before context)
+  win    calls       before          after          saved       %
+  1h       12      1.2k tok       380 tok        820 tok   68%
+  24h      87      9.8k tok      3.1k tok       6.7k tok   68%
+  7d      512     54.2k tok     17.8k tok      36.4k tok   67%
+  30d    2104    241.0k tok     79.2k tok     161.8k tok   67%
+  all    2104    241.0k tok     79.2k tok     161.8k tok   67%
+
+llm output  (model tokens — terse style trims this side)
+  win    turns       input         output          cache-read
+  1h        4       2.1k tok       320 tok      48.7k tok
+  24h      38      18.4k tok      2.6k tok     412.2k tok
+  7d      210     102.5k tok     14.1k tok     2.3M tok
+
+top commands  (all time)
+  git       812x   saved 124.3k tok  72%
+  ls        541x   saved  18.2k tok  58%
+  grep      339x   saved  12.0k tok  65%
+```
+
+The top block measures **input savings** (what filtered shell + guards prevented from entering context). The `llm output` block measures **model-side activity** so you can see verbosity dropping over time (and cache hits climbing). Set `LAKON_COLOR=1`/`0` (or `NO_COLOR=1`) to force/disable ANSI colors when piping.
+
+### Inspect a single command
+
+```bash
+lakon inspect git log
+```
+
+```
+cmd:      git log
+raw:      1234 tokens (8127 bytes)
+filtered: 187 tokens (1240 bytes)
+saved:    85%
+```
+
+---
+
+## Commands
+
+| Command                          | What it does                                                          |
+|----------------------------------|-----------------------------------------------------------------------|
+| `lakon install`                  | Install rule for detected GLOBAL agents only (no CWD writes)          |
+| `lakon install --here`           | Globals + per-project rules (Cursor/Windsurf/Cline) in current dir    |
+| `lakon install --only <p>`       | Install just one platform by id (any scope)                           |
+| `lakon uninstall`                | Strip the lakon block from each config (keeps your other content)     |
+| `lakon revert [--only <p>]`      | Restore each config to its pre-install state from backup              |
+| `lakon backups`                  | Show backup history per platform                                      |
+| `lakon list`                     | Show supported platforms and which are detected                       |
+| `lakon <cmd> [args]`             | Run a command, filter its output, track savings                       |
+| `lakon gain`                     | Show savings by hour / day / week / month / all-time + session totals |
+| `lakon inspect <cmd>`            | Run once and show raw-vs-filtered (no tracking)                       |
+| `lakon reset`                    | Wipe the savings log                                                  |
+| `lakon version` / `--version` / `-v` | Print the installed lakon version                                 |
+
+`lak` is the short alias for `lakon` — same behavior.
+
+---
+
+## Supported filters
+
+| Command                | What it does                                                      |
+|------------------------|-------------------------------------------------------------------|
+| `git log`              | One line per commit (`<hash> <subject>`), capped at 50            |
+| `git status`           | Drops hint paragraphs, separates changed vs untracked             |
+| `git diff` / `show`    | Only `+`/`-`/`@@` lines, drops `index`/`---`/`+++`, cap 120 lines |
+| `ls -la` / `tree`      | `<size>\t<name>` (drops perms / dates / link targets), cap 60     |
+| `cat`                  | Collapses blank-line runs, cap 200 lines                          |
+| `head` / `tail`        | Cap 50 lines                                                      |
+| `grep` / `rg` / `ag`   | Cap 15 matches with "tighten the pattern" hint                    |
+
+Unsupported commands run unchanged (passthrough), still tracked at 0 % savings.
+
+### Read tool guard (Claude Code)
+
+The `Read` hook automatically:
+
+- **Denies** paths under `node_modules/`, `vendor/`, `dist/`, `build/`, `target/`, `.next/`, `.nuxt/`, `.turbo/`, `.svelte-kit/`, `.parcel-cache/`, `.vercel/`, `coverage/`, `__pycache__/`, `.venv/`, `.git/objects/`, `__snapshots__/`, `.ipynb_checkpoints/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `.tox/`, `cypress/screenshots/`, `cypress/videos/`, `playwright-report/`, `test-results/`, `.idea/`, `.vscode/`, `tmp/`
+- **Denies** lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `go.sum`, `*.lock`)
+- **Denies** build artifacts (`*.min.js`, `*.min.css`, `*.min.mjs`, `*.tsbuildinfo`, `*.map`, `*.log`, `*.pyc`, `*.pyo`, `*.so`, `*.o`, `*.a`, `*.dylib`, `*.dll`, `*.exe`, `*.class`, `*.wasm`)
+- **Caps** files over 800 lines at 800 (with hint to `Read` again with `offset` for more, or `grep -n` for the symbol you need)
+
+Each deny returns a one-line reason the model reads, so it knows to `grep -n` the symbol instead.
+
+### Grep tool guard (Claude Code)
+
+The `Grep` hook auto-sets `head_limit` to **30** when the agent didn't pass one. First call per 4-hour window includes a one-line hint suggesting `output_mode:"count"` for tallies; subsequent calls cap silently.
+
+### Session output tracking (Claude Code)
+
+A `Stop` hook fires at the end of every model turn, reads the latest `usage` block from the transcript, and appends a `cmd: "session"` entry to the log with `input_tokens`, `output_tokens`, `cache_read_input_tokens`, and `cache_creation_input_tokens`.
+
+`lakon gain` renders these in a separate **session output** block (see example above) — so you can watch model-side verbosity drop and cache-hit ratios climb over time. Top commands list excludes session entries; they're not shell calls.
+
+### Update notifications (Claude Code)
+
+A `SessionStart` hook checks `registry.npmjs.org/lakon/latest` at most once per 24 hours (cached at `~/.lakon/version.json`) and, if a newer version exists, emits a `hookSpecificOutput.additionalContext` that surfaces inside the Claude session:
+
+```
+lakon 0.7.0 available (you have 0.6.0). Update: npm i -g lakon@latest
+```
+
+Outside Claude, `lakon gain` and `lakon version` print the same notice on stderr (yellow when TTY).
+
+**Opt out:** `LAKON_NO_UPDATE_CHECK=1`.
+**Test endpoint:** `LAKON_REGISTRY_URL=http://localhost:8080/` (overrides the npm URL for local testing).
+
+### Multi-profile Claude Code
+
+If you use wrapper aliases like `claude-my=CLAUDE_CONFIG_DIR=$HOME/.claude-my claude` (e.g. one profile per Anthropic account or org), set the same env var when running `lakon install` so hooks and the rule file land in the right config dir:
+
+```bash
+CLAUDE_CONFIG_DIR=$HOME/.claude-my   lakon install
+CLAUDE_CONFIG_DIR=$HOME/.claude-arco lakon install
+```
+
+Each profile gets its own independent install. `lakon uninstall` / `lakon revert` respect the same env var.
+
+---
+
+## Supported AI agents
+
+| Agent           | Scope    | What `lakon install` writes                                                                          |
+|-----------------|----------|------------------------------------------------------------------------------------------------------|
+| Claude Code¹    | global   | Rule block in `~/.claude/CLAUDE.md` + **five** hooks in `~/.claude/settings.json` (`PreToolUse`: Bash rewrite + Read guard + Grep guard; `Stop`: session-usage log; `SessionStart`: update notify) + `/lakon:gain` `/lakon:reset` `/lakon:inspect` slash commands |
+| Codex CLI       | global   | Rule block in `~/.codex/AGENTS.md`                                                                   |
+| Gemini CLI      | global   | Rule block in `~/.gemini/GEMINI.md`                                                                  |
+| Cursor          | project² | `.cursor/rules/lakon.mdc` in the current dir                                                         |
+| Windsurf        | project² | `.windsurf/rules/lakon.md` in the current dir                                                        |
+| Cline           | project² | `.clinerules/lakon.md` in the current dir                                                            |
+
+¹ "Claude Code" covers **every** Claude Code frontend — terminal CLI, VS Code extension, JetBrains plugin, desktop app. All read the same `~/.claude/CLAUDE.md` + `~/.claude/settings.json`, so one install lights up all of them.
+
+² Project-scoped tools only read rules from the current directory, so `lakon install` skips them by default to avoid scattering files across your repos. Add `--here` (or use `--project`) when you actually want them in the current dir.
+
+Each install is **idempotent** (rerunning replaces the existing block) and **reversible** (`uninstall` strips it, `revert` restores from backup).
+
+---
+
+## Backup & revert
+
+Before writing to your config file for the first time, `lakon` copies it into `~/.lakon/backups/<platform>/<filename>.<timestamp>.bak`. Every install thereafter appends another snapshot to that file's manifest.
+
+```bash
+lakon uninstall   # strips just the lakon block; keeps your other CLAUDE.md content
+lakon revert      # restores the file to its pre-install state, byte for byte
+lakon backups     # shows every snapshot, per platform, with timestamps
+```
+
+Use `uninstall` to remove lakon while keeping your other edits. Use `revert` when you want a clean rollback to exactly the file you had before.
+
+---
+
+## How tracking works
+
+Every filtered command appends a JSON line to `~/.lakon/log.jsonl`. The `Stop` hook appends one line per model turn with token counts (`cmd: "session"`). `lakon gain` reads that log and renders both sides separately.
+
+The log stores: timestamp, command name, first few args, raw/filtered token counts (shell entries); timestamp, session id, `input_tokens` / `output_tokens` / `cache_read` / `cache_create` (session entries). **No file contents. No full arguments. No transcript content. No data ever leaves your machine** — except the one daily HEAD request to `registry.npmjs.org` for the update check (opt-out: `LAKON_NO_UPDATE_CHECK=1`).
+
+Override the location with `LAKON_HOME=/path`. Disable per-command logging with `LAKON_NO_TRACK=1`.
+
+---
+
+## Configuration
+
+| Env var                 | Effect                                                                      |
+|-------------------------|-----------------------------------------------------------------------------|
+| `LAKON_HOME`            | Where to keep the log + backups + version cache (default `~/.lakon`)         |
+| `LAKON_NO_TRACK`        | Set to `1` to disable per-command logging                                    |
+| `LAKON_NO_UPDATE_CHECK` | Set to `1` to disable the `SessionStart` npm check + terminal hint           |
+| `LAKON_REGISTRY_URL`    | Override the npm registry URL used by the update check (testing)             |
+| `LAKON_COLOR`           | `1` forces ANSI colors in `lakon gain`; `0` disables; unset = TTY auto-detect |
+| `NO_COLOR`              | Standard. Disables ANSI colors when set to any non-empty value.              |
+| `CLAUDE_CONFIG_DIR`     | When set during `lakon install` / `uninstall`, hooks + rule land in that dir instead of `~/.claude/`. Used for multi-profile setups. |
+
+---
+
+## Philosophy
+
+> *"Brevity is the soul of wit."* — Shakespeare, *Hamlet*
+> *"Vēnī, vīdī, vīcī."* — Julius Caesar, three words to describe winning a war.
+> *"If."* — Spartans, refusing to be intimidated by a single conditional.
+
+Every token your agent emits or reads is paid for — in latency, in money, in context budget. The fastest way to think clearly is to speak briefly. lakon doesn't make your agent dumber; it makes it Spartan.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/bargadev/lakon-lib
+cd lakon-lib
+npm install                       # only devDeps (c8 for coverage); zero runtime deps
+node --test tests/                # run the suite
+npm run test:coverage             # text + HTML coverage report (coverage/index.html)
+npm run test:coverage:check       # fail if any metric drops below 100%
+node bin/lakon.js --help
+```
+
+Suite: **187 tests**. Coverage gate: **100% lines / 100% branches / 100% functions / 100% statements**. Zero runtime dependencies. Node ≥ 18.
+
+---
+
+## Credits
+
+Built on ideas from two excellent projects:
+
+- [**caveman**](https://github.com/juliusbrussee/caveman) — terse-prose rule + auto-clarity carve-outs.
+- [**rtk**](https://github.com/rtk-ai/rtk) — CLI output filtering as a force multiplier for LLM agents.
+
+lakon condenses both into one zero-dependency npm package with a single install command, automatic backups, and time-windowed savings tracking.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <sub>Speak less. Ship more.</sub>
+</p>

package/assets/logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 240" width="240" height="240" role="img" aria-label="lakon">
+  <title>lakon</title>
+  <desc>Spartan lambda inside a circular shield — symbol of Lakonía, ancient Sparta.</desc>
+  <style>
+    .mark { stroke: #0F0F0F; fill: none; }
+    @media (prefers-color-scheme: dark) {
+      .mark { stroke: #F5F5F5; }
+    }
+  </style>
+  <circle class="mark" cx="120" cy="120" r="106" stroke-width="5"/>
+  <path class="mark" d="M 72 178 L 120 60 L 168 178" stroke-width="16" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/bin/lakon.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const { filterCommand, isSupported, countTokensApprox } = require('../src/filters');
+const { install, uninstall, revert, listPlatforms, backupsReport } = require('../src/install');
+const tracking = require('../src/tracking');
+const versionCheck = require('../src/hooks/version-check');
+
+const HELP = `lakon — spartan replies for AI agents
+
+Usage:
+  lakon <cmd> [args...]      Run <cmd> and filter its output (tracks savings)
+  lak <cmd> [args...]        (short alias)
+
+  lakon install              Install rule + hooks for detected GLOBAL platforms
+                             (Claude Code / Codex / Gemini — touches ~/ only)
+  lakon install --here       Same as above + per-project rules (Cursor /
+                             Windsurf / Cline) written into the current dir
+  lakon install --only <p>   Install just one platform by id (any scope)
+                             (every install backs up the target file first)
+  lakon uninstall            Strip the lakon block (keeps rest of file)
+  lakon revert [--only <p>]  Restore files to pre-install state from backup
+  lakon backups              Show backup history per platform
+  lakon list                 Show supported platforms
+
+  lakon gain                 Show token savings (hour / day / week / month / all)
+  lakon inspect <cmd> ...    Run <cmd> once and show raw vs filtered (no tracking)
+  lakon reset                Wipe the savings log
+  lakon version              Print the installed lakon version
+  lakon --help               This help
+
+Supported filters: git (log/status/diff/show), ls, tree, cat, head, tail, grep, rg, ag.
+Unsupported commands run unchanged (passthrough, still tracked as 0% savings).
+
+Multi-profile Claude Code (e.g. claude-my / claude-arco wrappers):
+  CLAUDE_CONFIG_DIR=$HOME/.claude-my   lakon install
+  CLAUDE_CONFIG_DIR=$HOME/.claude-arco lakon install
+
+Update notifications:
+  SessionStart hook + \`lakon gain\` / \`lakon version\` check npm once per day.
+  Disable with LAKON_NO_UPDATE_CHECK=1.
+`;
+
+function runAndFilter(cmd, args) {
+  const child = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['inherit', 'pipe', 'inherit'] });
+  if (child.error) {
+    process.stderr.write(`lakon: ${child.error.message}\n`);
+    process.exit(127);
+  }
+  /* c8 ignore next */
+  const raw = child.stdout || '';
+  const filtered = isSupported(cmd) ? filterCommand(cmd, args, raw) : raw;
+  process.stdout.write(filtered);
+  /* c8 ignore next */
+  if (filtered && !filtered.endsWith('\n')) process.stdout.write('\n');
+
+  tracking.record({
+    cmd,
+    args,
+    rawTokens: countTokensApprox(raw),
+    filteredTokens: countTokensApprox(filtered),
+  });
+
+  /* c8 ignore next */
+  process.exit(child.status ?? 0);
+}
+
+function inspectCmd(rest) {
+  if (!rest.length) {
+    process.stderr.write('lakon inspect: missing command\n');
+    process.exit(2);
+  }
+  const [cmd, ...args] = rest;
+  const child = spawnSync(cmd, args, { encoding: 'utf8' });
+  /* c8 ignore next */
+  const raw = child.stdout || '';
+  const filtered = isSupported(cmd) ? filterCommand(cmd, args, raw) : raw;
+  const rawTokens = countTokensApprox(raw);
+  const newTokens = countTokensApprox(filtered);
+  /* c8 ignore next */
+  const saved = rawTokens === 0 ? 0 : Math.round((1 - newTokens / rawTokens) * 100);
+  process.stdout.write(
+    `cmd:      ${cmd} ${args.join(' ')}\n` +
+      `raw:      ${rawTokens} tokens (${raw.length} bytes)\n` +
+      `filtered: ${newTokens} tokens (${filtered.length} bytes)\n` +
+      `saved:    ${saved}%\n`
+  );
+}
+
+function printVersion() {
+  const pkg = require('../package.json');
+  process.stdout.write(`${pkg.name} ${pkg.version}\n`);
+}
+
+function maybePrintUpdateHint() {
+  try {
+    const update = versionCheck.getCachedUpdate();
+    if (update) {
+      /* c8 ignore next */
+      const color = !process.env.NO_COLOR && process.stderr.isTTY;
+      const msg = versionCheck.formatNotice(update);
+      /* c8 ignore next */
+      process.stderr.write(color ? `\n\x1b[33m${msg}\x1b[0m\n` : `\n${msg}\n`);
+    }
+    /* c8 ignore next 3 */
+  } catch {
+    // never let update hint break a command
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (argv[0] === '--version' || argv[0] === '-v' || argv[0] === 'version') {
+    printVersion();
+    await versionCheck.checkForUpdate().catch(() => {});
+    maybePrintUpdateHint();
+    return;
+  }
+
+  const [first, ...rest] = argv;
+
+  if (first === 'install') {
+    const onlyIdx = rest.indexOf('--only');
+    /* c8 ignore next */
+    const only = onlyIdx >= 0 ? rest[onlyIdx + 1] : null;
+    const here = rest.includes('--here');
+    await install({ only, here });
+    return;
+  }
+  if (first === 'uninstall') {
+    await uninstall();
+    return;
+  }
+  if (first === 'revert') {
+    const onlyIdx = rest.indexOf('--only');
+    /* c8 ignore next */
+    const only = onlyIdx >= 0 ? rest[onlyIdx + 1] : null;
+    await revert({ only });
+    return;
+  }
+  if (first === 'backups') {
+    process.stdout.write(backupsReport());
+    return;
+  }
+  if (first === 'list') {
+    process.stdout.write(listPlatforms().join('\n') + '\n');
+    return;
+  }
+  if (first === 'gain' || first === 'stats') {
+    process.stdout.write(tracking.report());
+    await versionCheck.checkForUpdate().catch(() => {});
+    maybePrintUpdateHint();
+    return;
+  }
+  if (first === 'inspect') {
+    inspectCmd(rest);
+    return;
+  }
+  if (first === 'reset') {
+    const ok = tracking.reset();
+    process.stdout.write(ok ? 'lakon: log cleared\n' : 'lakon: nothing to clear\n');
+    return;
+  }
+
+  runAndFilter(first, rest);
+}
+
+/* c8 ignore next 4 */
+main().catch((err) => {
+  process.stderr.write(`lakon: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "lakonai",
+  "version": "0.6.1",
+  "description": "Spartan replies for AI agents — terse model output + filtered CLI output for Claude Code, Codex, Cursor, Windsurf, Cline, and Gemini.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "cline",
+    "gemini",
+    "llm",
+    "tokens",
+    "context-window",
+    "ai-coding",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "bargadev",
+  "homepage": "https://github.com/bargadev/lakon-lib",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bargadev/lakon-lib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bargadev/lakon-lib/issues"
+  },
+  "type": "commonjs",
+  "main": "src/filters/index.js",
+  "bin": {
+    "lakon": "bin/lakon.js",
+    "lak": "bin/lakon.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/",
+    "test:coverage": "c8 --reporter=text --reporter=html node --test tests/",
+    "test:coverage:check": "c8 --check-coverage --lines 100 --branches 100 --functions 100 node --test tests/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
+}

package/src/filters/cat.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const { stripAnsi, truncateLines } = require('./utils');
+
+const DEFAULT_MAX_LINES = 200;
+const BLANK_RUN_RE = /\n[\t ]*\n([\t ]*\n)+/g;
+
+function compactBlankRuns(text) {
+  return text.replace(BLANK_RUN_RE, '\n\n');
+}
+
+function filter(raw, opts = {}) {
+  const max = opts.maxLines || DEFAULT_MAX_LINES;
+  const compacted = compactBlankRuns(stripAnsi(raw));
+  return truncateLines(compacted, max);
+}
+
+module.exports = { filter, compactBlankRuns };