xtralab 0.11.0 → 0.12.0

package/README.md

@@ -1,261 +1,69 @@
 ![xtralab-logo](./logo.png)
 
-An opinionated JupyterLab meta-package for use with coding agents.
+An opinionated JupyterLab meta-package for coding agents.
 
-It bundles a curated set of JupyterLab extensions, a path-first file browser,
-rich git diffs for text, notebooks, and images, an agent launcher, and a
-quieter default workspace.
+xtralab reshapes JupyterLab around terminal coding agents. It bundles a curated
+set of extensions, a path-first file browser, rich git diffs, an agent launcher,
+a Model Context Protocol server that lets agents drive the app, and a quieter
+set of defaults. It builds on [`ajlab`](https://github.com/jtpio/ajlab), the
+agent-ready JupyterLab base.
 
-![xtralab screenshot](./screenshot.png)
+![The xtralab workspace: path-first file browser, agent launcher, a side-by-side git diff, and a running Claude Code session](./images/hero.webp)
+
+The [documentation](https://jtpio.github.io/xtralab/) covers everything in
+detail: [installation](https://jtpio.github.io/xtralab/installation/), a
+[tour of the features](https://jtpio.github.io/xtralab/getting-started/),
+[connecting agents over MCP](https://jtpio.github.io/xtralab/agents/mcp/),
+[agent skills](https://jtpio.github.io/xtralab/agents/skills/), and the
+[desktop app](https://jtpio.github.io/xtralab/desktop/).
 
 ## Install
 
 ```bash
 pip install xtralab
-```
-
-## Usage
-
-### As a JupyterLab package
-
-Once installed, start JupyterLab the usual way:
-
-```bash
 jupyter lab
 ```
 
-### As a desktop app
-
-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 desktop app architecture and local
-build instructions.
-
-On macOS the build is not notarized yet (it has no Apple Developer ID), so
-Gatekeeper blocks it on first launch, and agent notifications fall back to
-`osascript`, appearing as "Script Editor". In the meantime you can self-sign it
-for free: this lets it launch and gives native notifications instead, branded as
-xtralab and clickable to jump to the terminal that fired them. Create a
-code-signing certificate once in Keychain Access (Certificate Assistant, Create
-a Certificate, with Identity Type "Self Signed Root" and Certificate Type "Code
-Signing") named `xtralab-selfsign`, then sign the app you copied out of the DMG:
-
-```bash
-codesign --force --deep --sign "xtralab-selfsign" --timestamp=none "/Applications/xtralab.app"
-xattr -dr com.apple.quarantine "/Applications/xtralab.app"
-```
-
-macOS prompts once to let `codesign` use the key; choose Always Allow. None of
-this will be needed once the app ships with a Developer ID signature.
-
-## What's included
+A standalone desktop app (DMG on macOS, AppImage on Linux) ships with every
+tagged release on the
+[releases page](https://github.com/jtpio/xtralab/releases/latest); see the
+[desktop app docs](https://jtpio.github.io/xtralab/desktop/) for the
+Gatekeeper notes and how it manages projects and kernels.
 
-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-search-replace`, `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.
+## Highlights
 
-The bundled xtralab labextension then adds:
+![The xtralab launcher](./images/launcher.webp)
 
-- A path-first file browser in the left sidebar, with `@pierre/trees`
-  file-type icons that also carry over to document tabs and the `jupyterlab-git`
-  panel.
-- Rich git diffs 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.
+The launcher starts any agent installed on your machine, with an optional
+prompt and a **Changes** list that jumps straight into a side-by-side git diff
+you can edit in place. Select code in an editor, a notebook, or a diff to send
+a prompt about it to a new or already-running agent, or queue prompts while
+you read. One omnibox searches files and commands, the Terminals panel shows
+which agent runs where, and quieter defaults keep the workspace calm. The
+[documentation](https://jtpio.github.io/xtralab/) walks through each of these.
 
-xtralab also ships a set of opinionated defaults: unused UI is hidden for a
-quieter workspace, the activity bar sits at the top, and autocompletion,
-continuous LSP hinting, code folding, and gitignore-aware quick open are on by
-default. See [the bundled labconfig overrides](./jupyter-config/labconfig) for
-the full set.
-
-## Connecting agents to Jupyter (MCP)
+## Connecting agents to JupyterLab (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:
+provided by [`jupyter-server-mcp`][mcp], so an agent can open files, run
+cells, and read notebooks. Register the bundled proxy from a terminal inside
+xtralab:
 
 ```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
 ```
 
-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.
-
-See the [`jupyter-server-mcp` README][mcp] for other MCP clients.
+The launcher surfaces the matching command for every agent you have
+installed, and the [MCP docs page](https://jtpio.github.io/xtralab/agents/mcp/)
+covers the details.
 
 [mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
 [mcp-spec]: https://modelcontextprotocol.io
 
-## Agent skills
-
-xtralab ships [Agent Skills][skills] at [`agent-skill/`](./agent-skill) that
-teach any coding agent how to work with the app:
-
-- **customize-jupyterlab** turns plain-English requests like "hide the status
-  bar", "change the theme", or "add a language server" into the right
-  config-file edits.
-- **guided-code-walkthrough** drives the running app over the MCP command
-  bridge (see the section above) to open files, jump to and highlight specific
-  lines (`xtralab:highlight-lines`), and build a read-only Walkthrough panel of
-  prose, snippets, diagrams, and clickable code links beside the editor
-  (`xtralab:walkthrough`, no notebook or kernel needed), so the agent can _show_
-  you something at your own pace instead of only describing it in chat.
-
-The same SKILL.md files work with Claude Code, Codex CLI, Gemini CLI, GitHub
-Copilot, and other tools that read the Agent Skills format.
-
-For Claude Code, this repository doubles as a one-plugin marketplace. Inside a
-Claude Code session:
-
-```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 directories:
-
-```bash
-git clone --depth=1 https://github.com/jtpio/xtralab.git /tmp/xtralab
-mkdir -p ~/.agents/skills
-cp -r /tmp/xtralab/agent-skill/skills/* ~/.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.
-
-[skills]: https://agentskills.io
-
-## Language servers
-
-xtralab ships [`jupyterlab-lsp`][lsp] with two language servers pre-registered:
-
-- 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:
-
-  ```bash
-  npm install -g typescript-language-server typescript
-  ```
-
-  Restart JupyterLab afterwards to pick it up.
-
-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
-{
-  "LanguageServerManager": {
-    "language_servers": {
-      "bash-language-server": {
-        "version": 2,
-        "argv": ["bash-language-server", "start"],
-        "languages": ["bash", "sh"],
-        "mime_types": ["text/x-sh", "application/x-sh"],
-        "display_name": "bash-language-server"
-      }
-    }
-  }
-}
-```
-
-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` to override, hide, or add
-launcher entries. The editor shows xtralab's full built-in list as the default
-for both the agents and editors settings, so you can read every shipped entry
-and copy one into your user preferences to tweak in place. Both lists merge with
-xtralab's defaults by `id`, so an override only needs the `id` plus the fields
-you want to change.
-
-### Agents
-
-Edit the `agents` array:
-
-```jsonc
-{
-  "agents": [
-    // Hide an agent
-    { "id": "kiro", "enabled": false },
-
-    // Override an agent's command (e.g. point Claude at a shell alias)
-    { "id": "claude", "command": "cl", "requireAvailable": false },
-
-    // Add a new agent; promptArgs: [] appends the prompt as a positional arg
-    { "id": "aider", "label": "Aider", "command": "aider", "promptArgs": [] }
-  ]
-}
-```
-
-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
+desktop app architecture, and the documentation sources in [`docs/`](./docs).
 
 ## License
 

package/lib/agentSessions.d.ts

@@ -26,9 +26,13 @@ export interface IAgentSessions {
      * this ran).
      */
     get(sessionName: string): string | null;
-    /** Record that a session was launched as the given agent command. */
+    /**
+     * 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. */
+    /**
+     * 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

package/lib/askAgent/editorSelection.d.ts

@@ -0,0 +1,53 @@
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { EditorView } from '@codemirror/view';
+import type { Widget } from '@lumino/widgets';
+import type { IAskAgentRequest } from './tokens';
+/**
+ * A CodeMirror view a selection can be asked about, plus the context needed
+ * to describe it to an agent: the document path and, for notebooks, which
+ * cell the view belongs to.
+ */
+interface IEditorTarget {
+    view: EditorView;
+    path: string;
+    cell?: {
+        index: number;
+        type: string;
+    };
+}
+/**
+ * Resolve the CodeMirror view a selection in `widget` would live in, or
+ * `null` when the widget holds no such editor. Two widget shapes are
+ * recognized:
+ *
+ * - a notebook panel, where the active cell carries the editor and
+ *   `activeCellIndex` names its 0-based position in the nbformat `cells`
+ *   array. A rendered markdown cell keeps its (hidden) editor, but a
+ *   selection in the rendered HTML never passes {@link domSelectionInView},
+ *   so no pill appears there; and
+ * - a document widget whose content is a `FileEditor`. The wrapper is not
+ *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ *   not a core singleton, so another copy of the class could be in play.
+ *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ */
+export declare function resolveEditorTarget(widget: Widget | null): IEditorTarget | null;
+/**
+ * Whether the current DOM selection lives inside `view`. Guards the
+ * selection-change listener against selections made elsewhere (a terminal,
+ * a sidebar, another notebook cell) while the widget owning `view` happens
+ * to be the shell's current widget.
+ */
+export declare function domSelectionInView(view: EditorView, selection: Selection): boolean;
+/**
+ * Build an ask-agent request from the current selection in the shell's
+ * current widget — a file editor or the active notebook cell — or return
+ * `null` when that widget holds no CodeMirror document editor.
+ *
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line
+ * (used by the command/shortcut path so it works without a mouse
+ * selection); otherwise an empty selection yields `null`.
+ */
+export declare function editorAskRequest(app: JupyterFrontEnd, options?: {
+    allowEmpty?: boolean;
+}): IAskAgentRequest | null;
+export {};

package/lib/askAgent/editorSelection.js

@@ -0,0 +1,95 @@
+import { CodeMirrorEditor } from '@jupyterlab/codemirror';
+import { FileEditor } from '@jupyterlab/fileeditor';
+import { NotebookPanel } from '@jupyterlab/notebook';
+/**
+ * Resolve the CodeMirror view a selection in `widget` would live in, or
+ * `null` when the widget holds no such editor. Two widget shapes are
+ * recognized:
+ *
+ * - a notebook panel, where the active cell carries the editor and
+ *   `activeCellIndex` names its 0-based position in the nbformat `cells`
+ *   array. A rendered markdown cell keeps its (hidden) editor, but a
+ *   selection in the rendered HTML never passes {@link domSelectionInView},
+ *   so no pill appears there; and
+ * - a document widget whose content is a `FileEditor`. The wrapper is not
+ *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ *   not a core singleton, so another copy of the class could be in play.
+ *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ */
+export function resolveEditorTarget(widget) {
+    if (widget instanceof NotebookPanel) {
+        const cell = widget.content.activeCell;
+        if (cell !== null && cell.editor instanceof CodeMirrorEditor) {
+            return {
+                view: cell.editor.editor,
+                path: widget.context.path,
+                cell: { index: widget.content.activeCellIndex, type: cell.model.type }
+            };
+        }
+        return null;
+    }
+    const content = widget === null || widget === void 0 ? void 0 : widget.content;
+    if (content instanceof FileEditor &&
+        content.editor instanceof CodeMirrorEditor) {
+        return { view: content.editor.editor, path: content.context.path };
+    }
+    return null;
+}
+/**
+ * Whether the current DOM selection lives inside `view`. Guards the
+ * selection-change listener against selections made elsewhere (a terminal,
+ * a sidebar, another notebook cell) while the widget owning `view` happens
+ * to be the shell's current widget.
+ */
+export function domSelectionInView(view, selection) {
+    var _a;
+    const node = selection.anchorNode;
+    const element = node instanceof Element ? node : ((_a = node === null || node === void 0 ? void 0 : node.parentElement) !== null && _a !== void 0 ? _a : null);
+    return element !== null && view.dom.contains(element);
+}
+/**
+ * Build an ask-agent request from the current selection in the shell's
+ * current widget — a file editor or the active notebook cell — or return
+ * `null` when that widget holds no CodeMirror document editor.
+ *
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line
+ * (used by the command/shortcut path so it works without a mouse
+ * selection); otherwise an empty selection yields `null`.
+ */
+export function editorAskRequest(app, options = {}) {
+    const target = resolveEditorTarget(app.shell.currentWidget);
+    if (target === null) {
+        return null;
+    }
+    const { view, path, cell } = target;
+    const { state } = view;
+    const main = state.selection.main;
+    if (main.empty && options.allowEmpty !== true) {
+        return null;
+    }
+    const startLine = state.doc.lineAt(main.from).number;
+    let endLine;
+    let text;
+    if (main.empty) {
+        endLine = startLine;
+        text = state.doc.lineAt(main.from).text;
+    }
+    else {
+        // A selection that ends exactly at the start of a line (the common
+        // "drag over whole lines" gesture) should not count that line.
+        const endPos = main.to === state.doc.lineAt(main.to).from ? main.to - 1 : main.to;
+        endLine = state.doc.lineAt(endPos).number;
+        text = state.sliceDoc(main.from, main.to);
+    }
+    // Anchor the popup at the selection head (where the cursor ended up).
+    // `coordsAtPos` returns `null` for positions scrolled out of view.
+    const coords = view.coordsAtPos(main.head);
+    const anchor = coords
+        ? new DOMRect(coords.left, coords.top, Math.max(1, coords.right - coords.left), Math.max(1, coords.bottom - coords.top))
+        : null;
+    const context = { path, startLine, endLine, text };
+    if (cell !== undefined) {
+        context.cell = cell;
+    }
+    return { context, anchor };
+}

package/lib/askAgent/icons.d.ts

@@ -0,0 +1,7 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Four-point sparkle used by the ask-agent affordances (selection pill,
+ * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
+ * active theme recolor the glyph like other JupyterLab UI icons.
+ */
+export declare const askAgentIcon: LabIcon;

package/lib/askAgent/icons.js

@@ -0,0 +1,15 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Four-point sparkle used by the ask-agent affordances (selection pill,
+ * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
+ * active theme recolor the glyph like other JupyterLab UI icons.
+ */
+export const askAgentIcon = new LabIcon({
+    name: 'xtralab:ask-agent',
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
+  <g class="jp-icon3" fill="#616161">
+    <path d="M6 1l1 4 4 1-4 1-1 4-1-4-4-1 4-1 1-4z"/>
+    <path d="M12 9l.7 2.3L15 12l-2.3.7L12 15l-.7-2.3L9 12l2.3-.7L12 9z"/>
+  </g>
+</svg>`
+});

package/lib/askAgent/index.d.ts

@@ -0,0 +1,32 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { IAskAgent } from './tokens';
+/**
+ * Select code in a file editor (or pick diff lines) and prompt a coding
+ * agent about it.
+ *
+ * The plugin watches the document selection: a non-empty selection inside a
+ * CodeMirror file editor or notebook cell grows a small floating "Ask agent"
+ * pill next to the selection. Clicking it (or running `xtralab:ask-agent`,
+ * bound to Accel+. in editors and notebooks) opens a popup where the user
+ * types an instruction, picks one of the launcher's agents and picks where
+ * the prompt goes; submitting either starts that agent in a fresh terminal
+ * via `xtralab:start-agent:<id>`, or pastes the prompt into an agent already
+ * running in one of the open terminal sessions (via `IAgentTerminals`; the
+ * agent CLIs queue prompts that arrive while they are busy). Sends to a
+ * running agent stay in the background — focus never leaves the editor, and
+ * a success toast offers to open the terminal. Either way the prompt embeds
+ * the file path, cell index for notebooks, line range and selected snippet.
+ *
+ * The popup's Queue button (or Accel+Enter) defers the send instead: the
+ * comment lands in a persistent queue, stamped with the popup's selected
+ * destination — every queued prompt is independent and may aim at a
+ * different agent or session. A right-sidebar panel reviews the queue
+ * (edit, retarget, remove) and flushes it in one go, combining prompts that
+ * share a destination into a single numbered message. The queue survives
+ * page reloads.
+ *
+ * The same popup is provided on the `IAskAgent` token so the git diff
+ * viewers can open it for a selected diff line range.
+ */
+declare const plugin: JupyterFrontEndPlugin<IAskAgent>;
+export default plugin;