nddipiazza/robos / .agents/skills/install-source-shortcuts
install-source-shortcuts
VerifiedRun RobOS apps from a git clone, and install "RobOS <App> (From Source)" Start menu / GNOME app grid / macOS Applications entries and desktop icons for them on Windows, Linux (GNOME) and macOS. Shortcuts take seconds to create; each app installs its own dependencies the first time it is opened, and shows its own icon on the menu entry, desktop icon, taskbar/dock button and window.
Run RobOS Apps From Source & Install "(From Source)" Shortcuts
Every RobOS app is an Electron app in packages/<app-id>/ of the clone. This skill covers
running them straight from source and installing per-OS launcher shortcuts that do the same.
Each shortcut is named RobOS <App> (From Source), so typing "RobOS" in Start menu,
GNOME or Spotlight search finds them, and they never collide with apps installed by
App Manager (robos-managed-*) or the release builds.
Input
$ARGUMENTS: a subcommand and options passed straight to the script:
install [app-id ...]: create or refresh shortcuts (every app when no IDs are given)--desktop: also put an icon on the desktop (kept on later refreshes)--dry-run: print what would be createdremove [app-id ...]: delete what the script created (everything when no IDs are given)list: show every app,readyorsetup(installs on first launch), and which shortcuts exist
If the user gives no arguments, run list first, then ask which apps they want and whether
they want desktop icons too. All ~100 apps on the desktop is rarely what they want.
Running an app from source (no shortcut)
Prerequisites: Node.js 20+, npm, Git, a desktop session.
# Any OS: install the package's dependencies once, then start it
cd packages/<app-id>
npm install
npm start # or: npx electron .
# Linux/macOS helper: npm installs on first run, starts with --no-sandbox etc.
scripts/dev-launch.sh <app-id>
scripts/dev-launch.sh # lists the app IDs
The shortcuts run the same code through scripts/source-shortcuts/source-host.cjs on one
shared Electron (33.4.11, the version App Manager runs every installed app on). The host
gives the window its icon and identity (see below) and does the lazy setup. To launch an app
by hand exactly as its shortcut does:
# Windows: scripts/source-shortcuts/node_modules/electron/dist/electron.exe …
scripts/source-shortcuts/node_modules/.bin/electron scripts/source-shortcuts/source-host.cjs --app=<app-id>
Lazy setup (nothing is npm-installed up front)
On every launch the host checks the package's runtime dependencies (except electron)
and those of the sibling libraries it loads (robos-lib, robos-ui, …, recorded per app in
the manifest when the shortcuts are created; same scan App Manager uses). If any are missing
it opens a small "Setting up RobOS (From Source)" window that already carries the
app's icon, runs npm install in each package that needs it (streaming the output), then
relaunches into the app. A first launch typically adds 1–3 s. Details:
- Packages with no
node_modulesgetnpm install --omit=dev; packages that already have some get a plainnpm installso dev dependencies are not pruned. ELECTRON_SKIP_BINARY_DOWNLOAD=1: apps run on the shared Electron, so the package's own copy is not downloaded. To usenpm startin that package later, runnode node_modules/electron/install.jsthere first.- The Node that ran
installis recorded and put first on PATH for npm, because a desktop menu's PATH can lack Node from nvm/fnm/Volta. - Output goes to
<RobOS data>/source-shortcuts-logs/<id>-setup.log. On failure the window stays open with the reason.
Apps look for shared libraries (robos-lib, robos-ui, …) in the neighbouring packages/
folder first, so nothing else needs installing. Data goes where npm start puts it: the
userData folder named after the package's productName/name.
Installing the shortcuts
node scripts/source-shortcuts/source-shortcuts.cjs list
node scripts/source-shortcuts/source-shortcuts.cjs install dev-central pr-review --desktop
node scripts/source-shortcuts/source-shortcuts.cjs install # every app, ~15 s (setup happens per app on first launch)
node scripts/source-shortcuts/source-shortcuts.cjs remove dev-central
node scripts/source-shortcuts/source-shortcuts.cjs remove # everything it created
On Windows run it from PowerShell or Git Bash with the same arguments. The first run installs
the shared Electron into scripts/source-shortcuts/node_modules (once, about 100 MB). If npm
holds back Electron's postinstall (npm 11 install-scripts approval) or its unzip step fails
(seen on Node 26), fetch-electron.cjs downloads it with Electron's own @electron/get and
unpacks it with tar.exe / ditto / unzip.
What it created is recorded in <RobOS data>/source-shortcuts.json (%LOCALAPPDATA%\RobOS,
~/.local/share/robos, ~/Library/Application Support/RobOS), so remove deletes exactly that.
Re-run install after moving the clone or changing an app's icon.png.
How each OS gets the right icon everywhere
Icons come from packages/<id>/icon.png (256×256, rendered from icon.svg by
scripts/app-manager/render-icons.cjs). The script builds every format in pure Node
(scripts/source-shortcuts/icons.cjs). The running window has to claim the same identity
as its shortcut, or the taskbar/dock shows a generic Electron icon in a separate group.
source-host.cjs does that before the app's main.js runs.
| Surface | Windows | Linux (GNOME) | macOS |
|---|---|---|---|
| Menu entry | %APPDATA%\Microsoft\Windows\Start Menu\Programs\RobOS (From Source)\RobOS <App> (From Source).lnk | ~/.local/share/applications/robos-source-<id>.desktop, grouped in a RobOS (From Source) app-grid folder | ~/Applications/RobOS (From Source)/RobOS <App> (From Source).app |
Desktop icon (--desktop) | Same .lnk on the real Desktop (OneDrive-redirected too) | Copy of the entry on the XDG desktop, chmod 755 + gio set … metadata::trusted true | Symlink to the bundle on ~/Desktop |
| Icon file | .ico with 16/20/24/32/40/48/64 px bitmaps + the 256 px PNG in %LOCALAPPDATA%\Programs\RobOS\icons\source-<id>-<hash>.ico | hicolor PNGs 16–256 px + scalable/…svg named robos-source-<id>, then gtk-update-icon-cache and update-desktop-database | Contents/Resources/icon.icns (PNG entries 16–256 px incl. @2x), registered with lsregister -f |
| Taskbar / dock identity | Shortcut and process share AppUserModelID com.rowbose.robos.source.<id> (app.setAppUserModelId, later app calls blocked) | StartupWMClass=robos-source-<id> = WM_CLASS / Wayland app_id (--class= + app.setName, app.setDesktopName, later renames blocked) | Bundle ID com.rowbose.robos.source.<id>; running tile gets app.dock.setIcon(icon.png) |
| Window / Alt+Tab icon | window.setIcon(<the .ico>) on every BrowserWindow | window.setIcon(icon.png) (Electron's _NET_WM_ICON needs a raster) | from the Dock icon |
Lessons that are baked in. Don't undo them:
HOMEis set (os.homedir()) beforemain.jsruns, as App Manager does. Apps build paths fromHOME, which Windows does not set (PR Review crashed with "Path must be absolute").- Windows
.lnkmust carry the AppUserModelID. Only Electron'sshell.writeShortcutLinksets it (win-lnk.cjs).WScript.Shellcannot. Without it the running window does not group with its pinned shortcut and shows electron.exe's icon. - Windows
.iconeeds small sizes. A 256-px-only.icoshows as a blank page in Start menu search. - Windows icon location matters. Start menu search refuses icons where app-container
processes may write (all of
AppData\Localcan be granted that);AppData\Local\Programsis safe. - Windows caches icons by path. The
.icois named by content hash, so a changed icon gets a new file instead of a stale cached one. - GNOME matches windows by WM_CLASS, and many apps call
app.setName()inmain.js; the host pins the name first and ignores later calls. - Electron on Linux cannot use an SVG window icon, so the host passes
icon.png. - macOS limitation: the bundle's launcher
execs the package's Electron, so while running, the Dock tile belongs to Electron.app: it shows the app's icon (viadock.setIcon) but its name/menu bar reads "Electron", and pinning that running tile pins Electron. Pin the(From Source)bundle from~/Applicationsinstead.
Validation
node --test scripts/source-shortcuts/source-shortcuts.test.cjspasses.node scripts/source-shortcuts/source-shortcuts.cjs listshows the app asmenu(ormenu+desktop).- Open the app from its menu entry/desktop icon. On first launch the setup window appears and
the app opens by itself afterwards (
listthen showsready). Check the taskbar/dock button shows the app's own icon (not the Electron atom) and groups with the pinned shortcut:- Windows: the window's process runs with
--app-user-model-id=com.rowbose.robos.source.<id>(visible in its renderer's command line), and the.lnk'sSystem.AppUserModel.IDmatches:$f = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\RobOS (From Source)\RobOS <App> (From Source).lnk" (New-Object -ComObject Shell.Application).NameSpace((Split-Path $f)).ParseName((Split-Path $f -Leaf)).ExtendedProperty('System.AppUserModel.ID') - GNOME:
xprop WM_CLASSon the window printsrobos-source-<id>.
- Windows: the window's process runs with
removeleaves no entry, desktop icon orsource-<id>-*.ico/robos-source-<id>.pngbehind.
Troubleshooting
- Setup window shows an npm error: read
<RobOS data>/source-shortcuts-logs/<id>-setup.log, fix the cause (e.g. Node/npm not installed), and open the app again; it retries. - Windows Firewall asks about "Electron" the first time an app opens a network port: that is
the shared Electron (
scripts/source-shortcuts/node_modules/electron/dist/electron.exe), asked once for all (From Source) apps. It is the user's choice; never answer it for them. - An app works with
npm startbut not from its shortcut: run the host command above in a terminal to see the error. Apps may assume Linux-only paths or environment variables. - Windows Start menu search does not list it yet: indexing can take a minute; the Start menu's All list shows it immediately.
- GNOME shows a gear icon: run
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor, then log out and in on Wayland if it persists. - Desktop icon on GNOME says "Untrusted": right-click → Allow Launching (happens if
giowas unavailable). scripts/install-local.shis the older, Linux-only way (entries namedrobos-<id>.desktop, no icon identity). Its--uninstallleaves theserobos-source-*entries alone.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |