agentleFS
Hacck3yHacck3y/ptk/CLAUDE.md

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

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
  1. Very specific:

    If ptk gain fails, you have the wrong package installed.

    line 23
  2. Distinctive:

    Guaranteed compatibility: Always works even if PTK doesn't implement the command

    line 89
  3. Very specific:

    All proxy commands appear in ptk gain --history with 0% bash output reduction (input = output).

    line 98
  4. Distinctive:

    Fallback pattern: if filter fails, execute raw command unchanged

    line 107
  5. Distinctive:

    CRITICAL: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:

    line 117
  6. Distinctive:

    Never commit code that hasn't passed all 3 checks

    line 124
  7. Distinctive:

    If build fails, fix it immediately before continuing to next task

    line 126
  8. Distinctive:

    Stay focused on the task: Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.

    line 148
  9. Distinctive:

    Rule: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.

    line 150
  10. Distinctive:

    When user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):

    line 165
  11. Distinctive:

    Execute sequentially: Follow plan order unless explicitly told otherwise

    line 167
  12. Distinctive:

    Never skip or reorder: If a step is blocked, report it and ask before proceeding

    line 169
  13. Distinctive:

    Track progress: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps

    line 170
  14. Distinctive:

    Validate assumptions: Before starting, verify all referenced file paths exist and working directory is correct

    line 171

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 locally

Testing

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 # preferred

Pre-commit Gate

cargo fmt --all && cargo clippy --all-targets && cargo test --all

Package 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 works

All 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
  • LazyLock statics 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 --all

Rules:

  • 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.):

  1. Execute sequentially: Follow plan order unless explicitly told otherwise
  2. Commit after each logical step: One commit per completed phase/task
  3. Never skip or reorder: If a step is blocked, report it and ask before proceeding
  4. Track progress: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps
  5. Validate assumptions: Before starting, verify all referenced file paths exist and working directory is correct

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.