lowfat logo

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

lowfat demo: condensing verbose git output (diff, log) before it reaches the agent

• 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.

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>:

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.

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

Pre-built binaries on GitHub Releases.

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)\"; " }

# 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

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

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

• 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

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

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

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

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.

Apache-2.0

Multiple AI tools were used for this project