ptk-ai 0.1.2

Python Token Killer — token-optimized CLI proxy for LLM context compression

High-performance CLI proxy that reduces LLM token consumption by 60-90%

Website • Install • Troubleshooting • Architecture • Discord

English • Francais • 中文 • 日本語 • 한국어 • Espanol

---

ptk filters and compresses command outputs before they reach your LLM context. Single Python binary, 100+ supported commands, <10ms overhead.

Token Savings (30-min Claude Code Session)

Operation	Frequency	Standard	ptk	Savings
ls / tree	10x	2,000	400	-80%
cat / read	20x	40,000	12,000	-70%
grep / rg	8x	16,000	3,200	-80%
git status	10x	3,000	600	-80%
git diff	5x	10,000	2,500	-75%
git log	5x	2,500	500	-80%
git add/commit/push	8x	1,600	120	-92%
cargo test / npm test	5x	25,000	2,500	-90%
ruff check	3x	3,000	600	-80%
pytest	4x	8,000	800	-90%
go test	3x	6,000	600	-90%
docker ps	3x	900	180	-80%
Total		~118,000	~23,900	-80%

Estimates based on medium-sized TypeScript/Python projects. Actual savings vary by project size.

Installation

PyPI (recommended)

pip install ptk-ai

pipx (Isolated)

pipx install ptk-ai

From Source (Development)

git clone https://github.com/maravedi/ptk
cd ptk
pip install -e .

Pre-built Binaries

Download from releases:

• macOS: ptk-x86_64-apple-darwin.tar.gz / ptk-aarch64-apple-darwin.tar.gz
• Linux: ptk-x86_64-unknown-linux-musl.tar.gz / ptk-aarch64-unknown-linux-gnu.tar.gz
• Windows: ptk-x86_64-pc-windows-msvc.zip

Verify Installation

ptk --version   # Should show "ptk 0.1.0"
ptk gain        # Should show token savings stats

Quick Start

# 1. Install for your AI tool
ptk init -g                     # Claude Code / Copilot (default)
ptk init -g --gemini            # Gemini CLI
ptk init -g --codex             # Codex (OpenAI)
ptk init -g --agent cursor      # Cursor
ptk init --agent windsurf       # Windsurf
ptk init --agent cline          # Cline / Roo Code

# 2. Restart your AI tool, then test
git status  # Automatically rewritten to ptk git status

The hook transparently rewrites Bash commands (e.g., git status -> ptk git status) before execution. Claude never sees the rewrite, it just gets compressed output.

Important: the hook only runs on Bash tool calls. Claude Code built-in tools like Read, Grep, and Glob do not pass through the Bash hook, so they are not auto-rewritten. To get PTK's compact output for those workflows, use shell commands (cat/head/tail, rg/grep, find) or call ptk read, ptk grep, or ptk find directly.

Windows / PowerShell agents: run ptk hooks init --shell powershell (or ptk hooks hook claude --shell powershell) to configure the PowerShell hookCommand. The generated snippet evaluates $Env:CMD, routes it through ptk rewrite, and writes the rewritten command only when PTK supports it; otherwise it prints the original command. Restart the agent after installing so the new hook takes effect.

How It Works

  Without ptk:                                    With ptk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  PTK  -->  git
    ^                                   |            ^                      |          |
    |        ~2,000 tokens (raw)        |            |   ~200 tokens        | filter   |
    +-----------------------------------+            +------- (filtered) ---+----------+

Four strategies applied per command type:

1. Smart Filtering - Removes noise (comments, whitespace, boilerplate)
2. Grouping - Aggregates similar items (files by directory, errors by type)
3. Truncation - Keeps relevant context, cuts redundancy
4. Deduplication - Collapses repeated log lines with counts

Commands

Files

ptk ls .                        # Token-optimized directory tree
ptk read file.rs                # Smart file reading
ptk read file.rs -l aggressive  # Signatures only (strips bodies)
ptk smart file.rs               # 2-line heuristic code summary
ptk find "*.rs" .               # Compact find results
ptk grep "pattern" .            # Grouped search results
ptk diff file1 file2            # Condensed diff

Git

ptk git status                  # Compact status
ptk git log -n 10               # One-line commits
ptk git diff                    # Condensed diff
ptk git add                     # -> "ok"
ptk git commit -m "msg"         # -> "ok abc1234"
ptk git push                    # -> "ok main"
ptk git pull                    # -> "ok 3 files +10 -2"

GitHub CLI

ptk gh pr list                  # Compact PR listing
ptk gh pr view 42               # PR details + checks
ptk gh issue list               # Compact issue listing
ptk gh run list                 # Workflow run status

Test Runners

ptk test cargo test             # Show failures only (-90%)
ptk err npm run build           # Errors/warnings only
ptk vitest run                  # Vitest compact (failures only)
ptk playwright test             # E2E results (failures only)
ptk pytest                      # Python tests (-90%)
ptk go test                     # Go tests (NDJSON, -90%)
ptk cargo test                  # Cargo tests (-90%)
ptk rake test                   # Ruby minitest (-90%)
ptk rspec                       # RSpec tests (JSON, -60%+)

