fix

I got sick of copying stack traces into ChatGPT, so I made a CLI that does it for me.

You run a command, it fails, and fix figures out why and fixes it:

1. re-runs the command and grabs the error
2. sends it to an LLM
3. shows you what it thinks went wrong
4. applies the fix — either a corrected command or a small code patch — after you say yes
5. re-runs the command to confirm it's green

Pure stdlib Python, no dependencies. Works with any OpenAI-compatible API, including the free ones.

$ npm run build
✗ Error: Cannot find module 'chalk'

$ fix
💡 You're missing the `chalk` dependency. Running `npm install chalk` fixes it.
Proposed fix: npm install chalk
Run it? [y/N] y
✓ fixed — exited 0

Install

Python 3.9+. Nothing else.

pip install fix-cli          # once it's on PyPI
# or from source:
git clone https://github.com/harmless-beep/fixer && cd fixer && pip install -e .

Try it without an API key

fix fixes common mistakes with plain offline rules — no key, no model, no network:

fix --no-llm git puhs        # "git puhs" -> "git push"
fix --no-llm python app.py   # ModuleNotFoundError -> "pip install <module>"

What the offline rules cover today: git command typos (git statsu), missing sudo, missing Python modules, and obvious command-not-found typos (npmm → npm). If none match, fix says so and points you at the options below.

There's also a mock server if you want to see the full model pipeline without paying for anything:

python scripts/mock_llm_server.py          # terminal 1
FIX_BASE_URL=http://127.0.0.1:8457/v1 FIX_API_KEY=mock FIX_MODEL=mock \
    python -m fix --yes python examples/broken.py   # terminal 2

Local model — free, private, no account (Ollama)

Run a real LLM on your own machine. Nothing leaves your computer, no key, no cost. Install Ollama, then:

ollama pull llama3.3          # or any model, e.g. qwen2.5-coder

export FIX_API_KEY=ollama     # value doesn't matter, just needs to be set
unset ZENMUX_API_KEY OPENAI_API_KEY   # or they'd take priority

export FIX_BASE_URL=http://localhost:11434/v1
export FIX_MODEL=llama3.3

fix npm run build

Slower than hosted models and needs a reasonably capable machine, but it's $0 forever and private by design.

Usage

fix npm run build                  # fix a specific command
fix                                # fix whatever failed last (needs the hook)
fix --dry-run python test.py       # show the fix, don't apply anything
fix --no-llm git puhs              # offline rules only — no API key needed

Bare fix reads your shell history for the last command. The hook makes it reliable — it also remembers the exit code:

fix --install-hook

Config

Environment variables, all optional:

Variable	What it does	Default
FIX_API_KEY	API key	auto-detected
FIX_BASE_URL	API base URL	auto-detected
FIX_MODEL	model name	auto-detected
FIX_TIMEOUT	LLM timeout (s)	90
FIX_RERUN_TIMEOUT	command re-run timeout (s)	60

If ZENMUX_API_KEY is set it uses ZenMux's free tier (deepseek/deepseek-v4-flash-free), otherwise it falls back to OPENAI_API_KEY (gpt-4o-mini). You can always override with the FIX_* vars.

Free providers

Provider	FIX_BASE_URL	FIX_MODEL	Key
ZenMux	https://zenmux.ai/api/v1	deepseek/deepseek-v4-flash-free	ZENMUX_API_KEY
OpenRouter	https://openrouter.ai/api/v1	meta-llama/llama-3.3-70b-instruct:free	OPENROUTER_API_KEY
Groq	https://api.groq.com/openai/v1	llama-3.3-70b-versatile	GROQ_API_KEY
Gemini	https://generativelanguage.googleapis.com/v1beta/openai	gemini-2.5-flash	GEMINI_API_KEY
Ollama (local)	http://localhost:11434/v1	llama3.3	FIX_API_KEY=ollama

Heads up: a few providers (ZenMux included) want a balance above $0 even for "free" models — it's an anti-abuse thing, not a charge. If you get a 402, switch to one that works at $0 or run Ollama.

How it works

Two stages. First the offline rules try to fix common mistakes instantly (no network, no key). If none match — or the rule's fix still fails — it asks the model.

The model gets the command, the exit code, and the tail of its output, and returns strict JSON:

{ "explanation": "...", "action": "command|patch|info", "command": "...", "patch": [...], "message": "..." }

• action: command — run this instead.
• action: patch — edit these files. Each hunk is an exact string match, and the whole patch applies all-or-nothing. If any hunk doesn't match, nothing gets written.
• action: info — it can't safely fix it and tells you what to do manually.

Safety

It re-runs your command, so it can have side effects. Destructive commands (rm -rf /, dd, git push --force, ...) trigger an extra confirmation. --yes skips all prompts — use it only with a model you trust.

The command, the last chunk of its output, and your working directory go to whatever LLM you configured. Don't run it on things that print secrets; use Ollama if that's a concern.

What's next

• more offline rules (npm/yarn typos, docker, cd-into-missing-dir)
• auto-retry loop (keep fixing until green)
• colored diffs / streaming output
• fix blame — explain someone else's log

License

MIT