A troubleshooting assistant should do more than suggest a command. It should explain what it observed, tell you what an action will change, and check whether the result actually helped.
That is the idea behind TroubleShoot, a Windows troubleshooting prototype we built as Team DROS at Hacktoberfest Hack Day Coimbatore with INIT Club and IDEA Club.
Explore the website and sample walkthrough · View the source on GitHub
The problem we wanted to solve
Windows already has automatic troubleshooters. But many support workflows still leave users moving between settings, interpreting commands, and guessing whether a fix worked.
We wanted a clearer interaction: describe the problem, inspect relevant facts, review a specific proposal, approve or reject it, and see fresh evidence afterward.
We deliberately kept the scope small. TroubleShoot is not a tool that can repair every Windows problem.
How TroubleShoot works
The working interface is a PWA connected to an authenticated local Windows helper. The public website is a product introduction and sample walkthrough, not a remote-control endpoint.
The flow is:
- Gather fresh Windows diagnostic facts.
- Ask hosted Gemma 4 to explain the facts and propose a bounded next step.
- Validate the proposal against registered operations and deterministic policy.
- Request action-specific human approval before a mutation.
- Run the permitted operation and collect fresh checks.
- Report the outcome, remaining uncertainty, and available recovery.
The current production provider uses gemma-4-26b-a4b-it through the Gemini API. A local Ollama adapter and recorded Gemma evaluations remain in the repository, but the enabled production flow is hosted-only.
The important boundary: proposals are not permissions
Gemma handles reasoning. It does not receive unrestricted authority to execute shell commands. The backend constrains proposals to registered tools, while approval and policy checks determine whether an operation can run.
Cloud text sharing requires explicit consent for each run. API keys stay on the server side and are encrypted using Windows DPAPI outside the repository. The helper uses loopback authentication, and cancellation remains part of the workflow.
These boundaries matter because a plausible explanation is not enough to justify changing a computer.
What we validated, and what we have not
The repository includes real hosted read-only Windows diagnosis evidence, alongside unit tests, API/runtime checks, and clearly labelled synthetic UI tests.
One example is the Print Spooler. Checking that it is running establishes a service fact. It does not prove that a printer produced a page. Our result needs to preserve that distinction instead of reporting an unqualified printing fix.
Full hosted guest repair and live browser installation remain pending in the current documentation. Production desktop mutation and hosted vision are disabled. The website walkthrough uses sample data and performs no AI inference or changes to your device.
That is the most useful lesson from this build: an action completing successfully and a user problem being resolved are different claims.
Stack
- Python, FastAPI, Uvicorn and HTTPX for the helper, API and inference transport.
- PowerShell for bounded Windows operations.
- Browser JavaScript, a manifest and a service worker for the PWA console.
- React, TypeScript and Vite for the product website, deployed on Vercel.
- Gemma 4 for diagnostic reasoning, with an experimental local Ollama path.
The application is MIT-licensed. Model weights, dependencies and Windows installation media retain their own applicable terms.
Building as a team
Our four-member split covered Windows tools and VM validation, local inference and reasoning, backend and hosted integration, and documentation. Shared contracts helped connect those components without treating model output as executable instructions.
We had worked on a separate prototype before this event. This repository was independently implemented from documented requirements following user-reported organizer guidance; earlier application code and history were not imported. The repository preserves that provenance and distinguishes new implementation from third-party tools.
Watch the demo
Watch the TroubleShoot demo on YouTube
Try it and inspect the evidence
The website is the easiest place to explore the interaction. For real Windows diagnosis, follow the helper setup instructions and keep the local helper running. Hosted inference requires internet access and a configured API key.
- Website and interactive sample
- Source repository
- Project presentation on Canva
- Windows setup and validation
- Recorded hosted diagnosis
Our next priority is validating the full approved repair path in a disposable Windows guest, including rejection, cancellation and recovery.
What evidence would you want an AI troubleshooting assistant to show before you trusted its proposed repair?
Disclosure: AI coding assistance was used during development, and this article was drafted with AI assistance for author review. The project documentation records implementation and validation limitations.
Top comments (0)