xtralab 0.5.0 → 0.7.0

package/README.md

@@ -1,10 +1,10 @@
 # xtralab
 
-An opinionated JupyterLab meta-package.
+An opinionated JupyterLab meta-package for use with coding agents.
 
-Bundles a curated set of extensions, a path-first file browser, the
-`jupyterlab-git` panel with its text, notebook and image diffs rendered by
-xtralab, an agent-focused launcher, and a quieter default workspace.
+It bundles a curated set of JupyterLab extensions, a path-first file browser,
+git diffs rendered by xtralab, an agent launcher, and a quieter default
+workspace.
 
 ![xtralab screenshot](./screenshot.png)
 
@@ -18,7 +18,7 @@ pip install xtralab
 
 ### As a JupyterLab package
 
-Run JupyterLab the usual way:
+Once installed, start JupyterLab the usual way:
 
 ```bash
 jupyter lab
@@ -26,85 +26,114 @@ jupyter lab
 
 ### As a desktop app
 
-A standalone Electron build (DMG on macOS, AppImage on Linux) ships with each
-tagged release — grab the installer for your platform from the
-[Releases page](https://github.com/jtpio/xtralab/releases/latest). Builds from
-the current `main` branch are also produced on every push as workflow
-artifacts under the repository's
+A standalone Electron build is also available, packaged as a DMG on macOS and
+an AppImage on Linux. Each tagged release ships installers on the
+[releases page](https://github.com/jtpio/xtralab/releases/latest), and builds
+from `main` are uploaded as workflow artifacts on the
 [Actions tab](https://github.com/jtpio/xtralab/actions). See
-[CONTRIBUTING.md](./CONTRIBUTING.md) for the architecture and local build
-instructions.
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the desktop app architecture and local
+build instructions.
 
 ## What's included
 
-- [`ajlab`](https://github.com/jtpio/ajlab) — agent-ready JupyterLab base
-- JupyterLab 4.6+
-- `jupyterlab-git` — provides the git panel; xtralab swaps its text,
-  notebook and image diff rendering for its own
-- `jupyterlab-lsp` + `ty` — Python LSP via Astral's `ty` (bundled); also
-  detects `typescript-language-server` on `PATH` for JS/TS
-- `jupyterlab-quickopen`
-- `jupyterlab-cursor-light`, `jupyterlab-cursor-dark`
-- `jupyterlab-day`, `jupyterlab-night` themes
+xtralab builds on [`ajlab`](https://github.com/jtpio/ajlab), the agent-ready
+JupyterLab base. On top of it, xtralab pulls in JupyterLab 4.6+ with
+`jupyterlab-git`, `jupyterlab-lsp`, `jupyterlab-quickopen`, `jupyterlab-vim`,
+and a set of light and dark themes (`jupyterlab-cursor-light`,
+`jupyterlab-cursor-dark`, `jupyterlab-day`, `jupyterlab-night`). See
+[`pyproject.toml`](./pyproject.toml) for the full list and pinned versions.
 
-The bundled labextension adds:
+The bundled xtralab labextension then adds:
 
 - A path-first file browser in the left sidebar.
-- xtralab-rendered diffs registered as `jupyterlab-git`'s diff providers
-  (its own notebook/plain-text/image diff plugins are disabled) so the
-  upstream git panel shows xtralab's diffs: `@pierre/diffs` for text and
-  notebooks, and an `<img>`-based 2-up/swipe/onion-skin view for images.
-- An agent launcher with a prompt textarea, a row of agent buttons (Claude,
-  Codex, Gemini, Copilot, Goose, OpenCode, Kiro, Mistral Vibe), and a
-  collapsible list of changed files. Buttons are filtered to agents installed
-  on the machine; a typed prompt is shell-quoted and spliced into the launch
-  command for agents that accept one.
+- Git diffs rendered by xtralab in the `jupyterlab-git` panel, using
+  `@pierre/diffs` for text and notebooks and a 2-up / swipe / onion-skin view
+  for images.
+- An agent launcher with a prompt box, buttons for the agents installed on your
+  machine (Claude, Codex, Antigravity, Copilot, Goose, OpenCode, Kiro, Mistral
+  Vibe), a collapsible list of changed files, and an Open row for a terminal,
+  notebook, console, or your terminal editor (Neovim or Vim).
+- A Terminals panel listing the running terminal sessions, each badged with the
+  agent or editor detected inside it. Open terminal tabs in the main area carry
+  the same icon.
+- Sidebar toggle buttons in the top bar for the left and right areas.
+
+## Connecting agents to Jupyter (MCP)
+
+xtralab runs a [Model Context Protocol][mcp-spec] server inside JupyterLab,
+provided by [`jupyter-server-mcp`][mcp]. To let a coding agent drive JupyterLab
+through it, register the bundled `jupyter-server-mcp-proxy` console script with
+the agent:
 
-## Language servers
+```bash
+claude mcp add jupyter -- jupyter-server-mcp-proxy
+codex mcp add jupyter -- jupyter-server-mcp-proxy
+copilot mcp add jupyter -- jupyter-server-mcp-proxy
+```
 
-xtralab ships with
-[`jupyterlab-lsp`](https://github.com/jupyter-lsp/jupyterlab-lsp) and
-pre-registers two language servers through
-`jupyter_server_config.d/xtralab-lsp.json`:
+Run this from a terminal inside xtralab, so the proxy inherits the server
+environment and discovers the running server automatically. No port is needed,
+and a single registration keeps working across restarts. The launcher also
+surfaces these commands with copy buttons, filtered to the agents you have
+installed.
 
-- **Python — [`ty`](https://github.com/astral-sh/ty)** — installed as a
-  Python dependency. Works out of the box.
-- **TypeScript / JavaScript — `typescript-language-server`** — install
-  yourself:
+See the [`jupyter-server-mcp` README][mcp] for other MCP clients.
 
-  ```bash
-  npm install -g typescript-language-server typescript
-  ```
+[mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
+[mcp-spec]: https://modelcontextprotocol.io
+
+## Agent skill
+
+xtralab ships an [Agent Skills][skills] entry at [`agent-skill/`](./agent-skill)
+that teaches any coding agent how to customize JupyterLab from plain-English
+requests like "hide the status bar", "change the theme", or "add a language
+server". The same SKILL.md file works with Claude Code, Codex CLI, Gemini CLI,
+GitHub Copilot, and other tools that read the Agent Skills format.
 
-  Restart JupyterLab (or the desktop app) after installing.
+For Claude Code, this repository doubles as a one-plugin marketplace. Inside a
+Claude Code session:
 
-Specs use bare command names (`["ty", "server"]`), so binaries are resolved
-from `PATH` at spawn time.
+```text
+/plugin marketplace add jtpio/xtralab
+/plugin install xtralab-skills@xtralab
+```
+
+For agents that read from `~/.agents/skills/`, such as Codex CLI or Gemini CLI,
+clone and copy the skill directory:
+
+```bash
+git clone --depth=1 https://github.com/jtpio/xtralab.git /tmp/xtralab
+mkdir -p ~/.agents/skills
+cp -r /tmp/xtralab/agent-skill/skills/customize-jupyterlab ~/.agents/skills/
+```
+
+See [`agent-skill/README.md`](./agent-skill/README.md) for additional install
+paths, the list of supported agents, and what the skill knows.
 
-### Where binaries are discovered
+[skills]: https://agentskills.io
+
+## Language servers
 
-- **`pip install xtralab`** — anything on the JupyterLab process's `PATH`.
-- **Desktop app** — the supervisor augments `PATH` with common shim
-  locations (`~/.volta/bin`, `~/.npm-global/bin`, `~/.bun/bin`,
-  `~/.asdf/shims`, `~/.mise/shims`, `/opt/homebrew/bin`, `/usr/local/bin`,
-  …). Set `XTRALAB_EXTRA_PATH` (colon-separated) before launching the app
-  to add directories the defaults miss.
+xtralab ships [`jupyterlab-lsp`][lsp] with two language servers pre-registered:
 
-### Adding more servers
+- Python, using [`ty`](https://github.com/astral-sh/ty), which is bundled and
+  works out of the box.
+- TypeScript and JavaScript, using `typescript-language-server`, which you
+  install yourself:
 
-To enable another server (bash, yaml, json, dockerfile, pyright, …),
-install the binary then drop a JSON file into a `jupyter_server_config.d/`
-directory:
+  ```bash
+  npm install -g typescript-language-server typescript
+  ```
 
-- **`pip install xtralab`** — run `jupyter --paths` and pick a config dir
-  (typically `~/.jupyter/jupyter_server_config.d/`).
-- **Desktop app (macOS)** —
-  `~/Library/Application Support/xtralab/jupyter/config/jupyter_server_config.d/`
-  (or `xtralab dev` for local dev builds).
-- **Desktop app (Linux AppImage)** —
-  `~/.config/xtralab/jupyter/config/jupyter_server_config.d/`.
+  Restart JupyterLab afterwards to pick it up.
 
-Example (`bash-lsp.json`):
+To enable another server (bash, yaml, json, pyright, and more), install its
+binary and drop a JSON spec into a `jupyter_server_config.d/` directory. For
+`pip install xtralab`, run `jupyter --paths` to find one (typically
+`~/.jupyter/jupyter_server_config.d/`). For the desktop app, use
+`~/Library/Application Support/xtralab/jupyter/config/jupyter_server_config.d/`
+on macOS or `~/.config/xtralab/jupyter/config/jupyter_server_config.d/` on
+Linux.
 
 ```json
 {
@@ -122,15 +151,19 @@ Example (`bash-lsp.json`):
 }
 ```
 
-Pair with `npm install -g bash-language-server`. Reuse a bundled `key` to
-override it. See
-[jupyterlab-lsp's docs](https://jupyterlab-lsp.readthedocs.io/en/latest/Configuring.html)
-for the full spec schema.
+See the [`jupyterlab-lsp` documentation][lsp-config] for the full spec.
+
+[lsp]: https://github.com/jupyter-lsp/jupyterlab-lsp
+[lsp-config]: https://jupyterlab-lsp.readthedocs.io/en/latest/Configuring.html
 
 ## Customizing the launcher
 
-Open `Settings → Settings Editor → xtralab launcher` and edit the `agents`
-array. Entries are merged with the defaults by `id`.
+Open `Settings → Settings Editor → xtralab launcher` to override, hide, or add
+launcher entries. Both lists below merge with xtralab's defaults by `id`.
+
+### Agents
+
+Edit the `agents` array:
 
 ```jsonc
 {
@@ -147,14 +180,43 @@ array. Entries are merged with the defaults by `id`.
 }
 ```
 
-Fields: `id` (required), `label`, `caption`, `command`, `promptArgs` (how to
-splice the prompt — `[]` for positional, `["--flag"]` for flagged, `null` to
-opt out), `iconSvg`, `rank`, `enabled`, `requireAvailable`.
+Fields: `id` (required), `label`, `caption`, `command`, `promptArgs` (how the
+prompt is spliced: `[]` for positional, `["--flag"]` for flagged, `null` to opt
+out), `iconSvg`, `rank`, `enabled`, `requireAvailable`.
+
+### Editors
+
+The **Open** section's terminal-editor tile (Neovim, falling back to Vim) is
+configured the same way through an `editors` array:
+
+```jsonc
+{
+  "editors": [
+    // Hide Neovim so the tile falls back to Vim (or disappears if Vim
+    // isn't installed either)
+    { "id": "nvim", "enabled": false },
+
+    // Add Helix, preferred over the built-ins
+    {
+      "id": "helix",
+      "label": "Helix",
+      "command": "hx",
+      "rank": -1,
+      "iconSvg": "<svg>…</svg>"
+    }
+  ]
+}
+```
+
+The launcher shows a single tile: the first editor, by `rank`, whose `command`
+is on `PATH`. Disable both built-ins (`nvim`, `vim`) to remove the tile
+entirely. Fields: `id` (required), `label`, `caption`, `command`, `iconSvg`,
+`rank`, `enabled`, `requireAvailable`.
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, the
-Electron desktop app architecture, and the build pipeline.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, the Electron
+desktop app architecture, and the build pipeline.
 
 ## License
 

package/lib/agentSessions.d.ts

@@ -0,0 +1,50 @@
+import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+/**
+ * A shared map from a terminal session name to the agent command it was
+ * *launched* with (e.g. `claude`).
+ *
+ * This is the optimistic half of the running-agent badge: when the launcher
+ * (or the terminals panel's `+` menu) starts an agent via a
+ * `xtralab:start-agent:<id>` command, it records the session here so the
+ * panel can show the agent's logo immediately, before the server-side
+ * process detection has had a chance to confirm it. Server detection is the
+ * authoritative source once it reports on a session; this tag only fills the
+ * gap right after launch (and serves as a fallback if detection is
+ * unavailable).
+ *
+ * It exists as its own token, provided by a tiny dependency-free plugin,
+ * specifically so the launcher (the writer) and the terminals panel (the
+ * reader) can share it without depending on each other — a direct
+ * launcher↔terminals token pair would form an activation cycle.
+ */
+export interface IAgentSessions {
+    /**
+     * The agent command a session was launched with, or `null` if we never
+     * launched an agent into it (e.g. a plain terminal, or one started before
+     * this ran).
+     */
+    get(sessionName: string): string | null;
+    /** Record that a session was launched as the given agent command. */
+    set(sessionName: string, command: string): void;
+    /** Forget a session — called when it shuts down so the map stays bounded. */
+    delete(sessionName: string): void;
+    /**
+     * Emitted with the affected session name whenever a record is added or
+     * removed, so readers can re-render.
+     */
+    readonly changed: ISignal<IAgentSessions, string>;
+}
+/**
+ * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
+ * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
+ */
+export declare const IAgentSessions: Token<IAgentSessions>;
+/**
+ * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
+ * sit underneath both the launcher and the terminals panel without creating
+ * a dependency cycle between them.
+ */
+declare const plugin: JupyterFrontEndPlugin<IAgentSessions>;
+export default plugin;

package/lib/agentSessions.js

@@ -0,0 +1,45 @@
+import { Token } from '@lumino/coreutils';
+import { Signal } from '@lumino/signaling';
+/**
+ * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
+ * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
+ */
+export const IAgentSessions = new Token('xtralab:IAgentSessions', 'A shared map from terminal session name to the agent command it was launched with.');
+class AgentSessions {
+    constructor() {
+        this._byName = new Map();
+        this._changed = new Signal(this);
+    }
+    get(sessionName) {
+        var _a;
+        return (_a = this._byName.get(sessionName)) !== null && _a !== void 0 ? _a : null;
+    }
+    set(sessionName, command) {
+        if (this._byName.get(sessionName) === command) {
+            return;
+        }
+        this._byName.set(sessionName, command);
+        this._changed.emit(sessionName);
+    }
+    delete(sessionName) {
+        if (this._byName.delete(sessionName)) {
+            this._changed.emit(sessionName);
+        }
+    }
+    get changed() {
+        return this._changed;
+    }
+}
+/**
+ * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
+ * sit underneath both the launcher and the terminals panel without creating
+ * a dependency cycle between them.
+ */
+const plugin = {
+    id: 'xtralab:agent-sessions',
+    description: 'Shared map from terminal session to the agent command it was launched with, used to badge terminal rows with the running agent.',
+    autoStart: true,
+    provides: IAgentSessions,
+    activate: () => new AgentSessions()
+};
+export default plugin;

package/lib/fileBrowser/index.js

@@ -22,7 +22,11 @@ const plugin = {
                 void app.commands.execute('docmanager:open', { path: serverPath });
             }
         });
-        app.shell.add(browser, 'left', { rank: 50 });
+        // Ranks just under the Terminals panel in the left sidebar. The shipped
+        // `layout` setting assigns the default ranks (rank only, no area pin),
+        // so this browser stays movable via the "Move Widget" context menu; the
+        // `rank` here is the in-code fallback for when that setting is absent.
+        app.shell.add(browser, 'left', { rank: 2 });
         if (restorer) {
             restorer.add(browser, browser.id);
         }

package/lib/git/imageDiff.js

@@ -164,15 +164,87 @@ function RangeSlider(props) {
 }
 function Swipe({ reference, challenger }) {
     const [position, setPosition] = React.useState(50);
+    const [dragging, setDragging] = React.useState(false);
+    const frameRef = React.useRef(null);
+    const setFromClientX = React.useCallback((clientX) => {
+        const frame = frameRef.current;
+        if (frame === null) {
+            return;
+        }
+        const rect = frame.getBoundingClientRect();
+        if (rect.width <= 0) {
+            return;
+        }
+        const next = ((clientX - rect.left) / rect.width) * 100;
+        setPosition(Math.max(0, Math.min(100, next)));
+    }, []);
+    const onPointerDown = React.useCallback((event) => {
+        // Only react to the primary pointer (left click / touch / pen tip).
+        if (event.button !== 0) {
+            return;
+        }
+        event.preventDefault();
+        setDragging(true);
+        setFromClientX(event.clientX);
+    }, [setFromClientX]);
+    React.useEffect(() => {
+        if (!dragging) {
+            return;
+        }
+        const onMove = (event) => {
+            setFromClientX(event.clientX);
+        };
+        const onUp = () => {
+            setDragging(false);
+        };
+        window.addEventListener('pointermove', onMove);
+        window.addEventListener('pointerup', onUp);
+        window.addEventListener('pointercancel', onUp);
+        return () => {
+            window.removeEventListener('pointermove', onMove);
+            window.removeEventListener('pointerup', onUp);
+            window.removeEventListener('pointercancel', onUp);
+        };
+    }, [dragging, setFromClientX]);
+    const onKeyDown = React.useCallback((event) => {
+        const step = event.shiftKey ? 10 : 1;
+        let next = null;
+        switch (event.key) {
+            case 'ArrowLeft':
+                next = position - step;
+                break;
+            case 'ArrowRight':
+                next = position + step;
+                break;
+            case 'Home':
+                next = 0;
+                break;
+            case 'End':
+                next = 100;
+                break;
+        }
+        if (next === null) {
+            return;
+        }
+        event.preventDefault();
+        setPosition(Math.max(0, Math.min(100, next)));
+    }, [position]);
     return (React.createElement("div", { className: "jp-xtralab-ImageDiff-interactive" },
-        React.createElement("div", { className: "jp-xtralab-ImageDiff-stack" },
-            reference.uri !== null ? (React.createElement("img", { className: "jp-xtralab-ImageDiff-stackImg", src: reference.uri, alt: "Reference revision", style: {
-                    clipPath: `inset(0 ${100 - position}% 0 0)`
-                } })) : null,
-            challenger.uri !== null ? (React.createElement("img", { className: "jp-xtralab-ImageDiff-stackImg", src: challenger.uri, alt: "Challenger revision", style: {
-                    clipPath: `inset(0 0 0 ${position}%)`
-                } })) : null),
-        React.createElement(RangeSlider, { value: position, onChange: setPosition, ariaLabel: "Swipe between reference and challenger" })));
+        React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeFrame", ref: frameRef, onPointerDown: onPointerDown, "data-dragging": dragging ? 'true' : undefined },
+            React.createElement("div", { className: "jp-xtralab-ImageDiff-stack" },
+                reference.uri !== null ? (React.createElement("img", { className: "jp-xtralab-ImageDiff-stackImg", src: reference.uri, alt: "Reference revision", draggable: false, style: {
+                        clipPath: `inset(0 ${100 - position}% 0 0)`
+                    } })) : null,
+                challenger.uri !== null ? (React.createElement("img", { className: "jp-xtralab-ImageDiff-stackImg", src: challenger.uri, alt: "Challenger revision", draggable: false, style: {
+                        clipPath: `inset(0 0 0 ${position}%)`
+                    } })) : null),
+            React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDivider", style: { left: `${position}%` }, role: "slider", "aria-label": "Swipe between reference and challenger", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": Math.round(position), "aria-orientation": "vertical", tabIndex: 0, onKeyDown: onKeyDown },
+                React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerHandle jp-mod-top" },
+                    React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerArrow jp-mod-left" }),
+                    React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerArrow jp-mod-right" })),
+                React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerHandle jp-mod-bottom" },
+                    React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerArrow jp-mod-left" }),
+                    React.createElement("div", { className: "jp-xtralab-ImageDiff-swipeDividerArrow jp-mod-right" }))))));
 }
 function OnionSkin({ reference, challenger }) {
     const [opacity, setOpacity] = React.useState(50);

package/lib/index.d.ts

@@ -4,8 +4,9 @@ import { JupyterFrontEndPlugin } from '@jupyterlab/application';
  * labextension is an array because the package bundles several independent
  * enhancements (file browser, git diff providers, …) — JupyterLab activates
  * each plugin individually and only the ones whose required tokens are
- * available end up running. `gitPlugins` is itself an array (the launcher
- * diff command + the jupyterlab-git diff providers), so it is spread in.
+ * available end up running. `gitPlugins` and `launcherPlugins` are themselves
+ * arrays (the git diff providers; the launcher plus its editor registry), so
+ * they are spread in.
  */
 declare const plugins: JupyterFrontEndPlugin<unknown>[];
 export default plugins;

package/lib/index.js

@@ -1,27 +1,32 @@
+import agentSessionsPlugin from './agentSessions';
 import fileBrowserPlugin from './fileBrowser';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
-import launcherPlugin from './launcher';
+import launcherPlugins from './launcher';
 import menusPlugin from './menus';
 import sidebarPlugin from './sidebar';
-import statusBarPlugin from './statusBar';
+import terminalsPlugin from './terminals';
+import topBarPlugin from './topBar';
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
  * labextension is an array because the package bundles several independent
  * enhancements (file browser, git diff providers, …) — JupyterLab activates
  * each plugin individually and only the ones whose required tokens are
- * available end up running. `gitPlugins` is itself an array (the launcher
- * diff command + the jupyterlab-git diff providers), so it is spread in.
+ * available end up running. `gitPlugins` and `launcherPlugins` are themselves
+ * arrays (the git diff providers; the launcher plus its editor registry), so
+ * they are spread in.
  */
 const plugins = [
+    agentSessionsPlugin,
     editorBreadcrumbsPlugin,
     editorIndentPlugin,
     fileBrowserPlugin,
     ...gitPlugins,
-    launcherPlugin,
+    ...launcherPlugins,
     menusPlugin,
     sidebarPlugin,
-    statusBarPlugin
+    terminalsPlugin,
+    topBarPlugin
 ];
 export default plugins;

package/lib/launcher/agents.d.ts

@@ -23,7 +23,7 @@ export interface IAgent {
      * the user types one into the launcher's prompt box. The semantics:
      *
      *   - `[]` → prompt is appended as a positional argument:
-     *     `<command> 'PROMPT'`. (Used by claude, codex, gemini, vibe.)
+     *     `<command> 'PROMPT'`. (Used by claude, codex, vibe.)
      *   - `['-i']` / `['--prompt']` → the prompt is preceded by a flag:
      *     `<command> -i 'PROMPT'`. (Used by copilot, opencode.)
      *   - `undefined` → the agent does not accept an initial prompt. The

package/lib/launcher/agents.js

@@ -1,12 +1,15 @@
 import { LabIcon, terminalIcon } from '@jupyterlab/ui-components';
 import { BUILTIN_AGENT_ICONS } from './icons';
 /**
- * Default agent cards shipped with xtralab. The list mirrors the eight
- * first-class personas in `jupyter-ai-contrib/jupyter-ai-acp-client` (which
- * is also where the icons come from), but uses the bare CLI names a user
- * would type in a terminal rather than the ACP wrapper binaries that
- * project spawns. Anything not on the user's `$PATH` is filtered out at
- * activation time, so the wider list is harmless.
+ * Default agent cards shipped with xtralab. Seven of these (Claude, Codex,
+ * Copilot, Goose, OpenCode, Kiro, Mistral Vibe) mirror first-class personas
+ * in `jupyter-ai-contrib/jupyter-ai-acp-client` (which is also where their
+ * icons come from), but use the bare CLI names a user would type in a
+ * terminal rather than the ACP wrapper binaries that project spawns.
+ * Antigravity (Google's agent-first IDE/CLI, `agy`) takes the Google slot —
+ * Gemini CLI was dropped because Google is sunsetting it for consumer
+ * accounts on 2026-06-18. Anything not on the user's `$PATH` is filtered
+ * out at activation time, so the wider list is harmless.
  */
 const DEFAULTS = [
     {
@@ -30,14 +33,20 @@ const DEFAULTS = [
         promptArgs: []
     },
     {
-        id: 'gemini',
-        label: 'Gemini',
-        caption: 'Start the Gemini CLI in a new terminal.',
-        command: 'gemini',
-        icon: BUILTIN_AGENT_ICONS.gemini,
+        id: 'antigravity',
+        label: 'Antigravity',
+        caption: 'Open Google Antigravity from a new terminal.',
+        command: 'agy',
+        icon: BUILTIN_AGENT_ICONS.antigravity,
         rank: 2,
-        requireAvailable: true,
-        promptArgs: []
+        requireAvailable: true
+        // `agy` is the Antigravity launcher binary — a VS Code-derived editor
+        // CLI that opens the Agent Manager / workspace, not a terminal REPL.
+        // Its positional args are file/folder paths, so there is no inline
+        // natural-language prompt form; like goose/kiro we omit promptArgs so a
+        // typed prompt dims the button instead of being mangled into a path.
+        // The command stays the bare binary (no `agy .`) so the server-side
+        // `shutil.which` availability check still resolves it.
     },
     {
         id: 'copilot',

package/lib/launcher/commands.d.ts

@@ -1,15 +1,14 @@
 import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { MainAreaWidget } from '@jupyterlab/apputils';
+import type { ITerminal } from '@jupyterlab/terminal';
+import type { CommandRegistry } from '@lumino/commands';
 import { type IDisposable } from '@lumino/disposable';
+import type { IAgentSessions } from '../agentSessions';
 import type { IAgent } from './agents';
 /**
  * The command id for opening the launcher.
  */
 export declare const CREATE_LAUNCHER_COMMAND = "launcher:create";
-/**
- * Build a JupyterLab command id for a given agent. Centralised so the
- * plugin and the launcher both use the same names.
- */
-export declare function agentCommandId(agentId: string): string;
 /**
  * Register a JupyterLab command per agent. Each command opens a new
  * terminal via `terminal:create-new` and feeds the agent's shell command
@@ -18,5 +17,32 @@ export declare function agentCommandId(agentId: string): string;
  * Returns a single disposable that tears down every registered command —
  * the launcher disposes the previous set before re-registering on settings
  * changes so the command palette stays in sync with the configured agents.
+ *
+ * When an `agentSessions` registry is supplied, each launch tags its terminal
+ * session with the agent's command, so the terminals panel can badge the row
+ * with the agent's logo immediately (before server-side detection confirms
+ * it).
+ */
+export declare function registerAgentCommands(app: JupyterFrontEnd, agents: IAgent[], agentSessions?: IAgentSessions | null): IDisposable;
+/**
+ * Open a fresh terminal, type `invocation` into it as if the user had, and
+ * label the tab. Shared by the per-agent launch commands and the launcher's
+ * editor tile so the fiddly "wait for the websocket, then write stdin"
+ * sequence lives in one place.
+ *
+ * `onSession`, when given, is called once with the new session's name right
+ * after the terminal is revealed. Callers use it to optimistically tag the
+ * session so the terminals panel can badge it with the agent's (or editor's)
+ * logo before server-side detection confirms the running process.
+ *
+ * Resolves with the host `MainAreaWidget` so the caller can place it — the
+ * launcher swaps it into its own tab.
  */
-export declare function registerAgentCommands(app: JupyterFrontEnd, agents: IAgent[]): IDisposable;
+export declare function launchInTerminal(commands: CommandRegistry, options: {
+    cwd?: string;
+    /** The literal command line typed into the fresh terminal. */
+    invocation: string;
+    /** Tab/title label applied once the command is sent. */
+    label: string;
+    onSession?: (sessionName: string) => void;
+}): Promise<MainAreaWidget<ITerminal.ITerminal>>;