{"id":48453973,"url":"https://github.com/nasirus/pytk-ai","last_synced_at":"2026-04-06T22:01:11.066Z","repository":{"id":349364581,"uuid":"1201946849","full_name":"nasirus/pytk-ai","owner":"nasirus","description":"Lightweight, zero-dependency Python library that filters shell command output for LLM   token efficiency","archived":false,"fork":false,"pushed_at":"2026-04-05T14:55:22.000Z","size":180,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-05T16:23:17.453Z","etag":null,"topics":["ai-agents","ai-coding","cli","developer-tools","devtools","llm","output-filtering","python","shell","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nasirus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-05T11:36:15.000Z","updated_at":"2026-04-05T15:01:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"54dd20a6-efc8-471e-91d8-b69062826bf7","html_url":"https://github.com/nasirus/pytk-ai","commit_stats":null,"previous_names":["nasirus/pytk-ai"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nasirus/pytk-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasirus%2Fpytk-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasirus%2Fpytk-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasirus%2Fpytk-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasirus%2Fpytk-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nasirus","download_url":"https://codeload.github.com/nasirus/pytk-ai/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasirus%2Fpytk-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31491097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","cli","developer-tools","devtools","llm","output-filtering","python","shell","token-optimization"],"created_at":"2026-04-06T22:00:33.104Z","updated_at":"2026-04-06T22:01:11.033Z","avatar_url":"https://github.com/nasirus.png","language":"Python","readme":"# PYTK-AI\n\nA lightweight, dependency-free Python library and CLI that executes shell commands and filters their output into compact, token-efficient results for LLM consumption.\n\nPYTK-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.\n\n## Features\n\n- **Smart output filtering** -- 55+ filters for git, build tools, package managers, infrastructure commands, and more\n- **Zero dependencies** -- standard library only, installs anywhere Python 3.10+ runs\n- **Fail-safe design** -- if a filter fails, raw output passes through unchanged\n- **Exit code preservation** -- underlying command exit codes propagate correctly\n- **Compound command support** -- handles `\u0026\u0026`, `||`, `;`, `\u0026`, and simple pipes\n- **Embeddable** -- small enough to drop into agent toolchains, hooks, and scripts\n\n## Installation\n\n### From PyPI\n\n```bash\npip install pytk-ai\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv tool install pytk-ai\n```\n\n### From source\n\n```bash\ngit clone https://github.com/nasirus/pytk-ai.git\ncd pytk-ai\npip install -e .\n```\n\n## CLI Usage\n\n```bash\npytk-ai run git status\npytk-ai run \"cargo test \u0026\u0026 git push\"\npytk-ai run \"docker ps\"\n```\n\n## Library Usage\n\n```python\nfrom pytk_ai.runner import run_command\n\nresult = run_command(\"git status\")\nprint(result.filtered_output)\nprint(result.exit_code)\n```\n\n## Supported Filters\n\n| Category | Examples | Avg Token Reduction |\n|----------|----------|---------------------|\n| Git | `git status`, `git log`, `git diff`, `git pull` | 40% |\n| Build | `cargo build`, `tsc`, `next build` | 19% |\n| Files | `find`, `wc`, `rg` | 18% |\n| Go | `golangci-lint`, `go test` | 26% |\n| Infrastructure | `docker ps`, `kubectl`, `aws`, `docker logs` | 46% |\n| Packages | `npm list`, `pip list`, `pnpm list`, `bundle install` | 47% |\n| Python | `pytest`, `mypy`, `ruff` | 24% |\n| Ruby | `rubocop`, `rspec` | 30% |\n| Tests | `cargo test`, `pytest` | 36% |\n| Generic | ANSI stripping, progress bars, line collapse | 52% |\n\n## How It Works\n\n```\nCommand input\n    |\n    v\nPlan/Normalize --\u003e Execute subprocess --\u003e Apply filter --\u003e Structured result\n                                              |\n                                    (smart filtering, grouping,\n                                     deduplication, truncation)\n```\n\n1. **Planning** -- determines if the command benefits from PYTK-AI filtering\n2. **Execution** -- runs the command via subprocess with stdout/stderr capture\n3. **Filtering** -- applies domain-specific filters to compress the output\n4. **Result** -- returns a `CommandResult` with filtered output, exit code, and metadata\n\n\u003c!-- BENCHMARK-START --\u003e\n\n### Filter Benchmark Results\n\nToken estimator: `cl100k_base`\n\n#### By Category\n\n| Category | Scenarios | Avg Raw Tokens | Avg Filtered | Avg Reduction |\n|----------|-----------|---------------|-------------|---------------|\n| build | 8 | 163 | 163 | 7.2% |\n| files | 6 | 293 | 234 | 18.6% |\n| generic | 2 | 14 | 6 | 59.3% |\n| git | 8 | 52 | 26 | 41.9% |\n| go | 2 | 496 | 303 | 30.2% |\n| infra | 11 | 92 | 48 | 42.4% |\n| packages | 8 | 102 | 43 | 38.4% |\n| python | 3 | 143 | 135 | 5.6% |\n| ruby | 2 | 174 | 152 | 15.0% |\n| system | 4 | 821 | 757 | 19.5% |\n| tests | 2 | 48 | 46 | 2.8% |\n| **Total** | **56** | | | **21.4%** |\n\n#### Top Filters by Token Reduction\n\n| Filter | Command | Raw | Filtered | Saved | Reduction |\n|--------|---------|-----|----------|-------|-----------|\n| git.log | `git log -2` | 85 | 16 | 69 | 81.2% |\n| git.pull | `git pull` | 39 | 8 | 31 | 79.5% |\n| git.status | `git status` | 14 | 3 | 11 | 78.6% |\n| system.ls | `ls -la` | 327 | 72 | 255 | 78.0% |\n| kubectl.pods | `kubectl get pods -A -o json` | 107 | 26 | 81 | 75.7% |\n| npm.list | `npm list` | 505 | 145 | 360 | 71.3% |\n| git.commit | `git commit -m \"Add compact filter\"` | 21 | 7 | 14 | 66.7% |\n| aws.read | `aws ec2 describe-instances --output json` | 86 | 31 | 55 | 64.0% |\n| kubectl.services | `kubectl get services` | 75 | 27 | 48 | 64.0% |\n| git.diff | `git diff` | 67 | 28 | 39 | 58.2% |\n| docker.compose.ps | `docker compose ps` | 94 | 41 | 53 | 56.4% |\n| uv.sync | `uv sync` | 20 | 9 | 11 | 55.0% |\n| pnpm.list | `pnpm list --json` | 56 | 27 | 29 | 51.8% |\n| bundle.install | `bundle install` | 60 | 30 | 30 | 50.0% |\n| docker.ps | `docker ps` | 80 | 41 | 39 | 48.8% |\n\n\u003c!-- BENCHMARK-END --\u003e\n\n## License\n\nMIT License\n\n## Acknowledgements\n\nPYTK-AI is a Python port of **[RTK (Rust Token Killer)](https://github.com/rtk-ai/rtk)**, 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.\n\n## Citation\n\nIf you use PYTK-AI or RTK in your research or tooling, please cite the original project:\n\n```bibtex\n@software{rtk2024,\n  title     = {RTK: Rust Token Killer},\n  author    = {RTK AI},\n  url       = {https://github.com/rtk-ai/rtk},\n  year      = {2024},\n  note      = {High-performance CLI proxy that reduces LLM token consumption by 60-90\\%}\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasirus%2Fpytk-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnasirus%2Fpytk-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasirus%2Fpytk-ai/lists"}