lowfat is a lightweight CLI tool that reduces AI token costs by filtering CLI output and file content before it reaches your agent.

Core focus

• Lightweight — Small single binary, small core; but extensible.
• Local-first — No telemetry; you own your data.
• Composable — UNIX-style pipes, mix built-ins and your own filters; not magic.
• User-owned — lowfat history shows what you run most; allow you to customize for your usecase.

Before / after

git status at the full level — same signal, less noise.

Before — raw git status:

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   crates/lowfat-cli/src/commands/plugin.rs
	modified:   crates/lowfat-cli/src/main.rs

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	plugins/git/git-compact/samples/

no changes added to commit (use "git add" and/or "git commit -a")

After — lowfat git status:

On branch main
Changes not staged for commit:
	modified:   crates/lowfat-cli/src/commands/plugin.rs
	modified:   crates/lowfat-cli/src/main.rs
Untracked files:
	plugins/git/git-compact/samples/

Reduction of raw command output, measured on the bundled samples (crates/lowfat-plugin/embedded/*/samples/). Reproduce with cat <sample> | lowfat filter <plugin>/filter.lf --sub=<sub> --level=<level>:

command	lite	full	ultra
git diff	-16%	-38%	-96%
git log	-53%	-80%	-91%
git status	-62%	-62%	-74%
docker ps	-38%	-38%	-85%
docker images	-48%	-58%	-86%
ls -la	-2%	-75%	-87%

These percentages are the reduction of a single command's output, not your end-to-end agent token usage. savings depend on how much of your context is command output and how lossy a level you pick — higher levels drop more, so verify your agent still has what it needs. treat the table as a ceiling on the output slice, not a promise on the total.

Install

cargo install lowfat
# or
brew install zdk/tools/lowfat

Pre-built binaries on GitHub Releases.

Setup

Pick one of:

Claude Code hook — add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "lowfat hook" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [{ "type": "command", "command": "lowfat post-read" }]
      }
    ]
  }
}

PreToolUse rewrites Bash commands through lowfat filters. PostToolUse compresses file content after Read — strips comments, collapses function bodies, summarizes lock files.

The filtering pattern Anthropic recommends, but via lowfat.

Shell integration — auto-activates inside agent environments (CLAUDECODE=1, CODEX_ENV), or set LOWFAT_ENABLE=1 to force it on any shell:

echo 'eval "$(lowfat shell-init zsh)"' >> ~/.zshrc   # or ~/.bashrc

OpenCode plugin — one command, no config editing:

lowfat opencode install   # writes ~/.config/opencode/plugins/lowfat.ts

Restart OpenCode; commands are rewritten transparently before they run. Uninstall with lowfat opencode uninstall.

Direct usage — prefix any command:

lowfat git status
lowfat docker ps
lowfat ls -la

Pi agent — in ~/.pi/agent/settings.json:

{ "shellCommandPrefix": "eval \"$(lowfat shell-init zsh)\"; " }

Codex, Grok Build, Antigravity — direct prefixing works in all:

lowfat git status
lowfat docker ps

Shell integration auto-activates for Codex when CODEX_ENV is set (or force with LOWFAT_ENABLE=1).

Non-interactive runs often need bypass/approval flags:

• Codex: codex exec --dangerously-bypass-approvals-and-sandbox ...
• Grok Build: grok --single --always-approve --permission-mode bypassPermissions ...

Antigravity (agy) supports direct prefixing inside sessions; non-interactive terminal execution is inconsistent.

Discoverability skills are installed for autonomous agent use:

• Claude Code: ~/.claude/skills/lowfat/SKILL.md
• Codex: ~/.codex/skills/lowfat/SKILL.md
• .agents / Devin-style: ~/.agents/skills/lowfat/SKILL.md
• Antigravity (Google): ~/.gemini/config/plugins/google-antigravity-sdk/skills/lowfat/SKILL.md

Tested agents (one-shot verification)

Assistant	Result	Notes
Claude Code	PASS	Pre-existing hooks; clean --print execution
Codex	PASS	Used bypass flags for non-interactive exec
Grok Build	PASS	--single + bypass/always-approve
Antigravity	PARTIAL	Direct prefix works in-session; --print terminal invocation is unreliable

Usage highlights

# See what's configured and how loud each filter is being
lowfat info                       # status badge + active filters
lowfat info git                   # pipeline for `git`
lowfat info --config              # full resolved config

# See what lowfat has saved you
lowfat stats                      # lifetime token savings
lowfat stats --audit              # recent plugin executions
lowfat history                    # rank commands by potential savings

# Dial the aggressiveness
lowfat level ultra                # max compression
LOWFAT_LEVEL=lite lowfat git log  # one-off override

# Write a plugin
lowfat plugin new terraform       # scaffold ~/.lowfat/plugins/terraform/
lowfat plugin doctor              # check plugins (and pre-install any Python deps)

# Test a plugin against a sample without installing it
cat samples/git-diff-full.txt | lowfat filter --explain ./filter.lf --sub=diff --level=ultra

File content compression (post-read)

When Claude reads files, lowfat post-read compresses the content before it enters the context:

Content type	What it does
Source code (Rust, Python, Go, Elixir, JS/TS, Java, Ruby, C/C++, Shell)	Strip comments, normalize blanks; at ultra: collapse function bodies to signatures
Markdown	Strip badges, HTML comments; truncate code blocks and tables
HTML / Vue / Svelte	Strip <style>, <script>, class attributes; at ultra: text extraction only
JSON / JSONC	Truncate large arrays, collapse deep nesting
Lock files (Cargo.lock, package-lock.json, yarn.lock, ...)	Replace with summary: package count + top deps
Unknown	Head + tail with line count

Compression level follows LOWFAT_LEVEL (lite/full/ultra). Files with <10% savings pass through unchanged.

Learn more

• docs/ARCHITECTURE.md — high-level diagram: CLI, Runner, Plugins, Builtins
• docs/CONFIG.md — .lowfat file, env vars, pipeline DSL, built-in processors, the history ranking
• docs/PLUGINS.md — lf-filter (the .lf plugin DSL), shell escape hatches, PEP 723 + uv, AI agent prompt

Alternatives

• rtk
• context-mode
• lean-ctx
• tokf
• tamp
• ecotokens
• token-enhancer

vs rtk

rtk is the closest tool but differ in philosophy: rtk is batteries-included; lowfat is a minimal core you extend yourself.

	lowfat	rtk
Built-in commands	6 curated (git, docker, grep, find, ls, tree)	100+ across many ecosystems
Custom filters	.lf DSL + shell + Python (PEP 723/uv)	TOML DSL
Levels	lite / full / ultra	-l aggressive, --ultra-compact
File-content filtering	post-read hook (code, markdown, HTML, data, lock files)	rtk read / smart (signatures, summaries)
Agent integrations	Claude Code, Codex, Grok Build, Antigravity, OpenCode, shell, Pi	14 tools (Claude Code, Copilot, Gemini, Codex, …)
Telemetry	None — local-only	Opt-in, off by default (anonymous aggregate)
Savings analytics	lowfat stats / history (local)	rtk gain / discover (local)
Optional remote log	Opt-in to your Supabase observatory (eng_evaluations)	—

Token savings, head-to-head

Same commands, same repo, same cwd, run through both tools. Output tokens counted with tiktoken (cl100k_base); savings are vs the raw command output:

command	raw tokens	lowfat full	lowfat ultra	rtk
git status	81	-91%	-91%	-79%
git diff	1241	-15%	-97%	-9%
git log	3350	-93%	-97%	-56%
ls -la	153	-77%	-89%	-86%
find	535	-0%	-58%	-66%
Honest read: lowfat compresses git harder; rtk edges out find; ls is close.
find only engages at lowfat's ultra level. rtk's --ultra-compact gave
near-identical numbers to its default here, so the default is shown. This is a
single small run on one repo — directional, not a benchmark; measure on your own
workload before trusting any of it.

Optional Supabase observatory integration

lowfat can optionally log its own token savings to a personal Supabase "observatory" (tables eng_technologies + eng_evaluations). This is completely optional, best-effort, and non-blocking.

• Only activates when LOWFAT_SUPABASE_URL + LOWFAT_SUPABASE_KEY (or the generic SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY) are present.
• Logs aggregates only: command, subcommand, raw/filtered/saved tokens, savings %, had_plugin, reduced, exit code, elapsed ms. No raw output or full arguments are sent.
• Records under technology slug lowfat (category tool).
• lowfat stats / history / info remain fully local and work offline.
• Enabled status appears in lowfat info when active.
• Debug failures with LOWFAT_OBSERVATORY_DEBUG=1.

This respects the local-first design: the remote path is fire-and-forget and never affects stdout, exit code, or local tracking.

License

Apache-2.0

AI notice

Multiple AI tools were used for this project

Star History