nietzschian-debugger README

项目的 README,来自 github.com/DilawarShafiq/nietzschian-debugger。合并为一个 markdown 文件:README.md。

Nietzschian Debugger

Nietzschian Debugger: the debugger that hands the question back

PyPI Python License: MIT

"What doesn't kill your code makes it stronger."

It won't fix your bug. It'll fix you. Every other tool hands you the answer; Nietzschian Debugger hands the question back.

You paste your bug. It doesn't fix it. Instead, it:

Why?

AI is making developers weaker. Copy-paste from ChatGPT, ship, repeat. Nobody understands their own code anymore. Nietzschian Debugger forges stronger developers — through struggle, not shortcuts.

This isn't anti-AI — it runs on Claude, on purpose. It's anti-outsourcing-your-thinking. Every other tool uses the model to hand you the answer; this one uses it to hand the question back.

"He who has a why to debug can bear almost any how."

Installation

# Python 3.10+
pip install nietzschian-debugger
nietzschian debug "your bug"

No API key yet? See it in action first — no key, no cost:

nietzschian demo

Note: the current tool is the Python package above. The old npx nietzschian-debugger serves a stale pre-rewrite build — it has been deprecated in favour of the pip install.

Requirements:

Setup

Set your Anthropic API key:

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# Windows (CMD)
set ANTHROPIC_API_KEY=sk-ant-...

Quick Start

# Start a debugging session (adaptive by default — it reads your state and shifts lens)
nietzschian debug "My API returns 500 but only on Tuesdays"

# Force a single lens instead of adapting
nietzschian debug --lens socrates "My login endpoint fails randomly"
nietzschian debug --lens zarathustra "Memory leak in production"

# Point it at specific code
nietzschian debug "Auth fails in ./src/middleware/auth.ts"

# Interrogate your actual uncommitted changes (feeds the git diff as context)
nietzschian debug --diff "tests started failing after my last change"

# Use any model — Claude by default; or OpenAI, Gemini, DeepSeek, local Ollama…
nietzschian debug --model ollama:llama3.1 "my function returns null sometimes"

Models — set one up, switch any time

Claude is the default and the sharpest experience. With ANTHROPIC_API_KEY set, every command just works with no flags. But the tool is model-agnostic — it speaks the OpenAI API, so almost any hosted or local model works too.

Switching models

The model is chosen per command with --model. There's no config to edit and no state to reset — you switch just by changing the flag, or drop it to return to Claude:

nietzschian debug "my bug"                                # Claude (needs ANTHROPIC_API_KEY)
nietzschian debug "my bug" --model openai:gpt-4o-mini     # a hosted model
nietzschian debug "my bug" --model ollama:llama3.1        # a local model, no key

The flag isn't sticky — each run is independent. (There's no mid-session switch yet; to change model, re-run the command with a different --model.)

Hosted models (bring your own key)

Set the matching key, then select the model:

export OPENAI_API_KEY=...     # or GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, …
nietzschian debug --model openai:gpt-4o-mini "..."
nietzschian debug --model deepseek:deepseek-chat "..."
nietzschian debug --model gemini:gemini-1.5-flash "..."

Supported: openai, gemini, deepseek, groq, mistral, together, openrouter, xai — plus custom:<model> with NIETZSCHIAN_BASE_URL for any other OpenAI-compatible endpoint.

Local models with Ollama (no key, no cost, offline)

# 1. Install Ollama (https://ollama.com) and make sure it's running
# 2. Pull a model once:
ollama pull llama3.1
# 3. Add the provider deps once, then point the tool at it:
pip install "nietzschian-debugger[providers]"
nietzschian roast ./messy.py --model ollama:llama3.1

(LM Studio works the same way: --model lmstudio:<model>.)

Which local model should I use?

Different jobs reward different kinds of model — and the twist is that the best model for predict is the worst for roast:

Command Best local model Why
roast, debug a general chat model — llama3.1, qwen3 built for prose and wit
predict a coding model — qwen2.5-coder it wants a precise function call — exactly the dare

A coding model asked to roast reaches for JSON instead of a joke; a chat model asked to predict is vaguer about the exact return value. Match the model to the job.

Honest caveat: the "never give answers" discipline is sharpest on Claude. Smaller local models leak and over-ask more — the built-in validator and the roast/predict guards catch a lot of it, not all.

Share a session

Your sessions are made to be shared. Turn the last one into clean markdown:

nietzschian share            # most recent session, to your terminal
nietzschian share -o run.md  # or save it to a file

Three Lenses — it picks, not you

