agentleFS
Hacck3yHacck3y/ptk/.claude/skills/performance/SKILL.md

performance

Skill2 starsChanged 3 months agoApache-2.0View on GitHub

CLI performance optimization - startup time, memory usage, token savings benchmarking

  • Installs packages

86 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use app-brief, design-from-app and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • StijnusSkill

    app-brief

    One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.

    Also in 3 projects that use this

  • StijnusSkill

    design-from-app

    Rebuild the look of an app the user likes as a native SwiftUI design kit, by measuring its screenshots (sizes, spacing, type, colors, icons), building its parts, and comparing pixel by pixel until they match. Use when the user names an app whose look they want, shares screenshots of one, or says "make it look like X".

    Also in 3 projects that use this

  • RodrigoTomeESSkill

    web-quality-audit

    Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".

    Also in 9 projects that use this

  • launchapp-devSkill

    layout-grid

    Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior.

    Also in 3 projects that use this

  • MohamedAbdallah-14Skill

    app-icon

    Generate an app icon from a single 1024² master and fan out to iOS (AppIcon.appiconset with squircle-ready 1024 opaque), Android (adaptive foreground + background + Android 13 monochrome), PWA (192/512 + 512 maskable with 80% safe zone), and visionOS (3-layer parallax).

    Also in 3 projects that use this

  • vijpatel7Skill

    core-web-vitals

    Optimize Core Web Vitals (LCP, INP, CLS) for better page experience and search ranking. Use when asked to "improve Core Web Vitals", "fix LCP", "reduce CLS", "optimize INP", "page experience optimization", or "fix layout shifts".

    Also in 10 projects that use this

  • +1 more from Stijnus

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 58 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Automatically triggered: After filter changes, regex modifications, or dependency additions

    line 11
  2. Distinctive:

    Manual invocation: When performance degradation suspected or before release

    line 12
  3. Distinctive:

    Proactive: After any code change that could impact startup time or memory

    line 13
  4. Distinctive:

    Before making any changes, capture current performance:

    line 28
  5. Distinctive:

    Before committing filter changes:

    line 319

“Common” is measured: kept by at least 6 in 10 of the 58 edited versions of this file we could read. “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
SKILL.md

Performance Optimization Skill

Systematic performance analysis and optimization for PTK CLI tool, focusing on startup time (<10ms), memory usage (<5MB), and token savings (60-90%).

When to Use

  • Automatically triggered: After filter changes, regex modifications, or dependency additions
  • Manual invocation: When performance degradation suspected or before release
  • Proactive: After any code change that could impact startup time or memory

PTK Performance Targets

MetricTargetVerification MethodFailure Threshold
Startup time<10mshyperfine 'ptk <cmd>'>15ms = blocker
Memory usage<5MB resident/usr/bin/time -l ptk <cmd> (macOS)>7MB = blocker
Token savings60-90%Tests with count_tokens()<60% = blocker
Binary size<5MB strippedls -lh target/release/ptk>8MB = investigate

Performance Analysis Workflow

1. Establish Baseline

Before making any changes, capture current performance:

# Startup time baseline
hyperfine 'ptk git status' --warmup 3 --export-json /tmp/baseline_startup.json

# Memory usage baseline (macOS)
/usr/bin/time -l ptk git status 2>&1 | grep "maximum resident set size" > /tmp/baseline_memory.txt

# Memory usage baseline (Linux)
/usr/bin/time -v ptk git status 2>&1 | grep "Maximum resident set size" > /tmp/baseline_memory.txt

# Binary size baseline
ls -lh target/release/ptk | tee /tmp/baseline_binary_size.txt

2. Make Changes

Implement optimization or feature changes.

3. Rebuild and Measure

# Rebuild with optimizations
cargo build --release

# Measure startup time
hyperfine 'target/release/ptk git status' --warmup 3 --export-json /tmp/after_startup.json

# Measure memory usage
/usr/bin/time -l target/release/ptk git status 2>&1 | grep "maximum resident set size" > /tmp/after_memory.txt

# Check binary size
ls -lh target/release/ptk | tee /tmp/after_binary_size.txt

4. Compare Results

# Startup time comparison
hyperfine 'ptk git status' 'target/release/ptk git status' --warmup 3

# Example output:
#   Benchmark 1: ptk git status
#     Time (mean ± σ):       6.2 ms ±   0.3 ms    [User: 4.1 ms, System: 1.8 ms]
#   Benchmark 2: target/release/ptk git status
#     Time (mean ± σ):       7.8 ms ±   0.4 ms    [User: 5.2 ms, System: 2.1 ms]
#
#   Summary
#     'ptk git status' ran 1.26 times faster than 'target/release/ptk git status'

# Memory comparison
diff /tmp/baseline_memory.txt /tmp/after_memory.txt

# Binary size comparison
diff /tmp/baseline_binary_size.txt /tmp/after_binary_size.txt

