Metadata-Version: 2.4
Name: ptk-ai
Version: 0.1.2
Summary: Python Token Killer — token-optimized CLI proxy for LLM context compression
Project-URL: Homepage, https://github.com/maravedi/ptk
Project-URL: Repository, https://github.com/maravedi/ptk
Project-URL: Issues, https://github.com/maravedi/ptk/issues
Project-URL: Documentation, https://github.com/maravedi/ptk/blob/main/README.md
Author-email: David Frazer <david.frazer@vizius.com>
License: MIT
License-File: LICENSE
Keywords: cli,compression,llm,optimization,proxy,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://avatars.githubusercontent.com/u/258253854?v=4" alt="PTK - Python Token Killer" width="500">
</p>

<p align="center">
  <strong>High-performance CLI proxy that reduces LLM token consumption by 60-90%</strong>
</p>

<p align="center">
  <a href="https://github.com/maravedi/ptk/actions"><img src="https://github.com/maravedi/ptk/workflows/Security%20Check/badge.svg" alt="CI"></a>
  <a href="https://github.com/maravedi/ptk/releases"><img src="https://img.shields.io/github/v/release/maravedi/ptk" alt="Release"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://pypi.org/project/ptk-ai/"><img src="https://img.shields.io/pypi/v/ptk-ai" alt="PyPI"></a>
</p>

<p align="center">
  <a href="https://www.ptk-ai.app">Website</a> &bull;
  <a href="#installation">Install</a> &bull;
  <a href="docs/TROUBLESHOOTING.md">Troubleshooting</a> &bull;
  <a href="ARCHITECTURE.md">Architecture</a> &bull;
  <a href="https://discord.gg/RySmvNF5kF">Discord</a>
</p>

<p align="center">
  <a href="README.md">English</a> &bull;
  <a href="README_fr.md">Francais</a> &bull;
  <a href="README_zh.md">中文</a> &bull;
  <a href="README_ja.md">日本語</a> &bull;
  <a href="README_ko.md">한국어</a> &bull;
  <a href="README_es.md">Espanol</a>
</p>

---

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)

```bash
pip install ptk-ai
```

### pipx (Isolated)

```bash
pipx install ptk-ai
```

### From Source (Development)

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

### Pre-built Binaries

Download from [releases](https://github.com/maravedi/ptk/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

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

## Quick Start

```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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

```bash
-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

```bash
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)

```bash
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)

```bash
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](https://github.com/github/copilot-cli/issues/2013))

### Cursor

```bash
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

```bash
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)

```bash
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](https://github.com/maravedi/ptk/blob/master/src/hooks/init.rs). Legacy `<!-- rtk-instructions -->` blocks and `@RTK.md` lines in `AGENTS.md` are migrated away on install. Restart Codex CLI after installing.

### Windsurf

```bash
ptk init --agent windsurf
```

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

### Cline / Roo Code

```bash
ptk init --agent cline
```

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

### OpenCode

```bash
ptk init -g --opencode
```

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

### OpenClaw

```bash
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](https://github.com/mistralai/mistral-vibe/issues/531), [PR #533](https://github.com/mistralai/mistral-vibe/pull/533)). Tracked in [#800](https://github.com/maravedi/ptk/issues/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`):

```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

```bash
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](docs/TROUBLESHOOTING.md)** - Fix common issues
- **[INSTALL.md](INSTALL.md)** - Detailed installation guide
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture
- **[SECURITY.md](SECURITY.md)** - Security policy and PR review process
- **[AUDIT_GUIDE.md](docs/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):
```bash
# 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](https://github.com/maravedi/ptk).

Join the community on [Discord](https://discord.gg/RySmvNF5kF).

## License

MIT License - see [LICENSE](LICENSE) for details.
