xtralab 0.4.0 → 0.6.0

package/README.md

@@ -1,9 +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, a VS Code-style
-git changes panel, 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)
 
@@ -17,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
@@ -25,81 +26,84 @@ 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` — backs the bundled changes panel
-- `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.
-- A "Source Control" panel powered by `jupyterlab-git` and `@pierre/diffs`.
-- 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
-
-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`:
+```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
+```
 
-- **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:
+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.
 
-  ```bash
-  npm install -g typescript-language-server typescript
-  ```
+See the [`jupyter-server-mcp` README][mcp] for other MCP clients.
 
-  Restart JupyterLab (or the desktop app) after installing.
+[mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
+[mcp-spec]: https://modelcontextprotocol.io
 
-Specs use bare command names (`["ty", "server"]`), so binaries are resolved
-from `PATH` at spawn time.
-
-### Where binaries are discovered
+## 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
 {
@@ -117,15 +121,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
 {
@@ -142,14 +150,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/commands.d.ts

@@ -1,17 +1,16 @@
 import { JupyterFrontEnd } from '@jupyterlab/application';
-import { ICommandPalette, IThemeManager } from '@jupyterlab/apputils';
+import { IThemeManager } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { Contents } from '@jupyterlab/services';
 import { createGitDiffWidget, diffWidgetId } from './diffWidget';
-import { GitPanel } from './panel';
 import { IFileChange } from './tokens';
 /**
- * Command IDs exposed by the git plugin. Both are registered in
- * {@link registerGitCommands} so other extensions, the command palette and
- * keybindings can drive the panel without going through the React internals.
+ * Command IDs exposed by the launcher's git diff path. The launcher
+ * dashboard's "Changes" section drives {@link CommandIDs.openDiff} to open
+ * its own diff tab, independent of `jupyterlab-git` (whose panel reaches
+ * the same rendering via the providers in `diffProvider.tsx`).
  */
 export declare namespace CommandIDs {
-    const refresh = "xtralab:git:refresh";
     const openDiff = "xtralab:git:open-diff";
 }
 /**
@@ -29,9 +28,7 @@ export declare namespace CommandArguments {
 }
 export interface IRegisterGitCommandsOptions {
     app: JupyterFrontEnd;
-    panel: GitPanel;
     themeManager: IThemeManager | null;
-    commandPalette: ICommandPalette | null;
     /**
      * Contents manager used by the diff widget to write hunk-discard
      * results back to the working tree.
@@ -46,7 +43,10 @@ export interface IRegisterGitCommandsOptions {
     rendermime: IRenderMimeRegistry | null;
     /**
      * Called whenever the diff widget mutates the working tree (e.g. after
-     * a hunk discard) so the plugin can refresh the changes panel.
+     * a hunk discard). The launcher dashboard polls git status on its own
+     * cadence and `jupyterlab-git`'s panel auto-refreshes on the contents
+     * `fileChanged` signal the save emits, so this is a hook for any extra
+     * bookkeeping rather than a required refresh.
      */
     onChanged: () => void;
     /**
@@ -63,9 +63,8 @@ export interface IRegisterGitCommandsOptions {
     onPinned(widget: ReturnType<typeof createGitDiffWidget>): void;
 }
 /**
- * Register the git commands on the application command registry. Returns
- * a disposer that clears the command palette items the registration created
- * (the commands themselves stay registered for the lifetime of the plugin).
+ * Register the launcher's git diff command on the application command
+ * registry.
  */
-export declare function registerGitCommands(options: IRegisterGitCommandsOptions): () => void;
+export declare function registerGitCommands(options: IRegisterGitCommandsOptions): void;
 export { diffWidgetId };

package/lib/git/commands.js

@@ -1,31 +1,21 @@
-import { refreshIcon } from '@jupyterlab/ui-components';
 import { createGitDiffWidget, diffWidgetId, updateGitDiffWidget } from './diffWidget';
 /**
- * Command IDs exposed by the git plugin. Both are registered in
- * {@link registerGitCommands} so other extensions, the command palette and
- * keybindings can drive the panel without going through the React internals.
+ * Command IDs exposed by the launcher's git diff path. The launcher
+ * dashboard's "Changes" section drives {@link CommandIDs.openDiff} to open
+ * its own diff tab, independent of `jupyterlab-git` (whose panel reaches
+ * the same rendering via the providers in `diffProvider.tsx`).
  */
 export var CommandIDs;
 (function (CommandIDs) {
-    CommandIDs.refresh = 'xtralab:git:refresh';
     CommandIDs.openDiff = 'xtralab:git:open-diff';
 })(CommandIDs || (CommandIDs = {}));
 /**
- * Register the git commands on the application command registry. Returns
- * a disposer that clears the command palette items the registration created
- * (the commands themselves stay registered for the lifetime of the plugin).
+ * Register the launcher's git diff command on the application command
+ * registry.
  */
 export function registerGitCommands(options) {
-    const { app, panel, themeManager, commandPalette, contentsManager, rendermime, onChanged, trackDiff, findDiff, onPinned } = options;
+    const { app, themeManager, contentsManager, rendermime, onChanged, trackDiff, findDiff, onPinned } = options;
     const { commands } = app;
-    commands.addCommand(CommandIDs.refresh, {
-        label: 'Refresh Git Changes',
-        caption: 'Refresh the git changes panel',
-        icon: refreshIcon,
-        execute: () => {
-            panel.refresh();
-        }
-    });
     commands.addCommand(CommandIDs.openDiff, {
         label: 'Open Git Diff',
         caption: 'Open a side-by-side diff for a changed file',
@@ -58,16 +48,5 @@ export function registerGitCommands(options) {
             app.shell.activateById(widget.id);
         }
     });
-    const paletteItems = commandPalette
-        ? [
-            commandPalette.addItem({
-                command: CommandIDs.refresh,
-                category: 'Git'
-            })
-        ]
-        : [];
-    return () => {
-        paletteItems.forEach(item => item.dispose());
-    };
 }
 export { diffWidgetId };

package/lib/git/diffProvider.d.ts

@@ -0,0 +1,8 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Registers xtralab's diff rendering as jupyterlab-git's diff providers:
+ * `@pierre/diffs` for text and notebooks, the bundled `<img>`-based view
+ * for raster images.
+ */
+declare const diffProviderPlugin: JupyterFrontEndPlugin<void>;
+export default diffProviderPlugin;