# lowfat

> A lightweight CLI tool that reduces AI token costs by filtering and compressing unnecessary command output before it reaches your AI agent.

lowfat is an open-source CLI tool written in Rust that intercepts shell command output and strips noise before it reaches an AI coding agent. It is built by zdk (Warachet Samtalee) and released under the Apache-2.0 license. The project is installable via `cargo install lowfat` or Homebrew and ships pre-built binaries on GitHub Releases.

## What It Is

lowfat sits between your shell and your AI agent, acting as a transparent filter that compresses verbose command output — such as `git diff`, `git log`, `docker ps`, and `ls -la` — before those outputs consume context-window tokens. It is not a cloud service; all processing happens locally with no telemetry. The tool is designed around UNIX-style composability: it works as a pipe, a shell hook, or a direct command prefix, and it supports custom user-written filter plugins.

## How the Filtering Pipeline Works

lowfat applies named filter levels — `lite`, `full`, and `ultra` — to each supported command. The README documents measured output reductions on bundled samples:

- `git diff`: -16% (lite), -38% (full), -96% (ultra)
- `git log`: -53% (lite), -80% (full), -91% (ultra)
- `git status`: -62% (lite), -62% (full), -74% (ultra)
- `docker ps`: -38% (lite), -38% (full), -85% (ultra)
- `ls -la`: -2% (lite), -75% (full), -87% (ultra)

The README notes these percentages measure reduction of a single command's raw output, not end-to-end agent token usage, and advises users to verify their agent still has what it needs at higher compression levels.

## Agent Integration Paths

lowfat supports several integration modes without requiring changes to the agent itself:

- **Claude Code hook** — a `PreToolUse` hook in `.claude/settings.json` intercepts every Bash call
- **Shell integration** — auto-activates inside agent environments (`CLAUDECODE=1`, `CODEX_ENV`) or via `LOWFAT_ENABLE=1`
- **OpenCode plugin** — a single `lowfat opencode install` command writes a plugin file; uninstall is equally simple
- **Pi agent** — configured via `shellCommandPrefix` in `~/.pi/agent/settings.json`
- **Direct prefix** — `lowfat git status`, `lowfat docker ps`, etc., with no setup required

## Plugin and Extensibility Model

The core ships with six built-in command filters: `git`, `docker`, `grep`, `find`, `ls`, and `tree`. Users can scaffold new plugins with `lowfat plugin new <name>`, which creates a directory under `~/.lowfat/plugins/`. Filters are written in the `.lf` DSL, with shell and Python (PEP 723 / uv) escape hatches available. The `lowfat plugin doctor` command checks plugins and pre-installs Python dependencies. Filters can be tested against sample files without installing them using `lowfat filter --explain`.

## Update: v0.6.8

The latest release is v0.6.8, published on 2026-06-05. The repository was created in April 2026 and has seen active development, with the last push recorded on 2026-06-06. The project has accumulated 299 stars and 11 forks on GitHub as of the last recorded update, signaling early community traction for a recently launched tool.

## Design Philosophy and Tradeoffs

The README explicitly positions lowfat as a "minimal core you extend yourself," contrasting it with the batteries-included approach of alternatives like `rtk`. lowfat covers fewer built-in commands (6 vs. 100+) but offers a local-only, no-telemetry guarantee and a composable plugin DSL. The README includes a head-to-head token savings comparison with `rtk` on the same repo, noting lowfat compresses git output harder while `rtk` edges out `find` at its default settings. The README frames this as directional rather than a definitive benchmark.

## Features
- Filter and compress CLI command output before it reaches AI agents
- Three compression levels: lite, full, ultra
- Six built-in command filters: git, docker, grep, find, ls, tree
- Claude Code PreToolUse hook integration
- Shell integration with auto-activation in agent environments
- OpenCode plugin support
- Pi agent support
- Custom plugin scaffolding with .lf DSL
- Shell and Python (PEP 723/uv) plugin escape hatches
- Local-only processing with no telemetry
- Token savings analytics via lowfat stats and history
- UNIX-style pipe composability
- Single binary, small footprint
- Plugin doctor for dependency checking
- Filter testing against samples without installation

## Integrations
Claude Code, OpenCode, Pi agent, Bash, Zsh, Git, Docker, Homebrew, cargo (Rust), Python (PEP 723 / uv)

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.6.8

## Links
- Website: https://github.com/zdk/lowfat
- Documentation: https://github.com/zdk/lowfat/blob/main/docs/ARCHITECTURE.md
- Repository: https://github.com/zdk/lowfat
- EveryDev.ai: https://www.everydev.ai/tools/lowfat