ptk
CLAUDE.md2 starsChanged 3 months agoApache-2.0View on GitHub
ptk is a high-performance CLI proxy that minimizes LLM token consumption by filtering and compressing command outputs. It reduces bash output by 60-90% on common development operations through smart filtering, grouping, truncation, and deduplication. All percentages in this repo measure bash output, not your bill. PTK ships no tokenizer (src/core/tracking.rs estimates tokens as bytes / 4), so the ratios are reliable but the absolute token counts are approximate. This is a fork with critical fixes for git argument parsing and…
- Installs packages
In this repository13 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- code-simplifierSkill
- design-patternsSkill
- issue-triageSkill
- performanceSkill
- pr-reviewSkill
- pr-triageSkill
- ptk-tddSkill
- ptk-triageSkill
- repo-recapSkill
- security-guardianSkill
- shipSkill
- tdd-rustSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
14 rules. About 0 are common, 12 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
If ptk gain fails, you have the wrong package installed.
- Distinctive: line 89
Guaranteed compatibility: Always works even if PTK doesn't implement the command
- Very specific: line 98
All proxy commands appear in ptk gain --history with 0% bash output reduction (input = output).
- Distinctive: line 107
Fallback pattern: if filter fails, execute raw command unchanged
- Distinctive: line 117
CRITICAL: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:
- Distinctive: line 124
Never commit code that hasn't passed all 3 checks
- Distinctive: line 126
If build fails, fix it immediately before continuing to next task
- Distinctive: line 148
Stay focused on the task: Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.
- Distinctive: line 150
Rule: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.
- Distinctive: line 165
When user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):
- Distinctive: line 167
Execute sequentially: Follow plan order unless explicitly told otherwise
- Distinctive: line 169
Never skip or reorder: If a step is blocked, report it and ask before proceeding
- Distinctive: line 170
Track progress: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps
- Distinctive: line 171
Validate assumptions: Before starting, verify all referenced file paths exist and working directory is correct
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
ptk is a high-performance CLI proxy that minimizes LLM token consumption by filtering and compressing command outputs. It reduces bash output by 60-90% on common development operations through smart filtering, grouping, truncation, and deduplication. All percentages in this repo measure bash output, not your bill. PTK ships no tokenizer (src/core/tracking.rs estimates tokens as bytes / 4), so the ratios are reliable but the absolute token counts are approximate.
This is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).
Name Collision Warning
Two different "ptk" projects exist:
- This project: ptk (hacck3y/ptk)
- reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)
Verify correct installation:
ptk --version # Should show "ptk 0.28.2" (or newer)
ptk gain # Should show token savings stats (NOT "command not found")If ptk gain fails, you have the wrong package installed.
Development Commands
Note: If ptk is installed, prefer
ptk <cmd>over raw commands for token-optimized output. All commands work with passthrough support even for subcommands ptk doesn't specifically handle.
Build & Run
cargo build # raw
ptk cargo build # preferred (token-optimized)
cargo build --release # release build (optimized)
cargo run -- <command> # run directly
cargo install --path . # install locallyTesting
cargo test # all tests
ptk cargo test # preferred (token-optimized)
cargo test <test_name> # specific test
cargo test <module_name>:: # module tests
cargo test -- --nocapture # with stdout
bash scripts/test-all.sh # smoke tests (installed binary required)Linting & Quality
cargo check # check without building
cargo fmt # format code
cargo clippy --all-targets # all clippy lints
ptk cargo clippy --all-targets # preferredPre-commit Gate
cargo fmt --all && cargo clippy --all-targets && cargo test --allPackage Building
cargo deb # DEB package (needs cargo-deb)
cargo generate-rpm # RPM package (needs cargo-generate-rpm, after release build)Architecture
ptk uses a command proxy architecture: main.rs routes CLI commands via a Clap Commands enum to specialized filter modules in src/cmds/*/, each of which executes the underlying command and compresses its output. Token savings are tracked in SQLite via src/core/tracking.rs.
For the full architecture, component details, and module development patterns, see:
- ARCHITECTURE.md — System design, module organization, filtering strategies, error handling
- docs/contributing/TECHNICAL.md — End-to-end flow, folder map, hook system, filter pipeline
Module responsibilities are documented in each folder's README.md and each file's //! doc header. Browse src/cmds/*/ to discover available filters.
Supported ecosystems: git/gh/gt, cargo, go/golangci-lint, npm/pnpm/npx, ruff/pytest/pip/mypy, rspec/rubocop/rake, dotnet, playwright/vitest/jest, docker/kubectl/aws, gradlew/mvn, php/artisan/phpunit/phpstan/pest.
Proxy Mode
Purpose: Execute commands without filtering but track usage for metrics.
Usage: ptk proxy <command> [args...]
Benefits:
- Bypass PTK filtering: Workaround bugs or get full unfiltered output
- Track usage metrics: Measure which commands Claude uses most (visible in
ptk gain --history) - Guaranteed compatibility: Always works even if PTK doesn't implement the command
Examples:
ptk proxy git log --oneline -20 # Full git log output (no truncation)
ptk proxy npm install express # Raw npm output (no filtering)
ptk proxy curl https://api.example.com/data # Any command worksAll proxy commands appear in ptk gain --history with 0% bash output reduction (input = output).
Coding Rules
Rust patterns, error handling, and anti-patterns are defined in .claude/rules/rust-patterns.md (auto-loaded into context). Key points:
- anyhow::Result everywhere, always
.context("description")? - No unwrap() in production code
LazyLockstatics for all regex (never compile on every function call)- Fallback pattern: if filter fails, execute raw command unchanged
- No async: single-threaded by design (startup <10ms)
- Exit code propagation:
std::process::exit(code)on child failure
Testing strategy and performance targets are defined in .claude/rules/cli-testing.md (auto-loaded). Key targets: <10ms startup, <5MB memory, 60-90% reduction in bash output bytes.
For contribution workflow and design philosophy, see CONTRIBUTING.md. For the step-by-step filter implementation checklist, see src/cmds/README.md.
Build Verification (Mandatory)
CRITICAL: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:
cargo fmt --all && cargo clippy --all-targets && cargo test --allRules:
- Never commit code that hasn't passed all 3 checks
- Fix ALL clippy warnings before moving on (zero tolerance)
- If build fails, fix it immediately before continuing to next task
Performance verification (for filter changes):
hyperfine 'ptk git log -10' --warmup 3 # before
cargo build --release
hyperfine 'target/release/ptk git log -10' --warmup 3 # after (should be <10ms)Working Directory Confirmation
ALWAYS confirm working directory before starting any work:
pwd # Verify you're in the ptk project root
git branch # Verify correct branch (main, feature/*, etc.)Never assume which project to work in. Always verify before file operations.
Avoiding Rabbit Holes
Stay focused on the task. Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.
Rule: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.
Examples of rabbit holes to avoid:
- Excessive regex pattern testing (trust snapshot tests, don't manually verify 20 edge cases)
- Deep diving into external command documentation (use fixtures, don't research git/cargo internals)
- Over-testing cross-platform behavior (test macOS + Linux, trust CI for Windows)
- Verifying API signatures across multiple crate versions (use docs.rs if needed, don't clone repos)
When to stop and ask:
- "Should I research X external API behavior?" → ASK if it requires >3 commands
- "Should I test Y edge case?" → ASK if not mentioned in requirements
- "Should I verify Z across N platforms?" → ASK if N > 2
Plan Execution Protocol
When user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):
- Execute sequentially: Follow plan order unless explicitly told otherwise
- Commit after each logical step: One commit per completed phase/task
- Never skip or reorder: If a step is blocked, report it and ask before proceeding
- Track progress: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps
- Validate assumptions: Before starting, verify all referenced file paths exist and working directory is correct
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

