Skip to content

About

Your PC. Uncomplicated. An offline-first Windows desktop assistant for settings, troubleshooting, shortcuts, and approved repairs.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

3 Commits

Folders and files

Repository files navigation

Unstuck OS

Your PC. Uncomplicated.

Find Windows settings, understand everyday problems, discover shortcuts,
and run supported repairsβ€”with you in control.

Version Platform Status Free
Electron React TypeScript Offline first

Explore the app Β· Screenshots Β· Get started Β· Documentation Β· Report an issue

Less searching. More doing.


Note

Current release status: Unstuck OS is a functional development candidate. You can build and run it from source today. A signed public installer and Microsoft Store publication are still pending; this repository currently has no published release download.

What is Unstuck OS?

Windows can make simple tasks surprisingly hard to find. Unstuck OS brings practical computer assistance into one desktop workspace: describe a problem, find the right setting, inspect diagnostic evidence, or follow a clear tutorial.

You do not need an account, a subscription, or a paid AI service. Supported help and local tools work offline. Network tests and optional online guidance use the internet where needed.

If you want to… Start here
Find a hidden Windows setting Search for a task such as β€œChange date and time”
Work through a computer problem Describe it in Issue assistant
Check internet, microphone or camera behavior Open Troubleshooting
Understand memory, storage and uptime Open Performance
Find a useful key combination Search Keyboard shortcuts
Learn at your own pace Read Help & Support, FAQs and tutorials

Screenshots

One place to describe the problem

Unstuck OS Issue assistant in dark mode with a problem description field, analysis controls and example requests
Describe an issue, start supported checks, and review the next step.

See the softer light theme

Unstuck OS Issue assistant using muted blue-gray light-theme surfaces

Explore the offline Help Center

Unstuck OS Help Center with local search, tutorials, FAQs and help articles

A welcoming first launch

The first-launch welcome screen with the Unstuck OS logo and introduction controls

These are captures of the running application in an isolated profile, not mockups. No diagnostic results were fabricated or personal machine details included.

Features

Feature What you can do
Universal search Find supported tasks and guides through local keyword and typo-tolerant search.
Windows Settings Explorer Review a task, then approve opening the relevant Windows settings page.
Issue assistant Describe a problem, gather supported evidence, and review available repairs or guidance.
Storage cleanup Preview eligible older temporary files, select exact candidates, approve deletion, and check free space again.
DNS repair and verification Approve a fixed DNS-cache repair, then let the app run before-and-after connectivity checks.
Media checks Test camera and microphone access locally, with a preview or live level meter.
Performance snapshot Inspect local CPU model, available memory, storage, uptime and available Windows information.
Activation assistance Read local Windows licensing status and follow legitimate Windows or Office activation guidance.
Shortcut library Search, copy and favorite useful Windows keyboard shortcuts.
Quick Access Open a compact floating search window using a configurable global shortcut.
Help and onboarding Use a five-screen introduction, a ten-step live tour, 35 help articles, FAQs and 19 practical tutorials.
Private problem reports Preview a report, optionally include diagnostic findings, then copy it or save a local text file.
Personal workspace Keep favorites and recent tasks, manage optional history, and choose dark or soft light mode.

Try it yourself

Find a Windows setting

  1. Press Ctrl + K and search for β€œDate and time”.
  2. Open the matching task and read the instructions.
  3. Choose Approve opening settings.
  4. Make the change in Windows and verify the result yourself.

Work through a full-storage request

  1. Open Issue assistant and type β€œMy storage is full”.
  2. Select Analyze issue. The scan itself does not delete anything.
  3. Review eligible older temporary files and select only files you no longer need.
  4. Review the native confirmation before approving permanent deletion.
  5. Read the actual deleted/skipped counts and the new free-space measurement.

The scan covers only top-level .tmp and .temp files at least seven days old in your user Temp folder. Personal folders and subfolders are excluded. A file's age does not prove that it is unnecessary; Windows Storage settings is available for a broader manual review.

