stepfix: tech support that never writes the command for you

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

Most of us have a friend or a parent who calls when the Wi-Fi breaks. Helping over the phone means reading commands out letter by letter, or telling them to paste something they can't read. I wanted something I could send them instead, that is careful in the same way I'd be.

stepfix is a support chat for people who aren't technical. You describe the problem in plain words, like "my Wi-Fi shows no networks". It asks a couple of questions, then walks you through the fix one step at a time.

Each step is a card with:

• the exact command to copy
• why we're running it
• what you should see if it worked
• "it worked" and "it didn't" buttons, so the next step depends on what actually happened

You run every command yourself. stepfix never touches your machine.

The one rule I didn't want to bend: the AI never writes a command. Every command comes from a public, reviewed library of 63 scripts covering Wi-Fi and Bluetooth on Ubuntu and Windows 11, plus a few developer-tool fixes. Each one has a risk level, and 39 of them only read information without changing anything. The model picks which step comes next. The app fills in the exact text. If the model tries to slip a command into its reply anyway, a scanner strips it out.

Why so strict? "Open your terminal and paste this" is exactly how a lot of scams work now. Someone who doesn't know what a command does can't tell a fix from an attack. So stepfix only hands out commands that anyone can read on GitHub first.

Demo

The demo is a live run on Ubuntu, unedited:

1. "My laptop says it's connected to Wi-Fi but nothing loads"
2. It asks one question at a time (which OS, when it started) and fills in the case panel as I answer
3. It switches to step-by-step fixing and shows the first card: a read-only check, with "why" and "what you should see"
4. I click "I ran it" without pasting anything. It won't move on: a check with no output proves nothing, so it asks for the output
5. I type "it got fixed". It still doesn't mark the case resolved, because nothing was verified
6. I stop, and get a report I can copy or download. It says plainly that nobody has been contacted

That last part is the point. It would rather stop and hand you an honest report than guess at a fix.

Code

trakshan-mishra / stepfix

AI tech support that never writes the command for you. Open-weight models, a reviewed public script library, you run every step.

stepfix

stepfix is an AI tech-support helper for people who are not technical. It explains each diagnostic or repair step, and the person runs every command themselves.

Safety model

The AI is never allowed to write commands. Every command comes from the reviewed, public script library in library/*.yaml, which is linted for dangerous patterns. This is the opposite of “paste this into your terminal” scams: the model selects a bounded step, while the application supplies the exact command and explains what it does.

Models

Open-weight models only: gpt-oss-20b and gpt-oss-120b on Groq, with GLM-4.7-flash on Cloudflare Workers AI as the fallback, and a scripted playbook if every model is down. No closed models are used.

Run locally

You need Node.js, npm, a Cloudflare account with Workers AI access, and a Groq API key.

npm install
cp .dev.vars.example .dev.vars
npx wrangler login
npm run dev

Fill in the required values…

View on GitHub

How I Built It

stepfix runs on Cloudflare Workers with Durable Objects, using the open-source Cloudflare Agents SDK and the AI SDK. Every support session is its own Durable Object. A separate Coordinator object handles admission and keeps a quota ledger, so a free-tier app doesn't fall over the moment a few people show up.

There are two roles:

• Support asks questions and fills in a case file: OS, problem area, symptom, when it started, what changed. It can't hand off until the case file is complete.
• Technician only sees the scripts for that OS and problem area, and recommends one at a time based on what the previous step showed.

Models: gpt-oss-20b for support and gpt-oss-120b for the technician, both on Groq. GLM-4.7-flash on Cloudflare Workers AI is the fallback. Before every model call, the router reserves quota. If every model is down, a scripted playbook continues the case instead of leaving the person stuck.

The script library is YAML. A linter rejects dangerous patterns, like piping a download straight into a shell or recursive deletes. It's then compiled and hashed, so the app only serves what's in the reviewed file. There are 462 unit tests, two browser tests that click through a full repair and a stop-and-report, and 13 simulated support conversations.

The best part of this weekend was a bug. When I first switched from mock mode to real models, stepfix answered nothing. No error, no message, just silence.

It turned out the quota ledger used JavaScript Maps, and the Durable Object saves its state as JSON. JSON.stringify(new Map()) is {}. After a restart, the ledger came back as empty plain objects, the first .get() threw, and the error was swallowed before it reached the user.

The fix had three parts:

• maps that serialize properly
• loading old broken state without crashing
• falling back to the playbook instead of going silent

While testing that, I found the technician had never actually seen the script catalog. It was loaded with require(), which doesn't exist in a Worker, and the catch hid that too. Two silent failures in one path. Now there's a test for each.

Then I recorded myself using it and watched it back. In one reply, the model wrote "run: ip -brief address" right in the chat. My scanner missed it for two reasons:

• its list of command names didn't include a single command from my own library
• it ignored anything near the word "Wi-Fi", which is every Wi-Fi conversation

Now the scanner learns every command from the library itself, and the exact text from that recording is a test case.

I used AI coding tools along the way, mostly Claude for debugging: going through logs with me and watching my screen recordings back to find where the flow broke. The Map bug and the scanner gaps both came out of those sessions.

Why Does Open Innovation Matter?

Trust. The thing that decides what runs on someone's computer should be inspectable. The script library is public. The models are open-weight, so you know exactly what's behind the chat, and so does anyone auditing it.

The fallback only works because the weights are open. stepfix's main and backup providers are different companies serving open-weight models. When Groq rate-limits, the same kind of model takes over on Cloudflare. With a single closed model, "fallback" means "nothing".

It can go local. Because the models are open-weight, the next step is running the whole thing on the person's own machine, for anyone who doesn't want their system output leaving it. That isn't built yet, but nothing in the design blocks it.

Prize Categories

Overall. I didn't use the partner technologies for this one.