By default it adapts: each turn it reads where you are and shifts between three methods. You don't choose a difficulty — a confused developer can't diagnose their own state, so the tool reads you instead. Nietzsche is home; it shifts only on sustained signals, not twitchily, and the active lens shows in every turn header ([Turn 3 · socrates]).

When you're… Lens What it does
confused — you don't know what you mean socrates Relentless clarification. Defines your vague terms until a testable claim appears. The stingray, not a gentle mentor.
avoiding — hiding in an assumption nietzsche The tuning fork. Taps the idol you're proudest of and listens for the hollow ring.
defeated — ready to quit zarathustra Affirmation. Reframes the bug as the weight that makes you stronger, and will not let you quit.

None of them is soft — adaptivity changes the angle of the blade, never sheathes it. To pin one lens instead of adapting:

nietzschian debug --lens socrates "my bug"
nietzschian debug --lens zarathustra "my bug"

How a Session Looks

$ nietzschian debug "login endpoint returns 403, but only for users who signed up before last week; new signups work; same code path; Node/Express"

Nietzschian Debugger [Adaptive mode]


[Turn 1 · nietzsche]
You said "same code path" — but the data is screaming that something
changed between last week and today.

What is different about the user record itself between those who signed
up before last week and those who signed up after?

> I assumed the records were identical. Let me actually compare one.

[Turn 2 · nietzsche]
"Assumed." There is the word you built a week of debugging on. Stop
assuming and read two rows side by side.

What field exists on an old account that a new signup was never given?

> ...the old ones carry a legacy role claim the new ones don't, and the
  auth middleware rejects any token without it.

[Turn 3 · nietzsche]
There it is. The bug was never in the code — it was in your certainty
that "same code path" meant "same data." You stopped looking exactly
where the difference lived.

> found it

Session Complete -- 3 questions to root cause (Solved)

Your Debugging Profile:
┣ Assumption-checking    ████████░░  strong
┣ Evidence-gathering     ██████░░░░  moderate
┗ Root cause speed       ████████░░  strong

"Man is something that shall be overcome."
 -- Friedrich Nietzsche

Or when you call a test "flaky":

$ nietzschian debug "integration test passes locally but fails in CI — it's flaky, I just rerun until it's green"

Nietzschian Debugger [Adaptive mode]


[Turn 1 · nietzsche]
"Flaky." The word you reach for when a test has found something true and
you'd rather it hadn't. A test that fails one run in three isn't random —
it's telling you something is ordered that you assumed was not.

What does CI have, or do in a different order, that your machine does not?

> idk, maybe the database isn't ready yet

[Turn 2 · nietzsche]
"Maybe" — you named a suspect and refused to question it in the same
breath. A database that wasn't ready would throw a connection error, not a
wrong answer. Unless your test is reading rows another test wrote.

Do your tests share a database, and are they guaranteed to run in order?

> ...they share one. locally they always run alphabetically

[Turn 3 · nietzsche]
There it is. "Flaky" was the mask on a race you refused to see — two tests
fighting over the same rows, hidden on your machine by an accident of
alphabetical ordering that CI parallelizes away. The test was never flaky.
It was honest, and you were not.

Will you isolate the data, or keep rolling the dice until they fall green?

> oh. found it

Session Complete -- 3 questions to root cause (Solved)

Your Debugging Profile:
┣ Assumption-checking    ███████░░░  strong
┣ Evidence-gathering     █████░░░░░  moderate
┗ Root cause speed       ████████░░  strong

"No victor believes in chance."
 -- Friedrich Nietzsche

Prove You Understand It — predict

debug interrogates a bug. predict interrogates you: it dares you to say what one of your functions returns, then runs the code for the truth — never a model guessing (that can be confidently wrong). At the end it names the pattern in your misses, not a score.

nietzschian predict ./parsers.py          # 3 dares by default
nietzschian predict ./parsers.py -n 5     # go five rounds
$ nietzschian predict ./parsers.py

Nietzschian Debugger [predict mode]

3 rounds — type 'quit' (or press Ctrl+C) to stop early.

── Round 1 of 3 ──

You named it truncate, and now you believe it truncates. Sweet certainty. But
look — you gave length a default of zero, and zero is a falsy little god that
answers "if not length". So tell me, prophet:
what does truncate("hello world") return?

your prophecy > "" — it truncates to zero, so nothing

Wrong, and gloriously so. "if not length" caught your zero and handed back the
text untouched, before a single character was cut. You read the name and never
the first line. The guard fired; your logic never ran.

The truth, once run — it returned 'hello world'.

── Round 2 of 3 ──

You wrote dedupe, and I can smell the doubt — most who write it reach for a set
and let the order rot. Did you keep the order, or did you betray it?
what does dedupe([3, 1, 2, 1, 3]) return?

