lowfat is a lightweight CLI tool that reduces AI token costs by filtering unnecessary CLI output 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.

Token savings

Aggregated from real local usage (lowfat stats):

Command	Raw	Filtered	Saved
grep	1.4Mt	29.5Kt	98%
docker	693.6Kt	27.2Kt	96%
kubectl get	1.4Mt	60.3Kt	96%
find	196.1Kt	13.3Kt	93%
docker compose	21.5Kt	2.3Kt	89%
git log	37.6Kt	9Kt	76%

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" }]
      }
    ]
  }
}

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. Remove it anytime 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)\"; " }

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

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

License

Apache-2.0

AI notice

Multiple AI tools were used for this project