welcome-workspace docs

FeaturesInstall

What it does

Not a collaboration cloud. A dashboard for your disk — scan, triage, open, scaffold, report.

Dashboard & health

You add roots — directories whose immediate children become projects. The scan fingerprints each one so warm reloads only re-scan what actually moved. On a large workspace that is the difference between usable and coffee-break.

Every project gets dates, stack detection, branch / ahead-behind / dirty / last commit / remote, and health alerts: no remote, diverged, behind, unpushed, dirty, stale WIP (dirty and quiet for 3+ weeks), dormant (90+ days).

  • Needs attention rolls up warn/error and folds away when empty
  • Pinned section, recency heat over about 90 days, Recent vs Older
  • Filter with / across name, path, stack, branch, remote, note

Project workspace

Open a project and you get the day-to-day surface: vitals, a note field for where you left off (the feature I actually use), remote deep links for GitHub / GitLab / Bitbucket / Codeberg / sourcehut, and git actions with a safety probe when switching branches.

  • Fetch all, pull ff-only, push with upstream
  • Branch switcher and read-only commit history
  • Quick-open editor, terminal, or folder — editor is configurable; terminal auto-detects common Linux terminals if you leave it blank

git-snitch reports

The project page can run a per-repo report; Settings can run a comparative scan across a whole root. HTML is cached under XDG and served at /reports/<key>, so it opens in a new tab from whatever machine is hitting the app.

CLI resolution is Settings path, then a local gitsnitch build, then npx as fallback.

Files & browser IDE

A lazy file tree stays confined to the project subtree — the server rejects path escapes. Upload (10 MB a file, overwrite confirm), rename, new folder, download, delete. Trash via gio when available; otherwise permanent delete behind the same confirmation.

Open IDE starts a shared code-server instance deep-linked to that folder. First use installs into XDG data. Stop it from Settings. URLs use the hostname you are already browsing — fine on a trusted LAN, not something to hang on the public internet with --auth none.

Create & clone

Create project scaffolds better-t-stack into a chosen root: stack options with compatibility-aware lists, progress, optional install, and AGENTS.md when the file is not already there.

Clone script builds a portable bash script from selected remotes — force SSH, skip existing dirs, dedupe. Copy or download it; you run it locally. The app does not clone for you.