💥 WhyBroke

Stop copy-pasting stack traces. Fix Python bugs in 8 seconds.

WhyBroke is a terminal-native CLI that reads your broken output, finds the exact failing function on your disk via Python's ast module, and prints a copy-pasteable fix. No dashboards. No SaaS. Just a Unix pipe that actually understands your code.

🚀 Quickstart

uv pip install whybroke    # or: pip install whybroke
whybroke auth              # stored locally at ~/.whybroke/credentials.json
python my_buggy_script.py 2>&1 | whybroke

That's it. Pipe anything. Want it free? Pick zai at the auth prompt — glm-4.7-flash is fully free, no card required.

🧠 Why not just paste into ChatGPT?

When you paste an error into ChatGPT, the conversation goes:

"Can you share the contents of api.py?"

WhyBroke automates that away:

1. AST context extraction — parses the traceback, finds the local file, walks the AST, and pulls the exact failing function. Not a ±10 line guess.
2. Noise reduction — strips the 500 lines of framework boilerplate before the trace.
3. Structured output — the LLM returns a confidence score, evidence lines, and a unified diff. No conversational fluff.
4. Time travel — every debug session is saved locally. Run whybroke view 12 to re-read yesterday's fix for free.

⚙️ Commands

🤖 Providers

BYOK (bring your own key). Supported at V1:

🗣️ Language Support

Pipe any trace — languages without deep support fall back to LLM-only analysis so the pipe always works. V2's scope is determined by the leaderboard above.

🔒 Privacy

V1 sends the stack trace and extracted source to whichever provider you configured. Nothing is logged anywhere else. If you don't want your code leaving your machine, use the litellm provider with an Ollama model:

whybroke auth  # choose "litellm"
python my_script.py 2>&1 | whybroke --model ollama/llama3

🛠️ Contributing

V1's codebase is deliberately boring. The seams for language expansion live in three places:

• whybroke/detect.py — add a regex signature to _SIGNATURES
• whybroke/parsers/ — add {language}.py returning list[Frame]
• whybroke/extractors/ — V2+ uses a shared tree-sitter extractor
• whybroke/prompts/ — add {language}.txt

See docs/ROADMAP.md for what's next.

🧩 Install as an Agent Skill

WhyBroke is available as an Agent Skill — drop it into any skills-aware AI assistant (Claude Code, Cursor, and others) and it'll trigger automatically when you hit a traceback.

npx skills add FireBolt922/whybroke

The skill works in two modes:

• With the CLI installed and authenticated — invokes whybroke --file <trace> and returns a unified diff.
• Without it — falls back to in-skill root-cause analysis (walks the traceback, reads the failing file, explains the root cause, proposes a fix). You'll see a one-time nudge to pip install whybroke && whybroke auth for the richer experience.

Skill source: skills/whybroke/.

💻 Platform support

Tested on macOS and Linux. Windows is untested in V1 and may need adjustments to credential-file permissions or path handling — PRs welcome.

📄 License

MIT — see LICENSE.