Build & Lint

ptk lint                        # ESLint grouped by rule/file
ptk lint biome                  # Supports other linters
ptk tsc                         # TypeScript errors grouped by file
ptk next build                  # Next.js build compact
ptk prettier --check .          # Files needing formatting
ptk cargo build                 # Cargo build (-80%)
ptk cargo clippy                # Cargo clippy (-80%)
ptk ruff check                  # Python linting (JSON, -80%)
ptk golangci-lint run           # Go linting (JSON, -85%)
ptk rubocop                     # Ruby linting (JSON, -60%+)

Package Managers

ptk pnpm list                   # Compact dependency tree
ptk pip list                    # Python packages (auto-detect uv)
ptk pip outdated                # Outdated packages
ptk bundle install              # Ruby gems (strip Using lines)
ptk prisma generate             # Schema generation (no ASCII art)

Containers

ptk docker ps                   # Compact container list
ptk docker images               # Compact image list
ptk docker logs <container>     # Deduplicated logs
ptk docker compose ps           # Compose services
ptk kubectl pods                # Compact pod list
ptk kubectl logs <pod>          # Deduplicated logs
ptk kubectl services            # Compact service list

Data & Analytics

ptk json config.json            # Structure without values
ptk deps                        # Dependencies summary
ptk env -f AWS                  # Filtered env vars
ptk log app.log                 # Deduplicated logs
ptk curl <url>                  # Auto-detect JSON + schema
ptk wget <url>                  # Download, strip progress bars
ptk summary <long command>      # Heuristic summary
ptk proxy <command>             # Raw passthrough + tracking

Token Savings Analytics

ptk gain                        # Summary stats
ptk gain --graph                # ASCII graph (last 30 days)
ptk gain --history              # Recent command history
ptk gain --daily                # Day-by-day breakdown
ptk gain --all --format json    # JSON export for dashboards

ptk discover                    # Find missed savings opportunities
ptk discover --all --since 7    # All projects, last 7 days

ptk session                     # Show PTK adoption across recent sessions

Global Flags

-u, --ultra-compact    # ASCII icons, inline format (extra token savings)
-v, --verbose          # Increase verbosity (-v, -vv, -vvv)

Examples

Directory listing:

# ls -la (45 lines, ~800 tokens)        # ptk ls (12 lines, ~150 tokens)
drwxr-xr-x  15 user staff 480 ...       my-project/
-rw-r--r--   1 user staff 1234 ...       +-- src/ (8 files)
...                                      |   +-- main.rs
                                         +-- Cargo.toml

Git operations:

# git push (15 lines, ~200 tokens)       # ptk git push (1 line, ~10 tokens)
Enumerating objects: 5, done.             ok main
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
...

Test output:

# cargo test (200+ lines on failure)     # ptk test cargo test (~20 lines)
running 15 tests                          FAILED: 2/15 tests
test utils::test_parse ... ok               test_edge_case: assertion failed
test utils::test_format ... ok              test_overflow: panic at utils.rs:18
...

Auto-Rewrite Hook

The most effective way to use ptk. The hook transparently intercepts Bash commands and rewrites them to ptk equivalents before execution.

Result: 100% ptk adoption across all conversations and subagents, zero token overhead.

Scope note: this only applies to Bash tool calls. Claude Code built-in tools such as Read, Grep, and Glob bypass the hook, so use shell commands or explicit ptk commands when you want PTK filtering there.

Setup

ptk init -g                 # Install hook + PTK.md (recommended)
ptk init -g --opencode      # OpenCode plugin (instead of Claude Code)
ptk init -g --auto-patch    # Non-interactive (CI/CD)
ptk init -g --hook-only     # Hook only, no PTK.md
ptk init --show             # Verify installation

After install, restart Claude Code.

Supported AI Tools

PTK supports 10 AI coding tools. Each integration transparently rewrites shell commands to ptk equivalents for 60-90% token savings.

| Jules (Google Cloud) | ptk init --agent jules | .julesrules + ptk-setup.sh | | Baton | ptk init --agent baton | Alias for Jules integration | | Cursor | ptk init -g --agent cursor | preToolUse hook (bash/ps1) | | Gemini CLI | ptk init -g --gemini | BeforeTool hook (bash/ps1) | | Codex | ptk init -g --codex | AGENTS.md + PTK.md instructions | | Windsurf | ptk init --agent windsurf | .windsurfrules (project-scoped) | | Cline / Roo Code | ptk init --agent cline | .clinerules (project-scoped) | | Claude Code | ptk init -g | PreToolUse hook (bash) | | GitHub Copilot | ptk init -g --copilot | PreToolUse hook (json/prompt) | | PowerShell Agents | ptk init --shell powershell | Unified PowerShell hook |

Claude Code (default)

ptk init -g                 # Install hook + PTK.md
ptk init -g --auto-patch    # Non-interactive (CI/CD)
ptk init --show             # Verify installation
ptk init -g --uninstall     # Remove

GitHub Copilot (VS Code + CLI)

ptk init -g --copilot         # Install hook + instructions