Learn a feature without running a repair

Open Help & Support, search for β€œmicrophone”, and read an article or tutorial. Choose Start guided tour to explore real controls. The tour does not run repairs or destructive actions.

How assistance works

flowchart LR
    A[Describe a problem] --> B[Match supported assistance]
    B --> C[Run supported read-only checks]
    C --> D[Review evidence and proposed action]
    D --> E[Approve a supported repair]
    E --> F[Run and verify]
    B --> G[Manual or online guidance]
Loading

Unstuck OS distinguishes a successful check, an accepted Windows navigation request, and a completed repair. None of those alone proves that every part of a computer problem has been solved.

Quick start

Requirements

  • A Windows development machine. The app targets Windows 10 build 19041 or later and Windows 11, x64; feature availability varies by Windows version, hardware and policy.
  • A supported Node.js LTS installation with npm.
  • Git to clone the repository.

Run from source

git clone https://github.com/brainiacweb-tech/Unstuck-OS.git
cd Unstuck-OS
npm ci
npm run dev

npm run dev compiles the app and launches Electron. There is no hot-reload development server; stop and rerun it after edits. Dependency installation requires internet access. End users of a packaged build do not need Node.js installed separately.

Electron runs but no window appears?

If your terminal sets ELECTRON_RUN_AS_NODE, Electron runs as a command-line process. Clear that variable in the current PowerShell session and try again:

Remove-Item Env:ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue
npm run dev

Build a Windows package

Run packaging commands sequentially:

npm run package      # Portable Windows executable
npm run installer    # Per-user NSIS installer

Generated files are written to release/ and are not committed to Git. Current test binaries are unsigned. MSIX packaging additionally requires real Partner Center identity values and Windows SDK tools; see the build guide and Store publishing guide.

Development and testing

Command Purpose
npm run lint ESLint and TypeScript checks
npm test Unit tests, including isolated cleanup safety fixtures
npm run build Type-check and compile renderer, main process and preload
npm run test:e2e Existing Electron diagnostics/settings regression
npm run test:help Onboarding, tour, offline help, About and report workflows
npm run test:repairs Issue matching, cleanup scan, online consent and DNS workflow checks
node scripts/layout-smoke.cjs Layout checks across desktop sizes and both themes
node scripts/brand-smoke.cjs Fonts, colors, logos and theme persistence

Latest verified checks: 77 unit tests passed, along with lint, TypeScript, production compilation and the Electron assistance/repair regressions. The responsive layout audit passed 66 page/content checks across 1280Γ—850, 1024Γ—768 and 800Γ—600, in dark and light mode. These are recorded local checks, not a hosted CI status or a claim of complete hardware coverage.

Electron tests use isolated profiles. Cleanup deletion is tested on generated fixtures; the repair smoke test intercepts the DNS command so it does not alter the computer's DNS cache. Camera/microphone hardware, Windows edition differences and assistive technologies still need manual acceptance testing.

See Testing, repair verification and layout verification. Generated QA reports and local diagnostic screenshots are excluded from Git.

Architecture

Layer Responsibility
React renderer Pages, accessible controls, local search, onboarding, tour and previews
Sandboxed preload A narrow, frozen API between the UI and native functionality
Electron main process Trusted-frame validation, Windows navigation, permissions, diagnostics, report export and approved repairs
Shared data and policy Task catalogue, help content, bounded input validation and report formatting

Windows commands are fixed and allowlisted. Issue text and online content never become executable commands. Cleanup plans are owned by the native process; the renderer selects opaque IDs rather than sending arbitrary file paths.