your prophecy > [3, 1, 2]

Right — and not by luck. You kept the first sighting of each and dropped the
echoes. Clean. There was no trap here; some things you simply know.

The truth, once run — it returned [3, 1, 2].

── Round 3 of 3 ──

A tier function, a border drawn at one hundred. Borders are where confidence
goes to die. Stand on the line itself and tell me which side claims you:
what does shipping_tier(100) return?

your prophecy > "freight" — 100 is the heavy tier

Wrong. "weight > 100", and one hundred is not greater than one hundred. You
stood ON the boundary and assumed it pulled you across; it let you fall back to
'parcel'. The strict > you typed yourself is the thing you forgot.

The truth, once run — it returned 'parcel'.

Proof of Understanding

Two of three — and the two you missed were cut from the same cloth. You read
functions by their name and their happy middle, and walk straight past the lines
that quietly decide everything first: the falsy default that returns early, the
strict > that owns its edge. You trust what the code is *for* over what it
*says*. Read the guards before the gift — the boundary is not an afterthought,
it is the whole argument.

It runs your code in a separate process with a timeout — your own functions, called the way you'd call them. It only picks functions it can invoke with simple literal arguments, and a function that raises is a legitimate answer (predict that too).

Roast Your Code — roast

For when you don't want a question or a fix — you want the truth, fast and funny. Point it at your worst file; it reads the code's cowardice and laughs. Fixes nothing.

nietzschian roast ./legacy/utils.py
$ nietzschian roast ./legacy/utils.py

🔥 Nietzschian Roast

A function named `helper` wrapping a bare `except: pass` — you built a room with
no windows and called it tidy. The bug you're hiding from in there is the only
honest thing you've written all week.

"Not by wrath does one kill, but by laughter." — Thus Spoke Zarathustra

Session Commands

Command Effect
solved or found it End session — you found the root cause
I give up Get one lifeline question, then exit
exit or quit Abandon session immediately
Ctrl+C / Ctrl+D Force quit

Features

Development

# Clone and install
git clone https://github.com/DilawarShafiq/nietzschian-debugger.git
cd nietzschian-debugger
pip install -e ".[dev]"

# Run the test suite
pytest

# Run the CLI locally
nietzschian debug "test problem"

Tech Stack

License

MIT

nietzschian-debugger (DilawarShafiq/nietzschian-debugger)

正在搜索数据库…

这是什么?Nietzschian Debugger 是一个命令行工具,它不直接给出答案,而是通过提问来帮你调试:你粘贴出现的 bug,它会连续抛出步步紧逼的问题,直到你自己找到根本原因。
它是一个解释 bug 的聊天机器人,还是别的什么?它是一个终端命令行会话,会读取你的实际代码并就此向你发问。它从不输出修复方案,只提出让你自己推理 bug 的问题。
怎么把它跑起来?安装 npm 版本(需要 Node.js >=20),或从源码运行(需要 Python >=3.10),然后设置你的 Anthropic API 密钥,并开始一个会话,指向存在 bug 的文件。
我需要 Anthropic API 密钥吗?需要。它采用自带密钥(BYOK)的模式:你需要自己的 Anthropic API 密钥,因为提问功能由 Claude API 驱动。
如果卡住了,我能直接拿到修复方案吗?不能直接拿到。输入 'I give up' 只会再多给你一次求助提问的机会,之后会话就会结束;这个工具的设计目的就是绝不把答案交给你。
这个工具到底适合谁?适合正在学习基础知识的初级开发者、怀念那种艰苦钻研过程的资深开发者、希望团队学会独立思考而不是只会提示词的工程经理,以及正在培养调试直觉的训练营学员。
我的会话数据会去哪里?会话数据保存在你本机上,用于长期跟踪进度;除了 Anthropic API 调用本身,不会发送到任何外部服务器。
三个强度等级是什么?socrates(语气温和,提供脚手架式问题,适合初级开发者)、nietzsche(直接且咄咄逼人,为默认等级)、zarathustra(严厉、对抗性强,适合想承受真正压力的资深开发者)。
找到 bug 后,我该怎么结束调试会话?当你定位到根本原因时,输入 'solved' 或 'found it' 即可结束会话;输入 'exit' 或 'quit' 则会立即放弃会话。
它会跟踪我的能力提升吗?会的,它会保存一个 Growth Score,用可视化的条形图记录你跨会话的调试能力变化。
Growth Score 和 Sliding Context 功能是什么?Growth Score 用图表展示你调试进步的历程;Sliding Context 则会在长会话中总结较早的对话轮次,避免程序崩溃或超出模型的上下文窗口。
大小
1.4 MB
星标
559
时长
8个月
提交 · 90 天