5. Identify Regressions

Startup time regression (>15% increase or >2ms absolute):

# Profile with flamegraph
cargo install flamegraph
cargo flamegraph -- target/release/ptk git status

# Open flamegraph.svg
open flamegraph.svg
# Look for:
# - Repeated fixed-regex compilation (should be in LazyLock init)
# - Excessive allocations
# - File I/O on startup (should be zero)

Memory regression (>20% increase or >1MB absolute):

# Profile allocations (requires nightly)
cargo +nightly build --release -Z build-std
RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo +nightly build --release

# Use DHAT for heap profiling
cargo install dhat
# Add to main.rs:
# #[global_allocator]
# static ALLOC: dhat::Alloc = dhat::Alloc;

Token savings regression (<60% savings):

# Run token accuracy tests
cargo test test_token_savings

# Example failure output:
# Git log filter: expected ≥60% savings, got 52.3%

# Fix: Improve filter condensation logic

Common Performance Issues

Issue 1: Regex Recompilation

Symptom: Startup time >20ms, flamegraph shows regex compilation in hot path

Detection:

# Flamegraph shows Regex::new() calls during execution
cargo flamegraph -- target/release/ptk git log -10
# Check whether fixed patterns are compiled outside LazyLock statics

Fix:

// ❌ WRONG: Recompiled on every call
fn filter_line(line: &str) -> Option<&str> {
    let re = Regex::new(r"pattern").unwrap(); // RECOMPILED!
    re.find(line).map(|m| m.as_str())
}

// ✅ RIGHT: Compiled once with LazyLock
use std::sync::LazyLock;

static LINE_PATTERN: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"pattern").unwrap());

fn filter_line(line: &str) -> Option<&str> {
    LINE_PATTERN.find(line).map(|m| m.as_str())
}

Issue 2: Excessive Allocations

Symptom: Memory usage >5MB, many small allocations in flamegraph

Detection:

# DHAT heap profiling
cargo +nightly build --release
valgrind --tool=dhat target/release/ptk git status

Fix:

// ❌ WRONG: Allocates Vec for every line
fn filter_lines(input: &str) -> String {
    input.lines()
        .map(|line| line.to_string()) // Allocates String
        .collect::<Vec<_>>()
        .join("\n")
}

// ✅ RIGHT: Borrow slices, single allocation
fn filter_lines(input: &str) -> String {
    input.lines()
        .collect::<Vec<_>>() // Vec of &str (no String allocation)
        .join("\n")
}

Issue 3: Startup I/O

Symptom: Startup time varies wildly (5ms to 50ms), flamegraph shows file reads

Detection:

# strace on Linux
strace -c target/release/ptk git status 2>&1 | grep -E "open|read"

# dtrace on macOS (requires SIP disabled)
sudo dtrace -n 'syscall::open*:entry { @[execname] = count(); }' &
target/release/ptk git status
sudo pkill dtrace

Fix:

// ❌ WRONG: File I/O on startup
fn main() {
    let config = load_config().unwrap(); // Reads ~/.config/ptk/config.toml
    // ...
}

// ✅ RIGHT: Lazy config loading (only if needed)
fn main() {
    // No I/O on startup
    // Config loaded on-demand when first accessed
}

Issue 4: Dependency Bloat

Symptom: Binary size >5MB, many unused dependencies in Cargo.toml

Detection:

# Analyze dependency tree
cargo tree

# Find heavy dependencies
cargo install cargo-bloat
cargo bloat --release --crates

# Example output:
#  File  .text     Size Crate
#  0.5%   2.1%  42.3KB regex
#  0.4%   1.8%  36.1KB clap
# ...

Fix:

# ❌ WRONG: Full feature set (bloat)
[dependencies]
clap = { version = "4", features = ["derive", "color", "suggestions"] }

# ✅ RIGHT: Minimal features
[dependencies]
clap = { version = "4", features = ["derive"], default-features = false }

Optimization Techniques

Technique 1: LazyLock Initialization

Use case: Regex patterns, static configuration, one-time allocations

Implementation:

use regex::Regex;
use std::sync::LazyLock;

static COMMIT_HASH: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"[0-9a-f]{7,40}").unwrap());
static AUTHOR_LINE: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"^Author: (.+)$").unwrap());
static DATE_LINE: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"^Date: (.+)$").unwrap());

// Fixed regexes compile on first use and are then reused

Impact: ~5-10ms saved per regex pattern (if compiled at runtime)

Technique 2: Zero-Copy String Processing

Use case: Filter output without allocating intermediate Strings

Implementation:

// ❌ WRONG: Allocates String for every line
fn filter(input: &str) -> String {
    input.lines()
        .filter(|line| !line.is_empty())
        .map(|line| line.to_string()) // Allocates!
        .collect::<Vec<_>>()
        .join("\n")
}