Creates .github/hooks/ptk-rewrite.json (PreToolUse hook) and .github/copilot-instructions.md (prompt-level awareness).

The hook (ptk hook copilot) auto-detects the format:

• VS Code Copilot Chat: transparent rewrite via updatedInput (same as Claude Code)
• Copilot CLI: deny-with-suggestion (CLI does not support updatedInput yet — see copilot-cli#2013)

Cursor

ptk init -g --agent cursor

Creates ~/.cursor/hooks/ptk-rewrite.sh + patches ~/.cursor/hooks.json with preToolUse matcher. Works with both Cursor editor and cursor-agent CLI.

Gemini CLI

ptk init -g --gemini
ptk init -g --gemini --uninstall

Creates ~/.gemini/hooks/ptk-hook-gemini.sh + patches ~/.gemini/settings.json with BeforeTool hook.

Codex (OpenAI)

ptk init -g --codex          # ~/.codex/PTK.md + ~/.codex/AGENTS.md
ptk init --codex             # ./PTK.md + ./AGENTS.md in the current directory
ptk hook codex -g            # same as global install above

Creates PTK.md (usage + examples for Bash and PowerShell) and patches AGENTS.md with an @PTK.md reference, matching the RTK Codex flow. Legacy <!-- rtk-instructions --> blocks and @RTK.md lines in AGENTS.md are migrated away on install. Restart Codex CLI after installing.

Windsurf

ptk init --agent windsurf

Creates .windsurfrules in the current project. Cascade reads rules and prefixes commands with ptk.

Cline / Roo Code

ptk init --agent cline

Creates .clinerules in the current project. Cline reads rules and prefixes commands with ptk.

OpenCode

ptk init -g --opencode

Creates ~/.config/opencode/plugins/ptk.ts. Uses tool.execute.before hook.

OpenClaw

openclaw plugins install ./openclaw

Plugin in openclaw/ directory. Uses before_tool_call hook, delegates to ptk rewrite.

Mistral Vibe (planned)

Blocked on upstream BeforeToolCallback support (mistral-vibe#531, PR #533). Tracked in #800.

Commands Rewritten

Raw Command	Rewritten To
git status/diff/log/add/commit/push/pull	ptk git ...
gh pr/issue/run	ptk gh ...
cargo test/build/clippy	ptk cargo ...
cat/head/tail <file>	ptk read <file>
rg/grep <pattern>	ptk grep <pattern>
ls	ptk ls
vitest/jest	ptk vitest run
tsc	ptk tsc
eslint/biome	ptk lint
prettier	ptk prettier
playwright	ptk playwright
prisma	ptk prisma
ruff check/format	ptk ruff ...
pytest	ptk pytest
pip list/install	ptk pip ...
go test/build/vet	ptk go ...
golangci-lint	ptk golangci-lint
rake test / rails test	ptk rake test
rspec / bundle exec rspec	ptk rspec
rubocop / bundle exec rubocop	ptk rubocop
bundle install/update	ptk bundle ...
docker ps/images/logs	ptk docker ...
kubectl get/logs	ptk kubectl ...
curl	ptk curl
pnpm list/outdated	ptk pnpm ...

Commands already using ptk, heredocs (<<), and unrecognized commands pass through unchanged.

Configuration

Config File

~/.config/ptk/config.toml (macOS: ~/Library/Application Support/ptk/config.toml):

[tracking]
database_path = "/path/to/custom.db"  # default: ~/.local/share/ptk/history.db

[hooks]
exclude_commands = ["curl", "playwright"]  # skip rewrite for these

[tee]
enabled = true          # save raw output on failure (default: true)
mode = "failures"       # "failures", "always", or "never"
max_files = 20          # rotation limit

Tee: Full Output Recovery

When a command fails, PTK saves the full unfiltered output so the LLM can read it without re-executing:

FAILED: 2/15 tests
[full output: ~/.local/share/ptk/tee/1707753600_cargo_test.log]

Uninstall

ptk init -g --uninstall     # Remove hook, PTK.md, settings.json entry
cargo uninstall ptk          # Remove binary
brew uninstall ptk           # If installed via Homebrew

Documentation

• TROUBLESHOOTING.md - Fix common issues
• INSTALL.md - Detailed installation guide
• ARCHITECTURE.md - Technical architecture
• SECURITY.md - Security policy and PR review process
• AUDIT_GUIDE.md - Token savings analytics guide

Privacy & Telemetry

PTK collects anonymous, aggregate usage metrics once per day, enabled by default. This helps prioritize development. See opt-out options below.

What is collected:

• Device hash (salted SHA-256 — per-user random salt stored locally, not reversible)
• PTK version, OS, architecture
• Command count (last 24h) and top command names (e.g. "git", "cargo" — no arguments, no file paths)
• Token savings percentage

What is NOT collected: source code, file paths, command arguments, secrets, environment variables, or any personally identifiable information.

Opt-out (any of these):

# Environment variable
export PTK_TELEMETRY_DISABLED=1

# Or in config file (~/.config/ptk/config.toml)
[telemetry]
enabled = false

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Join the community on Discord.

License

MIT License - see LICENSE for details.