agentcage 0.1.8 → 0.1.9

package/README.md

@@ -23,11 +23,6 @@ You need **Docker** (Docker Desktop on Windows/macOS, Docker Engine on Linux), *
 npm install -g agentcage           # also updates to the latest version
 ```
 
-```bash
-agentcage doctor        # checks all the prerequisites.
-```
-
-
 
 ## Quickstart
 
@@ -41,17 +36,19 @@ Run this in terminal:
 
 ```bash
 agentcage doctor        # checks all the prerequisites.
-agentcage               # Starts the container-creation dialogue
+agentcage               # Starts the CLI: UI or container-creation dialogue
 ```
 
-Follow the steps
 
 ## The agentcage window (UI)
+Agentcage UI gives you a graphical way to see and manage your devcontainers
 
 ```bash
 agentcage ui            # opens the agentcage window
 ```
 
+Running `agentcage` without a command also offers it as the first choice in the menu.
+
 A local web UI with the same features as the terminal dialog:
 - **Containers:** each container's status, and Start, Stop, Open in IDE, Add to OpenCode, OpenCode providers (gear button: add model provider API keys), Rebuild and Remove.
 - **New container:** a dialog to create one from a folder, a git URL, or a repository picked from **GitHub** or **Azure Repos**.
@@ -63,8 +60,9 @@ A local web UI with the same features as the terminal dialog:
 The window opens as an app window (Edge or Chrome `--app`), or as a normal browser tab if neither is installed.
 
 **Desktop icon:** the first `agentcage ui` offers to add an agentcage icon to the desktop and Start Menu (Windows) or app
-menu (Linux). Clicking it starts the UI without a console window. `agentcage ui --shortcut` adds the icon later, and
-`--no-shortcut` removes it.
+menu (Linux). Clicking it starts the UI without a console window. The window also offers it when it opens (until you add
+it or pick "Don't show this again"), and you can always add it under **Settings → Desktop icon** or with
+`agentcage ui --shortcut`; `--no-shortcut` removes it.
 
 **How it runs:** the UI is served by a small server on `127.0.0.1` only, protected by a random session token. It stops a
 few seconds after you close the window, unless a container is still being created. `--no-open` only prints the URL.

package/bin/agentcage.js

@@ -12,7 +12,7 @@ process.removeAllListeners('warning'); // hide node:sqlite ExperimentalWarning
 
 const HELP = `agentcage: isolated dev containers for AI coding agents
 
-  agentcage                         interactive menu (create or manage containers)
+  agentcage                         menu: open the agentcage window, or create / manage containers in the terminal
   agentcage ui                      open the agentcage window (containers, create dialog, GitHub / Azure Repos, help)
                                       [--shortcut] add a desktop / menu icon  [--no-shortcut] remove it  [--no-open] only print the URL
   agentcage new [folder|git-url]    create a container  [--name x] [--tools opencode,claude-code,python,gh,pnpm]
@@ -123,14 +123,16 @@ const commands = {
   },
   adopt() { const b = adoptContainer(arg); console.log(`Adopted '${b.name}' (${b.container}).`); },
 
