\n One command. Three fronts: terse model output · filtered shell output · blocked junk reads.
\n Plus session-level token tracking and one-day update notifications.
\n Works across Claude Code, Codex, Cursor, Windsurf, Cline, Gemini CLI.\n
\n\n---\n\n## At a glance — measured savings\n\n| Command | Raw tokens | Filtered | Saved |\n|----------------------------------|-----------:|---------:|--------:|\n| `git log -p -10` | 10,497 | 78 | **-94%** |\n| `ls -laR` (deep directory) | 23,624 | 117 | **-94%** |\n| `git diff HEAD~5` | 13,230 | 798 | **-89%** |\n| `git log --stat -50` | 4,845 | 439 | **-86%** |\n| `git status` | 17 | 1 | **-89%** |\n| `Read pnpm-lock.yaml` | ~56,000 | **blocked** | **-95%** |\n| `Grep` (auto `head_limit`) | unbounded | 30 matches | **capped** |\n\nConservative numbers — peaks go higher in practice. Run `lakon inspect ` on your own commands to measure.\n\n---\n\n## The story behind the name\n\nIn 346 BC, Philip II of Macedon — father of Alexander the Great — sent the Spartans a message:\n\n> *\"If I invade Lakonía, I will raze your cities to the ground.\"*\n\nThe Spartans replied with a single word:\n\n> *\"If.\"*\n\nThat 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.\n\nYour 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.\n\n**lakon trims both sides.**\n\n---\n\n## Three fronts. One install.\n\n| Front | Wasted tokens look like… | lakon fixes it by… |\n|--------------------------------|-------------------------------------------------------|-------------------------------------------------------------------------------------|\n| **Output** (the model) | *\"Great question! Let me explain…\"* | Installing a terse-response rule. No preamble, no recap, no restating. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n\nOther tools stop at one front. lakon does all three transparently — your agent doesn't have to remember anything.\n\n---\n\n## Quick start\n\n```bash\nnpm install -g @bargadev/lakon\nlakon install\n```\n\nThat'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.\n\nWorking inside a repo and want **per-project** rules (Cursor, Windsurf, Cline)? Add `--here`:\n\n```bash\ncd path/to/your/repo\nlakon install --here # globals + per-project rules in this dir\n```\n\nFrom the next session forward your agent:\n\n1. **Responds tersely** — no preamble, no restating, no recap. (rule in `CLAUDE.md` / equivalent)\n2. **Has its `Bash` calls auto-rewritten** — `PreToolUse` hook intercepts `git`/`ls`/`cat`/`grep`/etc and prefixes them with `lakon` transparently.\n3. **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.\n4. **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.\n5. **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.\n6. **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.\n7. **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`).\n\nYou'll see savings stack up immediately in `lakon gain`.\n\n> 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.\n\n> **Worried?** Every install backs up the target file first. `lakon revert` puts it back byte-for-byte.\n\n---\n\n## Use the filter directly\n\nThe CLI works as a standalone tool too. Run any shell command through `lakon` (or the short alias `lak`) to filter its output:\n\n```bash\nlakon git status # compressed git status\nlakon git log -50 # one line per commit (hash + subject)\nlakon git diff # only +/- lines, no noise\nlakon ls -la # size + name only\nlakon grep -r foo src/ # truncates at 40 matches\n```\n\nUnsupported commands run unchanged.\n\n---\n\n## See your savings\n\n```bash\nlakon gain\n```\n\n```\nlakon — savings this week: 36.4k tok saved across 512 shell calls (67%)\n\nshell + read/grep guards (tokens filtered before context)\n win calls before after saved %\n 1h 12 1.2k tok 380 tok 820 tok 68%\n 24h 87 9.8k tok 3.1k tok 6.7k tok 68%\n 7d 512 54.2k tok 17.8k tok 36.4k tok 67%\n 30d 2104 241.0k tok 79.2k tok 161.8k tok 67%\n all 2104 241.0k tok 79.2k tok 161.8k tok 67%\n\nllm output (model tokens — terse style trims this side)\n win turns input output cache-read\n 1h 4 2.1k tok 320 tok 48.7k tok\n 24h 38 18.4k tok 2.6k tok 412.2k tok\n 7d 210 102.5k tok 14.1k tok 2.3M tok\n\ntop commands (all time)\n git 812x saved 124.3k tok 72%\n ls 541x saved 18.2k tok 58%\n grep 339x saved 12.0k tok 65%\n```\n\nThe 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.\n\n### Inspect a single command\n\n```bash\nlakon inspect git log\n```\n\n```\ncmd: git log\nraw: 1234 tokens (8127 bytes)\nfiltered: 187 tokens (1240 bytes)\nsaved: 85%\n```\n\n---\n\n## Commands\n\n| Command | What it does |\n|----------------------------------|-----------------------------------------------------------------------|\n| `lakon install` | Install rule for detected GLOBAL agents only (no CWD writes) |\n| `lakon install --here` | Globals + per-project rules (Cursor/Windsurf/Cline) in current dir |\n| `lakon install --only ` | Install just one platform by id (any scope) |\n| `lakon uninstall` | Strip the lakon block from each config (keeps your other content) |\n| `lakon revert [--only
]` | Restore each config to its pre-install state from backup |\n| `lakon backups` | Show backup history per platform |\n| `lakon list` | Show supported platforms and which are detected |\n| `lakon [args]` | Run a command, filter its output, track savings |\n| `lakon gain` | Show savings by hour / day / week / month / all-time + session totals |\n| `lakon inspect ` | Run once and show raw-vs-filtered (no tracking) |\n| `lakon reset` | Wipe the savings log |\n| `lakon version` / `--version` / `-v` | Print the installed lakon version |\n\n`lak` is the short alias for `lakon` — same behavior.\n\n---\n\n## Supported filters\n\n| Command | What it does |\n|------------------------|-------------------------------------------------------------------|\n| `git log` | One line per commit (` `), capped at 50 |\n| `git status` | Drops hint paragraphs, separates changed vs untracked |\n| `git diff` / `show` | Only `+`/`-`/`@@` lines, drops `index`/`---`/`+++`, cap 120 lines |\n| `ls -la` / `tree` | `\\t` (drops perms / dates / link targets), cap 60 |\n| `cat` | Collapses blank-line runs, cap 200 lines |\n| `head` / `tail` | Cap 50 lines |\n| `grep` / `rg` / `ag` | Cap 15 matches with \"tighten the pattern\" hint |\n\nUnsupported commands run unchanged (passthrough), still tracked at 0 % savings.\n\n### Read tool guard (Claude Code)\n\nThe `Read` hook automatically:\n\n- **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/`\n- **Denies** lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `go.sum`, `*.lock`)\n- **Denies** build artifacts (`*.min.js`, `*.min.css`, `*.min.mjs`, `*.tsbuildinfo`, `*.map`, `*.log`, `*.pyc`, `*.pyo`, `*.so`, `*.o`, `*.a`, `*.dylib`, `*.dll`, `*.exe`, `*.class`, `*.wasm`)\n- **Caps** files over 800 lines at 800 (with hint to `Read` again with `offset` for more, or `grep -n` for the symbol you need)\n\nEach deny returns a one-line reason the model reads, so it knows to `grep -n` the symbol instead.\n\n### Grep tool guard (Claude Code)\n\nThe `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.\n\n### Session output tracking (Claude Code)\n\nA `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`.\n\n`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.\n\n### Update notifications (Claude Code)\n\nA `SessionStart` hook checks `registry.npmjs.org/@bargadev/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:\n\n```\nlakon 0.7.0 available (you have 0.6.0). Update: npm i -g @bargadev/lakon@latest\n```\n\nOutside Claude, `lakon gain` and `lakon version` print the same notice on stderr (yellow when TTY).\n\n**Opt out:** `LAKON_NO_UPDATE_CHECK=1`.\n**Test endpoint:** `LAKON_REGISTRY_URL=http://localhost:8080/` (overrides the npm URL for local testing).\n\n### Multi-profile Claude Code\n\nIf 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:\n\n```bash\nCLAUDE_CONFIG_DIR=$HOME/.claude-my lakon install\nCLAUDE_CONFIG_DIR=$HOME/.claude-arco lakon install\n```\n\nEach profile gets its own independent install. `lakon uninstall` / `lakon revert` respect the same env var.\n\n---\n\n## Supported AI agents\n\n| Agent | Scope | What `lakon install` writes |\n|-----------------|----------|------------------------------------------------------------------------------------------------------|\n| 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 |\n| Codex CLI | global | Rule block in `~/.codex/AGENTS.md` |\n| Gemini CLI | global | Rule block in `~/.gemini/GEMINI.md` |\n| Cursor | project² | `.cursor/rules/lakon.mdc` in the current dir |\n| Windsurf | project² | `.windsurf/rules/lakon.md` in the current dir |\n| Cline | project² | `.clinerules/lakon.md` in the current dir |\n\n¹ \"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.\n\n² 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.\n\nEach install is **idempotent** (rerunning replaces the existing block) and **reversible** (`uninstall` strips it, `revert` restores from backup).\n\n---\n\n## Backup & revert\n\nBefore writing to your config file for the first time, `lakon` copies it into `~/.lakon/backups//..bak`. Every install thereafter appends another snapshot to that file's manifest.\n\n```bash\nlakon uninstall # strips just the lakon block; keeps your other CLAUDE.md content\nlakon revert # restores the file to its pre-install state, byte for byte\nlakon backups # shows every snapshot, per platform, with timestamps\n```\n\nUse `uninstall` to remove lakon while keeping your other edits. Use `revert` when you want a clean rollback to exactly the file you had before.\n\n---\n\n## How tracking works\n\nEvery 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.\n\nThe 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`).\n\nOverride the location with `LAKON_HOME=/path`. Disable per-command logging with `LAKON_NO_TRACK=1`.\n\n---\n\n## Configuration\n\n| Env var | Effect |\n|-------------------------|-----------------------------------------------------------------------------|\n| `LAKON_HOME` | Where to keep the log + backups + version cache (default `~/.lakon`) |\n| `LAKON_NO_TRACK` | Set to `1` to disable per-command logging |\n| `LAKON_NO_UPDATE_CHECK` | Set to `1` to disable the `SessionStart` npm check + terminal hint |\n| `LAKON_REGISTRY_URL` | Override the npm registry URL used by the update check (testing) |\n| `LAKON_COLOR` | `1` forces ANSI colors in `lakon gain`; `0` disables; unset = TTY auto-detect |\n| `NO_COLOR` | Standard. Disables ANSI colors when set to any non-empty value. |\n| `CLAUDE_CONFIG_DIR` | When set during `lakon install` / `uninstall`, hooks + rule land in that dir instead of `~/.claude/`. Used for multi-profile setups. |\n\n---\n\n## Philosophy\n\n> *\"Brevity is the soul of wit.\"* — Shakespeare, *Hamlet*\n> *\"Vēnī, vīdī, vīcī.\"* — Julius Caesar, three words to describe winning a war.\n> *\"If.\"* — Spartans, refusing to be intimidated by a single conditional.\n\nEvery 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.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/bargadev/lakon-lib\ncd lakon-lib\nnpm install # only devDeps (c8 for coverage); zero runtime deps\nnode --test tests/ # run the suite\nnpm run test:coverage # text + HTML coverage report (coverage/index.html)\nnpm run test:coverage:check # fail if any metric drops below 100%\nnode bin/lakon.js --help\n```\n\nSuite: **187 tests**. Coverage gate: **100% lines / 100% branches / 100% functions / 100% statements**. Zero runtime dependencies. Node ≥ 18.\n\n---\n\n## Credits\n\nBuilt on ideas from two excellent projects:\n\n- [**caveman**](https://github.com/juliusbrussee/caveman) — terse-prose rule + auto-clarity carve-outs.\n- [**rtk**](https://github.com/rtk-ai/rtk) — CLI output filtering as a force multiplier for LLM agents.\n\nlakon condenses both into one zero-dependency npm package with a single install command, automatic backups, and time-windowed savings tracking.\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n---\n\n\n Speak less. Ship more.\n
\n","readmeFilename":"README.md"}
![\"lakon\"](\"./assets/logo.svg\"){kind=logo}
\n![\"npm\"](\"https://img.shields.io/npm/v/@bargadev/lakon?color=0F0F0F&label=npm\")
![\"MIT\"](\"https://img.shields.io/badge/license-MIT-0F0F0F\"){kind=icon}
![\"node](\"https://img.shields.io/badge/node-%E2%89%A518-0F0F0F\"){kind=icon}
![\"zero](\"https://img.shields.io/badge/deps-0-0F0F0F\"){kind=icon}
![\"6](\"https://img.shields.io/badge/agents-6-0F0F0F\"){kind=icon}