// ✅ RIGHT: Borrow slices, single final allocation
fn filter(input: &str) -> String {
    input.lines()
        .filter(|line| !line.is_empty())
        .collect::<Vec<_>>() // Vec<&str> (no String alloc)
        .join("\n") // Single allocation for joined result
}

Impact: ~1-2MB memory saved, ~1-2ms startup saved

Technique 3: Minimal Dependencies

Use case: Reduce binary size and compile time

Implementation:

# Only include features you actually use
[dependencies]
clap = { version = "4", features = ["derive"], default-features = false }
serde = { version = "1", features = ["derive"], default-features = false }

# Avoid heavy dependencies
# ❌ Avoid: tokio (adds 5-10ms startup overhead)
# ❌ Avoid: full regex (use regex-lite if possible)
# ✅ Use: anyhow (lightweight error handling)
# ✅ Use: LazyLock (zero runtime overhead)

Impact: ~1-2MB binary size reduction, ~2-5ms startup saved

Performance Testing Checklist

Before committing filter changes:

Startup Time

  • Benchmark with hyperfine 'ptk <cmd>' --warmup 3
  • Verify <10ms mean time
  • Check variance (σ) is small (<1ms)
  • Compare against baseline (regression <2ms)

Memory Usage

  • Profile with /usr/bin/time -l ptk <cmd>
  • Verify <5MB resident set size
  • Compare against baseline (regression <1MB)

Token Savings

  • Run cargo test test_token_savings
  • Verify all filters achieve ≥60% savings
  • Check real fixtures used (not synthetic)

Binary Size

  • Check ls -lh target/release/ptk
  • Verify <5MB stripped binary
  • Run cargo bloat --release --crates if >5MB

Continuous Performance Monitoring

Pre-Commit Hook

Add to .claude/hooks/bash/pre-commit-performance.sh:

#!/bin/bash
# Performance regression check before commit

echo "🚀 Running performance checks..."

# Benchmark startup time
CURRENT_TIME=$(hyperfine 'ptk git status' --warmup 3 --export-json /tmp/perf.json 2>&1 | grep "Time (mean" | awk '{print $4}')

# Extract numeric value (remove "ms")
CURRENT_MS=$(echo $CURRENT_TIME | sed 's/ms//')

# Check if > 10ms
if (( $(echo "$CURRENT_MS > 10" | bc -l) )); then
    echo "❌ Startup time regression: ${CURRENT_MS}ms (target: <10ms)"
    exit 1
fi

# Check binary size
BINARY_SIZE=$(ls -l target/release/ptk | awk '{print $5}')
MAX_SIZE=$((5 * 1024 * 1024))  # 5MB

if [ $BINARY_SIZE -gt $MAX_SIZE ]; then
    echo "❌ Binary size regression: $(($BINARY_SIZE / 1024 / 1024))MB (target: <5MB)"
    exit 1
fi

echo "✅ Performance checks passed"

CI/CD Integration

Add to .github/workflows/ci.yml:

- name: Performance Regression Check
  run: |
    cargo build --release
    cargo install hyperfine

    # Benchmark startup time
    hyperfine 'target/release/ptk git status' --warmup 3 --max-runs 10

    # Check binary size
    BINARY_SIZE=$(ls -l target/release/ptk | awk '{print $5}')
    MAX_SIZE=$((5 * 1024 * 1024))
    if [ $BINARY_SIZE -gt $MAX_SIZE ]; then
      echo "Binary too large: $(($BINARY_SIZE / 1024 / 1024))MB"
      exit 1
    fi

Performance Optimization Priorities

Priority order (highest to lowest impact):

  1. 🔴 LazyLock regex (5-10ms per pattern if compiled at runtime)
  2. 🔴 Remove startup I/O (10-50ms for config file reads)
  3. 🟡 Zero-copy processing (1-2MB memory, 1-2ms startup)
  4. 🟡 Minimal dependencies (1-2MB binary, 2-5ms startup)
  5. 🟢 Algorithm optimization (varies, measure first)

When in doubt: Profile first with flamegraph, then optimize the hottest path.

Tools Reference

ToolPurposeCommand
hyperfineBenchmark startup timehyperfine 'ptk <cmd>' --warmup 3
timeMemory usage (macOS)/usr/bin/time -l ptk <cmd>
timeMemory usage (Linux)/usr/bin/time -v ptk <cmd>
flamegraphCPU profilingcargo flamegraph -- ptk <cmd>
cargo bloatBinary size analysiscargo bloat --release --crates
cargo treeDependency treecargo tree
DHATHeap profilingcargo +nightly build && valgrind --tool=dhat
straceSystem call tracing (Linux)strace -c target/release/ptk <cmd>
dtraceSystem call tracing (macOS)sudo dtrace -n 'syscall::open*:entry'

Install tools:

# macOS
brew install hyperfine

# Linux / cross-platform via cargo
cargo install hyperfine
cargo install flamegraph
cargo install cargo-bloat

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.