Unstuck-OS/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ data/           # Tasks, shortcuts, help and support configuration
β”‚   β”œβ”€β”€ main/           # Electron, diagnostics, Windows queries and repairs
β”‚   β”œβ”€β”€ preload/        # Narrow IPC bridge
β”‚   β”œβ”€β”€ renderer/       # React pages, components, themes and brand assets
β”‚   └── shared/         # Contracts, search, policy and validation
β”œβ”€β”€ tests/              # Unit tests and isolated filesystem fixtures
β”œβ”€β”€ scripts/            # Build helpers, screenshots and Electron checks
β”œβ”€β”€ docs/               # User, architecture, security and release guides
└── store-assets/       # Branding, icons, licence notices and Store templates

Built with: Electron, React, TypeScript, Node.js, Vite, Tailwind CSS, Fuse.js and Lucide. Raleway, Inter and JetBrains Mono are bundled locally for branding, UI and technical information.

Privacy and safety

  • Local by default. No account, analytics or cloud AI service is required. Preferences and optional diagnostic history stay in your Windows user profile.
  • Explicit file deletion. Temporary-file cleanup starts with a preview, leaves everything unselected, and requires native approval. Deletion is permanent; changed, locked or inaccessible files are skipped.
  • Permission-aware media. Camera and microphone tests use Windows and app permissions. Media is processed locally, never recorded or uploaded, and stops when you leave the test.
  • Clear network boundaries. Internet checks contact Microsoft endpoints. Online guidance asks before sending your reviewed issue text to Microsoft Support in your browser; no files or diagnostic findings are attached.
  • Deliberate reporting. Reports require a preview before copying or saving. Nothing is sent automatically.
  • Legitimate licensing only. Activation assistance does not bypass Windows or Office licensing and never asks you to enter a product key into Unstuck OS.

Read the privacy documentation and supported repair boundaries.

Documentation

Guide What it covers
User guide Finding tasks, using help and working through issues
Onboarding and Help Center Introduction, tour, tutorials, About and local reports
Issue assistant Cleanup, DNS repair, online consent and actual limits
Architecture Renderer/main boundaries and local state
Security Permissions, IPC and Windows integration
Brand identity Logo, colors, type and the softer light theme
Build and packaging Local compilation and Windows executables
Microsoft Store publishing Identity, SDK and submission requirements
Known limitations Outstanding compatibility and release checks

Release priorities

  • Search, settings discovery, shortcuts and local system information
  • Onboarding, guided tour, Help Center, tutorials and About
  • Approved temporary-file cleanup and DNS repair with verification
  • Dark and soft light themes with responsive desktop layouts
  • Complete real-device Windows 10/11, media and accessibility acceptance
  • Produce and verify current signed distribution packages
  • Configure a verified developer support destination
  • Complete Microsoft Store identity, packaging and certification

There is no automatic updater in this build, and Unstuck OS does not claim to fix every computer issue. Unsupported, privileged or hardware-related problems may require manual help. See Known limitations.

Contributing and feedback

Have a reproducible bug, a clearer explanation, or a supported task to suggest? Open an issue.

Include the Windows version, what you expected, what happened and steps to reproduce. Remove personal details, passwords and product keys. If you use Report a Problem in the app, review its preview before choosing what to share.

For code changes, run the relevant unit and Electron checks. Keep native actions allowlisted, preserve explicit approval for destructive operations, and update the local help when behavior changes. Do not commit dependency folders, installers, credentials or machine-specific diagnostic output.

Creator and acknowledgements

Developed by Francis Kusi.

Unstuck OS was created to make everyday computer tasks easier for everyone. From finding hidden Windows settings and discovering shortcuts to troubleshooting common problems, Unstuck OS brings practical computer assistance into one simple application.

Third-party software and fonts retain their respective licences; bundled notices are available in store-assets/licenses. This repository does not assign an MIT or other project-wide open-source licence.

Less searching. More doing.
Β© 2026 Francis Kusi. All rights reserved.
Unstuck OS is an independent desktop application and is not affiliated with or endorsed by Microsoft.

About

Your PC. Uncomplicated. An offline-first Windows desktop assistant for settings, troubleshooting, shortcuts, and approved repairs.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages