Linux Tech Helper

Tester Build

Linux Tech Helper v0.2.1 is a public-alpha compatibility test. It runs from the extracted folder and does not yet include the planned user-local self-installer.

Testing this build? Fill out the Linux Tech Helper tester questionnaire.

Linux Tech Helper v0.2.1 is a local GTK app that helps a Linux user finish setup, collect basic system context, run guided read-only troubleshooting steps, and review a support bundle before sharing it.

Current Status

Prototype / Safety Policy v0.2. This is not a repair tool.

The app runs locally on the machine. It stores its own app data under ~/.local/share/linux-tech-helper/.

Safety Model

Linux Tech Helper v0.2.1 includes Safety Policy v0.2.

Currently allowed:

• Read-only internal scanner commands from the fixed app scanner list
• User notes and explanations
• Guided diagnostic commands displayed for manual copy-only use
• User-guided caution steps, such as manually launching a trusted app command to capture output

Not allowed:

• No sudo, su, pkexec, or doas
• No automatic repair commands
• No package installation, removal, purge, upgrade, autoremove, or repair operations
• No service start, stop, restart, reload, enable, disable, mask, unmask, or daemon-reload operations
• No drive, mount, partition, filesystem repair, boot repair, or automated driver repair actions
• No file deletion, overwrite, write redirection, or destructive filesystem commands
• No AI runtime or Ollama dependency

Guided diagnostic commands are shown for the user to copy, run manually, and paste back into the app. The app does not run those commands automatically.

Permanent forbidden zones: partition changes, filesystem repair, boot repair, and automated driver repair or driver installation.

Current Features

• First-run wizard
• First-run readiness checklist
• Read-only system scan
• Dashboard
• Project Status
• Dependency preflight checker
• Case File
• Support Bundle review and export
• Linux Knowledge Pack v0.1 with Safety Policy v0.2 metadata
• Guided diagnostics for audio, internet, updates, drives, disk space, services/logs, desktop/session, application launch, and general triage
• Expanded read-only internet diagnostics for NetworkManager, IP address, route, DNS, and ping checks
• Expanded read-only audio diagnostics for PipeWire, PulseAudio compatibility, sinks, sources, cards, user services, and ALSA hardware visibility
• Expanded read-only updates diagnostics for apt package listing, dpkg audit, source policy, disk space, apt background service state, and recent warning-log checks
• Expanded read-only missing-drive diagnostics for block devices, mounts, fstab, common mount directories, kernel storage messages, USB detection, and udisks status
• Expanded read-only disk-space diagnostics for block usage, inode usage, shallow home and /var usage, mount options, and filesystem identifiers
• Expanded read-only services and logs diagnostics for failed system services, failed user services, current-boot warnings/errors, and specific service status checks
• Expanded read-only desktop and session diagnostics for desktop environment variables, session type, login session state, visible sessions, failed user services, and user-session logs
• Expanded application launch diagnostics for command lookup, executable details, desktop launchers, launcher metadata, packaging clues, and copy-only user-guided terminal launch-error capture
• Rule-based interpretation for pasted diagnostic output, including common network, audio, failed-updates, missing-drive, disk-space, services/logs, desktop/session, and application-launch patterns

Run From Folder

If you have the source tarball, extract it first:

tar -xzf linux-tech-helper-v0.2.1.tar.gz
cd linux-tech-helper-v0.2.1
./run.sh

From the development checkout:

cd ~/Projects/linux-tech-helper
./run.sh

You can also run the Python entry point directly:

cd ~/Projects/linux-tech-helper
python3 app.py

Local Desktop Launcher

Install a user-local KDE/Linux launcher so Linux Tech Helper appears in the app menu. This is the canonical desktop launcher method for the source tarball release:

cd ~/Projects/linux-tech-helper
./install-local-launcher.sh

This creates:

~/.local/share/applications/linux-tech-helper.desktop

It does not use sudo, install packages, move the project, or write to system-wide application folders. The source or extracted folder remains the application folder. The launcher points to the exact folder where you run install-local-launcher.sh.

Upgrade And Uninstall

Linux Tech Helper app-owned user data remains under ~/.local/share/linux-tech-helper/. Extracting a newer release does not delete that data.

If you use the local launcher, reinstall it from the newer extracted folder after upgrading. Otherwise the existing launcher may continue pointing to the old extracted folder.

Remove only the user-local launcher:

cd ~/Projects/linux-tech-helper
./uninstall-local-launcher.sh

Removing the launcher does not remove Linux Tech Helper app data, reports, or support bundles. The uninstaller may refresh the desktop database, which can update mimeinfo.cache in the user-local applications folder.

Dependencies

• Python 3.10 or newer
• GTK 3
• PyGObject
• A Linux desktop session

Linux Tech Helper is primarily tested on KDE. X11 has been tested. Wayland is expected to work, but it has not yet been deeply validated.

This project does not install system packages or dependencies automatically. Install Python, GTK 3, and PyGObject through your Linux distribution if they are missing.

Important Paths

• App data: ~/.local/share/linux-tech-helper/
• Reports: ~/.local/share/linux-tech-helper/reports/
• Exports: ~/.local/share/linux-tech-helper/exports/
• Knowledge pack: lth/knowledge/packs/core_v0_1/

Support Bundle

Support bundles are exported from the Case File window.

Bundles are saved under:

~/.local/share/linux-tech-helper/exports/

Before export, the Case File shows what the bundle includes and asks for confirmation.

The bundle contains:

• Linux Tech Helper reports
• Linux Tech Helper SQLite database copy
• Saved diagnostic output and notes
• Machine profile details saved by Linux Tech Helper
• DPD tag metadata
• Knowledge pack JSON
• Support bundle manifest

Saved diagnostic output may include usernames, hostnames, file paths, device names, network details, application names, or other local machine details that appeared in pasted terminal output. Review the Case File and inspect the bundle contents before sharing.

It does not intentionally collect arbitrary home files, browser history, passwords, documents, or system-wide private data. Nothing is uploaded or sent automatically.

Development Notes

• DPD tag: .dpd-tag.json
• DPD tag reader: tools/read_dpd_tag.py
• Knowledge validator: tools/validate_knowledge_pack.py
• Release checklist: RELEASE-CHECKLIST.md

Useful checks:

python3 tools/read_dpd_tag.py
python3 tools/validate_knowledge_pack.py
python3 tools/test_safety_policy.py
python3 tools/test_output_interpreter.py
python3 tools/test_preflight.py
python3 tools/test_release_package.py

Preflight Check

From the Maintenance card, choose Run Preflight Check to see whether the basic runtime pieces are available. It checks Python, PyGObject/GTK, bundled app imports, desktop/session context, launcher helper files, optional desktop utilities, and app-owned data folder writability.

The preflight check does not use sudo, install packages, repair anything, change services, change drives, or add an AI runtime.

Build Source Package

Build the v0.2.1 source tarball:

python3 tools/build_release_package.py

The package is created under dist/ as:

dist/linux-tech-helper-v0.2.1.tar.gz

The source tarball excludes .git, Python caches, runtime app data, support bundle zips, and prior build output.

Release Materials

• Release notes: RELEASE-NOTES-v0.2.1.md
• GitHub release draft: GITHUB-RELEASE-v0.2.1.md
• Website/download copy: WEBSITE-DOWNLOAD-COPY.md