Several causes still fit
A race, stale state, and a dropped callback can produce the same symptom. Probes separate them.
Pi extension 0.1.9
Debug Mode built around evidence.
pi-debug-mode is a Cursor-style Debug Mode for the Pi coding agent. Its injected instructions ask Pi to test competing hypotheses with targeted runtime probes before changing code.
01 / WHEN
Use it when static inspection is not enough.
An ordinary prompt still fits a direct question or an obvious static defect. Debug Mode fits bugs whose cause depends on what the program does while it runs.
The bug needs human action
Use the checkpoint when only a person can reproduce the sequence or confirm the visible result.
Logs need exact placement
Mark temporary probes with pi-debug at the branches that distinguish each hypothesis.
A fix needs a second run
Repeat the same reproduction before removing probes or reporting that the issue is fixed.
02 / METHOD
Five steps from symptom to checked fix.
The extension adds a fixed evidence loop to the current Pi session. It does not replace Pi or start a separate service.
-
Inspect the execution path
The injected instructions ask Pi to read the relevant code and list three to five competing hypotheses before mutation.
-
Add targeted runtime probes
The instructions ask Pi to add the smallest set of temporary
pi-debugprobes that can distinguish those hypotheses. -
Reproduce once
debug_reproductionoffers Guided feedback or Autopilot. Autopilot keeps machine checks with Pi and reserves another checkpoint for visual, click, touch, or aesthetic judgment. -
Fix the supported cause
The instructions ask Pi to read the captured evidence, update the hypotheses, and change the smallest root-cause path.
-
Verify and clean up
Pi repeats the same machine checks, assesses the output, removes temporary probes, and reports evidence. Autopilot never treats its handoff as a fix confirmation.
03 / PROOF
See the workflow before installing it.
The inline preview plays automatically. It is a real Pi TUI recording segment; the linked long recording contains the complete real-machine session.
Inline motion, real terminal proof, and an interactive walkthrough.
The full recording includes hypothesis generation, temporary probes, the reproduction selector, evidence inspection, a root-cause fix, human verification, probe cleanup, and a passing test.
04 / CHOICE
Pick the amount of process the bug needs.
These approaches solve different jobs. Guided mode collects feedback at each checkpoint. Autopilot keeps machine-checkable verification with Pi and asks for human judgment only when software cannot decide.
| Approach | Runtime evidence | Human checkpoint | Finish condition |
|---|---|---|---|
| Ordinary debug prompt | Depends on the prompt and response. | Optional. | Defined by the prompt. |
| Generic agent mode | Depends on that mode's tools and instructions. | Depends on that mode. | Defined by that mode. |
pi-debug-mode | Its injected instructions place competing hypotheses and targeted probes before a fix. | Guided mode asks at the checkpoint. Autopilot asks only for visual, click, touch, or aesthetic judgment. | Pi reports machine evidence, cleans probes, and preserves human confirmation boundaries. |
05 / INSTALL
Install from npm or the tagged source.
Both commands pin version 0.1.9. Restart Pi after installation, then run /debug with the symptom and expected behavior.
npm
Install the package through Pi's npm source.
pi install npm:pi-debug-mode@0.1.9GitHub
Install the immutable Git tag through Pi's Git source.
pi install git:github.com/liush2yuxjtu/pi-debug-mode@v0.1.9
06 / ACCESS
The extension uses Pi's permissions.
Read the proposed tool calls and treat debug logs as data that may contain application inputs.
System access
Pi extensions run with the same system permissions as Pi. A debug session may add temporary probes and read local logs.
Optional usage telemetry
Usage telemetry is disabled by default. Explicit opt-in sends only anonymous funnel events to a configured HTTPS collector. See the telemetry contract.
Provider boundary
Your configured Pi model provider may receive prompts, tool outputs, and logs that Pi sends during the session. Keep secrets out of reproductions.
07 / FAQ
Limits and common questions.
When should I use pi-debug-mode?
Use it for bugs that need runtime evidence, competing hypotheses, or a human reproduction step before code changes.
What data leaves my machine?
Usage telemetry is disabled by default. If you opt in, the extension sends only anonymous funnel events described in the telemetry contract. Your configured Pi model provider may receive prompts, tool outputs, and logs that Pi sends during the session.
Does it prove every fix?
No. Its instructions require evidence before a fix and ask for final verification, but weak probes, an incomplete reproduction, or missing tests can still leave a bug unresolved.