-  // No command: menu
+  // No command: menu. The window (UI) comes first; the rest is the terminal flow.
   async menu() {
     const containers = listContainers();
-    if (!containers.length) return newWizard();
     p.intro('agentcage');
-    // '-settings' can't clash with a container name (names start with a letter or digit)
-    const pick = await ask(p.select({ message: 'What do you want to do?', options: [{ value: '', label: 'Create a new container' },
+    // '-ui' and '-settings' can't clash with a container name (names start with a letter or digit)
+    const pick = await ask(p.select({ message: 'What do you want to do?', options: [
+      { value: '-ui', label: 'Open the agentcage window', hint: 'containers, create dialog, GitHub / Azure Repos' },
+      { value: '', label: 'Create a new container (here in the terminal)' },
       ...containers.map(b => ({ value: b.name, label: b.name, hint: state(b) })), { value: '-settings', label: 'Settings' }] }));
+    if (pick === '-ui') return commands.ui();
     if (pick === '-settings') return settingsWizard();
     if (!pick) return newWizard();
     const action = await ask(p.select({ message: pick, options: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcage",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Isolated dev containers for AI coding agents (OpenCode, Claude Code), connected to OpenCode Desktop",
   "type": "module",
   "bin": {

package/src/server.js

@@ -12,7 +12,7 @@ import { isGitUrl, localRemote, parseRemote } from './git.js';
 import { connectDesktop, desktopRunning, desktopRunningAsync, desktopServers, detectDesktop, latestVersion, serverName, setProviderKey, setupProject } from './opencode.js';
 import { run } from './run.js';
 import { CHOICES, DEFAULTS, LABELS, loadSettings, saveSettings } from './settings.js';
-import { openWindow, pickFolder } from './shortcut.js';
+import { createShortcuts, hasShortcuts, openWindow, pickFolder } from './shortcut.js';
 import * as conn from './connections.js';
 
 const PAGE = new URL('./ui.html', import.meta.url), LOCK = join(ROOT, 'ui.json');
@@ -138,6 +138,9 @@ export async function serve({ open = true } = {}) {
     ['DELETE', /^\/api\/connections\/(github|azure)$/, ([, id]) => conn.removePat(id)],
     ['GET', /^\/api\/repos\/(github|azure)$/, ([, id], q) => conn.repos(id, q.get('org'))],
     ['POST', /^\/api\/browse$/, async (_, __, body) => ({ path: await pickFolder(body.start?.trim()) })],
+    ['GET', /^\/api\/shortcut$/, () => ({ supported: process.platform !== 'darwin', exists: hasShortcuts(), hideTip: !!loadSettings().hideShortcutTip })],
+    ['POST', /^\/api\/shortcut$/, () => ({ files: createShortcuts() })],
+    ['POST', /^\/api\/shortcut\/hide-tip$/, () => saveSettings({ ...loadSettings(), hideShortcutTip: true })],
   ];
 
   const server = createServer(async (req, res) => {

package/src/shortcut.js

@@ -29,6 +29,7 @@ const PS = `$w = New-Object -ComObject WScript.Shell
 foreach ($d in [Environment]::GetFolderPath('Desktop'), [Environment]::GetFolderPath('Programs')) {
   $f = Join-Path $d 'agentcage.lnk'
   if ($env:AC_REMOVE) { if (Test-Path $f) { Remove-Item $f; $f }; continue }
+  if ($env:AC_CHECK) { if (Test-Path $f) { $f }; break } # the desktop icon only
   $s = $w.CreateShortcut($f); $s.TargetPath = $env:AC_NODE; $s.Arguments = '"' + $env:AC_SCRIPT + '" ui --detach'
   $s.IconLocation = $env:AC_ICO; $s.WindowStyle = 7; $s.Description = 'agentcage: dev containers for AI coding agents'; $s.Save(); $f }`;
 const powershell = env => spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', PS], { encoding: 'utf8', env: { ...process.env, ...env }, windowsHide: true })
@@ -53,6 +54,7 @@ export function createShortcuts() {
   });
 }
 export const removeShortcuts = () => (WIN ? powershell({ AC_REMOVE: '1' }) : linuxFiles().filter(existsSync).map(f => (rmSync(f), f)));
+export const hasShortcuts = () => (WIN ? powershell({ AC_CHECK: '1' }) : linuxFiles().filter(existsSync)).length > 0;
 
 // Edge / Chrome / Chromium, for an app window (own window and taskbar icon, no tabs or address bar)
 function appBrowser() {

package/src/ui.html

@@ -15,6 +15,8 @@
   header { display: flex; align-items: center; gap: 12px; padding: 10px 20px; background: var(--brand); color: var(--brand-text); }
   header img { width: 28px; height: 28px; border-radius: 6px; }
   header b { font-size: 16px; margin-right: 16px; }
+  .tip { position: fixed; right: 20px; top: 62px; width: 350px; max-width: calc(100vw - 40px); background: var(--panel); color: var(--text); border: 1px solid var(--line); border-radius: 9px; padding: 12px 30px 12px 14px; font-size: 13px; line-height: 1.45; box-shadow: 0 6px 20px rgba(0,0,0,.25); z-index: 5; }
+  .tip .x { position: absolute; top: 4px; right: 4px; border: 0; background: none; padding: 2px 6px; color: var(--muted); }
   nav button { background: none; border: 0; color: inherit; opacity: .75; padding: 6px 10px; border-radius: 6px; font: inherit; cursor: pointer; }
   nav button.on, nav button:hover { opacity: 1; background: rgba(255,255,255,.14); }
   main { max-width: 1320px; margin: 0 auto; padding: 20px; }
@@ -65,6 +67,9 @@
 </style>
 </head>
 <body>
+<div id="tip" class="tip hidden" role="dialog" aria-label="Desktop icon"><button type="button" class="x" aria-label="Close">×</button>
+  <b>Open agentcage from your desktop</b><div style="margin-top:4px">Add an agentcage icon to your <span class="sc-places"></span>, so you can open this window without a terminal.</div>
+  <div class="row" style="margin-top:10px"><button class="primary add">Add desktop icon</button><button class="never">Don't show this again</button></div></div>
 <header>
   <img src="/icon.svg" alt=""><b>agentcage</b>
   <nav class="row">
@@ -123,6 +128,9 @@
     <p class="muted">Apply to containers created afterwards. Stored in <code>~/.agentcage/settings.json</code>, shared with <code>agentcage settings</code>.</p>
     <div class="card" style="max-width:560px"><div id="settings-form"></div>
       <div class="row" style="margin-top:14px"><button class="primary" id="settings-save">Save</button><span id="settings-msg" class="muted small"></span></div></div>
+    <div class="card hidden" id="sc-card" style="max-width:560px;margin-top:14px"><h3>Desktop icon</h3>
+      <p class="muted" style="margin:0">An agentcage icon on your <span class="sc-places"></span> opens this window without a terminal. <span id="sc-status"></span></p>
+      <div class="row"><button class="primary" id="sc-add">Add desktop icon</button></div></div>
   </section>
 
   <section id="help" class="hidden">
@@ -163,6 +171,13 @@
     <details><summary>IDEs</summary>
       <p><b>Open in IDE</b> attaches Cursor, VS Code or Antigravity to the container in the project folder. Use the IDE for editing, diffs
         and git. Its built-in AI agent runs outside the container's isolation, so run agents through OpenCode or Claude Code.</p></details>
+    <details><summary>Desktop icon</summary>
+      <ul><li>Go to <b>Settings</b> and click <b>Add desktop icon</b> at the bottom of the page. The icon is added to your desktop and to the
+          Start Menu (Windows) or app menu (Linux). New users are also offered it when the window opens.</li>
+        <li>The icon opens this window without a terminal. It reuses agentcage if it is already running.</li>
+        <li>In a terminal: <code>agentcage ui --shortcut</code> adds the icon, <code>agentcage ui --no-shortcut</code> removes it.</li>
+        <li>If you update or move Node.js, click <b>Add desktop icon</b> again so the icon points to the new location.</li>
+        <li>Not available on macOS yet: run <code>agentcage ui</code> there.</li></ul></details>
     <details><summary>Command line and troubleshooting</summary>
       <ul><li>Everything here also works in a terminal: <code>agentcage</code> (menu), <code>agentcage list</code>, <code>agentcage new</code>,
           <code>agentcage shell &lt;name&gt;</code>, <code>agentcage help</code>.</li>
@@ -435,13 +450,27 @@ $('#settings-save').onclick = run(async () => {
   STATE.settings = (await api('/api/state')).settings; $('#settings-msg').textContent = 'Saved.';
 });
 
+// Desktop icon: a button at the bottom of Settings, and a popover when the window opens while there is no desktop icon
+// (until the user adds one or picks "Don't show this again")
+async function shortcuts() {
+  const sc = await api('/api/shortcut').catch(() => ({})), tip = $('#tip');
+  if (!sc.supported) return;
+  $$('.sc-places').forEach(e => (e.textContent = META.platform === 'win32' ? 'desktop and Start Menu' : 'desktop and app menu'));
+  const added = exists => { $('#sc-status').textContent = exists ? 'You already have one; adding it again recreates it.' : ''; $('#sc-add').textContent = exists ? 'Recreate desktop icon' : 'Add desktop icon'; };
+  added(sc.exists); $('#sc-card').classList.remove('hidden');
+  const add = run(async () => { tip.classList.add('hidden'); await api('/api/shortcut', { method: 'POST' }); added(true); toast('Added the agentcage icon.'); });
+  $('#sc-add').onclick = tip.querySelector('.add').onclick = add;
+  tip.querySelector('.x').onclick = () => tip.classList.add('hidden');
+  tip.querySelector('.never').onclick = run(async () => { tip.classList.add('hidden'); await api('/api/shortcut/hide-tip', { method: 'POST' }); });
+  tip.classList.toggle('hidden', sc.exists || sc.hideTip);
+}
 // Tell the server this window is open (it stops a few seconds after the window closes); reconnect if it drops
 async function alive() { try { const r = await fetch('/api/alive', { headers: { 'x-agentcage-token': TOKEN } }); await r.text(); } catch {} setTimeout(alive, 2000); }
 
 (async () => {
   if (!TOKEN) return $('#banners').replaceChildren(h('div', { class: 'banner bad' }, 'Open agentcage with the agentcage icon or by running: agentcage ui'));
   try { META = await api('/api/meta'); } catch (e) { return $('#banners').replaceChildren(h('div', { class: 'banner bad' }, `${e.message}`)); }
-  alive(); refresh();
+  alive(); refresh(); shortcuts();
 })();
 </script>
 </body>