peeka-diagnostics

AI skill for runtime Python diagnostics using peeka-cli.

Description

This is an AI agent skill that provides runtime diagnostic capabilities for Python applications. It enables debugging of live Python processes, diagnosing performance issues, finding memory leaks, tracing function calls, watching variables at runtime, and analyzing thread issues.

The skill is designed to be used with AI agents that need to perform runtime Python debugging tasks. All diagnostic output is in JSONL format for structured analysis and automation.

Triggers

Use this skill when you need to:

• Debug Python processes
• Diagnose slow application performance
• Find memory leaks
• Trace function calls and execution flow
• Watch variable values at runtime
• Analyze thread deadlocks or synchronization issues
• Profile Python code
• Inspect runtime state of running applications

Dependencies

• peeka-cli: Command-line tool for Python runtime diagnostics
  • Installation: pip install peeka-cli
  • Requires Python 3.8+
  • For Python < 3.14: GDB and ptrace capabilities required
  • For Python 3.14+: Uses native PEP 768 attach mechanism

Usage

This skill provides a comprehensive reference for using peeka-cli commands:

• Session Management: attach, detach, reset
• Streaming Observation: watch, trace, stack, monitor, top
• Query & Inspection: sc, sm, memory, inspect, logger, thread
• Script Bootstrap: peeka-cli run for observing short-lived scripts

For detailed command reference and examples, see SKILL.md.

Quick Example

# Find Python process
pgrep -af "python.*myapp"

# Watch a function in a running process
peeka-cli attach <PID>
peeka-cli watch "mymodule.myfunction" -n 10

# Trace execution with timing
peeka-cli trace "mymodule.main" -d 3 -n 1

License

Apache License 2.0 — see LICENSE for details.

Links

• Main Repository: peeka-project/peeka
• peeka-cli Tool: Available on PyPI as peeka-cli
• Peeka Diagnostics Skill: peeka-project/peeka-diagnostics