PYTK-AI

A lightweight, dependency-free Python library and CLI that executes shell commands and filters their output into compact, token-efficient results for LLM consumption.

PYTK-AI reduces token usage by 25-50% across common development commands through smart filtering, deduplication, and noise removal -- helping AI coding agents work faster and cheaper.

Features

• Smart output filtering -- 55+ filters for git, build tools, package managers, infrastructure commands, and more
• Zero dependencies -- standard library only, installs anywhere Python 3.10+ runs
• Fail-safe design -- if a filter fails, raw output passes through unchanged
• Exit code preservation -- underlying command exit codes propagate correctly
• Compound command support -- handles &&, ||, ;, &, and simple pipes
• Embeddable -- small enough to drop into agent toolchains, hooks, and scripts

Installation

From PyPI

pip install pytk-ai

Or with uv:

uv tool install pytk-ai

From source

git clone https://github.com/nasirus/pytk-ai.git
cd pytk-ai
pip install -e .

CLI Usage

pytk-ai run git status
pytk-ai run "cargo test && git push"
pytk-ai run "docker ps"

Library Usage

from pytk_ai.runner import run_command

result = run_command("git status")
print(result.filtered_output)
print(result.exit_code)

Supported Filters

How It Works

Command input
    |
    v
Plan/Normalize --> Execute subprocess --> Apply filter --> Structured result
                                              |
                                    (smart filtering, grouping,
                                     deduplication, truncation)

1. Planning -- determines if the command benefits from PYTK-AI filtering
2. Execution -- runs the command via subprocess with stdout/stderr capture
3. Filtering -- applies domain-specific filters to compress the output
4. Result -- returns a CommandResult with filtered output, exit code, and metadata

Filter Benchmark Results

Token estimator: cl100k_base

Compared against rtk 0.35.0

By Category

Scenario Comparison (Top 25)

License

MIT License

Acknowledgements

PYTK-AI is a Python port of RTK (Rust Token Killer), a high-performance Rust CLI proxy that reduces LLM token consumption by 60-90%. The filtering strategies, command coverage, and architectural patterns in this project are derived from RTK's design.

Citation

If you use PYTK-AI or RTK in your research or tooling, please cite the original project:

@software{rtk2024,
  title     = {RTK: Rust Token Killer},
  author    = {RTK AI},
  url       = {https://github.com/rtk-ai/rtk},
  year      = {2024},
  note      = {High-performance CLI proxy that reduces LLM token consumption by 60-90\%}
}