Lowfat: Reducing LLM Token Costs via Pluggable CLI Filtering

Lowfat is a lightweight CLI tool that reduces AI token costs by filtering unnecessary command-line output before it reaches an AI agent. By stripping "noise" from the output of tools like git or docker, it prevents bloated context windows and lowers the cost of LLM API calls.

Core Architecture and Design

Lowfat is built as a composable, local-first utility that prioritizes user control and extensibility. Its design follows several key technical principles:

  • Local-first and Private: The tool operates entirely locally with no telemetry, ensuring that data remains under the user's control.
  • Composable Pipeline: Using a UNIX-style pipe architecture, Lowfat allows users to mix built-in filters with custom-defined filters to create specific output-slimming pipelines.
  • Extensible via Plugins: Users can create custom filters using the lf-filter DSL (defined in .lf files), shell escape hatches, or Python dependencies via PEP 723 and uv.
  • Lightweight Execution: Distributed as a small single binary, it is designed to be integrated into existing agent workflows without adding significant overhead.

Integration and Deployment

Lowfat can be integrated into various AI agent environments through several methods:

Agent-Specific Hooks

  • Claude Code: Integration is achieved by adding a PreToolUse hook to .claude/settings.json that triggers lowfat hook when a Bash matcher is detected.
  • OpenCode: The tool provides a dedicated installation command (lowfat opencode install) that writes a plugin to ~/.config/opencode/plugins/lowfat.ts to transparently rewrite commands.
  • Pi Agent: Integration is handled via the shellCommandPrefix setting in ~/.pi/agent/settings.json.

General Shell Integration

Users can enable Lowfat for any shell by adding eval "$(lowfat shell-init zsh)" (or bash) to their RC files and setting the LOWFAT_ENABLE=1 environment variable. It also auto-activates in environments where CLAUDECODE=1 or CODEX_ENV are present.

Direct Manual Usage

Lowfat can be used as a prefix to any command to slim the output immediately, such as lowfat git status or lowfat docker ps.

Operational Management

Lowfat provides a suite of commands for monitoring and tuning the filtering process:

  • lowfat info: Displays active filters and the pipeline for specific commands (e.g., lowfat info git).
  • lowfat stats: Tracks lifetime token savings and provides an audit trail of recent plugin executions.
  • lowfat history: Ranks commands by potential savings to help users identify where to customize filters.
  • lowfat level: Allows users to adjust the aggressiveness of compression (e.g., lowfat level ultra).

Technical Trade-offs and Community Discussion

The introduction of Lowfat has sparked a technical debate regarding the balance between token savings and agent reasoning quality.

The Risk of Over-Filtering

Several users have noted that aggressive filtering can lead to "hallucinations" or agent confusion if critical information—such as specific stack traces—is stripped away.

"I've tried rtx and lean-ctx and these tools seem to end up confusing the agent more than helping. Any saving is irrelevant if the agent decides to work around the tool and makes even more calls than it would otherwise."

Holistic Token Savings vs. Raw Output Reduction

Critics have pointed out that claiming a "91.8% saving in tokens" refers specifically to the raw CLI output of a single use case, rather than the total token cost of an entire agentic loop. Applying Amdahl's Law suggests that the overall system savings are lower than the reduction in raw output tokens.

Alternative Strategies

Community members suggested alternative approaches to reducing context bloat:

  • Narrower Querying: Teaching agents to use precise flags (e.g., kubectl get -o jsonpath instead of -o yaml) to prevent the noise from being generated in the first place.
  • Response Truncation: Saving full output to a temporary file and providing the agent with a path to that file, allowing the agent to query specific parts of the output as needed.
  • Local Pre-filtering: Using a smaller, cheaper local LLM to identify and filter the "important" parts of the output before passing it to a larger, more expensive model.

Sources