lowfat

lowfat filters command output.

It filters command output before they reach AI agent by wrapping them as shell functions.

Pipe your CLI output through composable processors like grep, cut, head, and token-budget.

git diff: 2,781 tokens → 156 tokens (−94%)

Key features,

• You own your data — customize or add your own filters in shell script.
• Composable, pipe-based processing stages.
• Per-project pipeline customization.
• Built-in secret redaction.
• No telemetry.

Install

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

Pre-built binaries are also available on GitHub Releases.

Setup

Choose one of the following:

Option A: Claude Code hook

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "lowfat hook"
          }
        ]
      }
    ]
  }
}

Option B: Shell integration

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

Activates automatically inside agent environments (CLAUDECODE=1, CODEX_ENV) — commands run normally otherwise.

Option C: Direct usage

lowfat git status
lowfat docker ps
lowfat ls -la

Intensity levels

Three levels control how aggressively output is compressed:

lowfat level              # show current level
lowfat level ultra        # set to ultra (most aggressive)
LOWFAT_LEVEL=lite lowfat git log  # per-command override

Level	Behavior
lite	Gentle — keeps most context
full	Default — balanced filtering
ultra	Maximum compression — minimal output

Inspecting state

lowfat filters            # list enabled/disabled filters
lowfat pipeline git       # show active pipeline for a command
lowfat gain               # show lifetime token savings report
lowfat audit              # show recent plugin executions
lowfat status             # show status badge

Disabling filters

LOWFAT_DISABLE=git lowfat git status   # disable git filter for this run

Or in .lowfat config:

disable=npm,cargo

Token savings

Command	Raw	Filtered	Saved
git status	127t	5t	96%
git diff	2,781t	156t	94%
git log	911t	100t	89%
docker ps	271t	41t	84%
npm install	184t	13t	92%

Pipeline config

Define per-command filters in .lowfat:

pipeline.git.diff = grep:^(diff |--- |\+\+\+ |@@ |[+-]) | head:200
pipeline.cargo = grep:^error | head:50
pipeline.kubectl = strip-ansi | cut:1,4,6 | token-budget:500

Built-in processors: grep, grep-v, cut, strip-ansi, head, truncate, token-budget, dedup-blank, redact-secrets

cut uses Unix cut -f syntax: cut:1,3 (fields 1 and 3), cut:2-5 (range), cut:3- (field 3 to end), cut:,;1,3 (comma delimiter).

Plugins

For command-specific filtering beyond built-in processors, plugins are shell scripts that read raw output from stdin and write filtered output to stdout.

Bundled plugins: git-compact, docker-compact, ls-compact, npm-compact, go-compact

lowfat plugin list          # list installed plugins
lowfat plugin new cargo     # scaffold a new plugin
lowfat plugin bench cargo   # benchmark against sample files
lowfat plugin doctor        # check plugin health

lowfat plugin new cargo creates ~/.lowfat/plugins/cargo/cargo-compact/ with:

lowfat.toml     # manifest: name, commands, runtime
filter.sh       # your filter logic (stdin → stdout)
samples/        # sample outputs for benchmarking

Plugins receive context via environment variables: $LOWFAT_LEVEL, $LOWFAT_COMMAND, $LOWFAT_SUBCOMMAND, $LOWFAT_EXIT_CODE.

Plugins can be mixed with built-in processors in pipelines:

pipeline.git = strip-ansi | git-compact | truncate:100

Alternatives

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

License

Apache-2.0

AI notice

AI tools were used for this project