jupyterlab_claude_code_extension 1.0.16

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stellars Henson
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,51 @@
+# jupyterlab_claude_code_extension
+
+[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_claude_code_extension/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_claude_code_extension/actions/workflows/build.yml)
+[![npm version](https://img.shields.io/npm/v/jupyterlab_claude_code_extension.svg)](https://www.npmjs.com/package/jupyterlab_claude_code_extension)
+[![PyPI version](https://img.shields.io/pypi/v/jupyterlab_claude_code_extension.svg)](https://pypi.org/project/jupyterlab_claude_code_extension/)
+[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab_claude_code_extension)](https://pepy.tech/project/jupyterlab_claude_code_extension)
+[![JupyterLab 4](https://img.shields.io/badge/JupyterLab-4-orange.svg)](https://jupyterlab.readthedocs.io/en/stable/)
+[![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
+[![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
+
+Manage Claude Code CLI sessions from inside JupyterLab. A left-sidebar panel lists every project under `~/.claude/projects/` deduplicated to one row per folder, marks live remote-control sessions with a green dot, and lets you jump back into any session by opening (or reactivating) a terminal pwd'd to that project and auto-running `claude --resume <id>`.
+
+![Claude Code Sessions panel](.resources/screenshot.png)
+
+## Features
+
+- **Three-section side panel** - Favourites, Recent (top 10 by activity), and All. Each section scrolls independently; Favourites disappears when empty
+- **Live remote-control indicator** - green dot on rows whose `~/.claude/sessions/<pid>.json` is alive (verified via `os.kill(pid, 0)`)
+- **One-click resume** - click a row to find an existing terminal pwd'd to that project (queried server-side from the pty's process tree) and reactivate its tab; only spawns a fresh terminal if none matches. Concurrent rapid clicks are coalesced
+- **Smart name resolution** - shows the user-set `/rename` name when available; auto-detected names (volatile across the same `sessionId` or 3+ token lowercase-kebab) fall back to the folder basename. Toggle the behaviour via the `resolveSessionNames` setting
+- **Path-segment disambiguation** - when two sessions share the same display name, the row reveals the minimum number of trailing path segments needed for each to be unique
+- **Favourites** - star a session via the right-click menu; persisted server-side at `~/.claude/jupyterlab_claude_code_extension.json`
+- **Layout restorer** - panel visibility persists across JupyterLab reloads
+- **Auto-disabled** when the `claude` binary is not on `PATH`
+- **Hover tooltip** with relative path (vs JL root), last activity, message count, branch, first prompt, session id
+
+## Requirements
+
+- JupyterLab >= 4.0.0
+- Python >= 3.10
+- `claude` CLI on `PATH`
+
+## Install
+
+Developers must install via the project `Makefile` (which orchestrates clean, build, and pip install of the resulting wheel):
+
+```bash
+make install
+```
+
+End-users can install the published package from PyPI:
+
+```bash
+pip install jupyterlab_claude_code_extension
+```
+
+## Uninstall
+
+```bash
+pip uninstall jupyterlab_claude_code_extension
+```

package/lib/icons.d.ts

@@ -0,0 +1,5 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+export declare const claudeIcon: LabIcon;
+export declare const starFilledIcon: LabIcon;
+export declare const refreshIcon: LabIcon;
+export declare const removeIcon: LabIcon;

package/lib/icons.js

@@ -0,0 +1,44 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+const claudeSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <g class="jp-icon3" fill="#616161">
+    <path d="m14.375 6.48.49.28v.209l-.14.489-5.937 1.397-.558-1.387zm0 0"/>
+    <path d="m12.155 2.373.683.143.182.224.173.535-.072.342-3.983 5.447L7.81 7.737l3.673-4.82z"/>
+    <path d="m8.719 1.522.419-.28.349.14.349.49-.957 5.748-.65-.441-.279-.769.49-4.33z"/>
+    <path d="m4.239 1.614.43-.55L4.95 1l.558.081.275.216 2.004 4.442.724 2.11-.848.471-3.231-5.864z"/>
+    <path d="m2.154 4.665-.14-.56.42-.488.488.07h.14l2.933 2.165.908.698 1.257.978-.698 1.187-.629-.489-.419-.419-4.05-2.863z"/>
+    <path d="M1.316 8.296 1 7.946v-.31l.316-.108 3.562.21 3.491.279-.113.695-6.66-.346z"/>
+    <path d="M3.411 11.931h-.698l-.278-.32v-.382l1.186-.838 4.82-3.068.487.833z"/>
+    <path d="m4.738 13.883-.28.07-.418-.21.07-.35 4.12-5.446.558.768-3.072 4.05z"/>
+    <path d="m8.23 14.581-.21.28-.419.14-.349-.28-.21-.42L8.09 8.646l.629.07z"/>
+    <path d="M11.791 13.045v.558l-.07.21-.279.14-.489-.066-3.356-4.996 1.331-1.014 1.117 2.025.105.733z"/>
+    <path d="m13.398 12.207.07.349-.21.279-.21-.07-1.187-.838-1.815-1.606-1.397-.978.419-1.326.698.419.42.768z"/>
+    <path d="m12.49 8.645 1.746.14.419.28.279.418v.302l-.768.327-3.911-.978-1.606-.07.419-1.466 1.117.838z"/>
+  </g>
+</svg>`;
+export const claudeIcon = new LabIcon({
+    name: 'jupyterlab_claude_code_extension:claude',
+    svgstr: claudeSvgStr
+});
+const starFilledSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M12 2.5l2.9 6.4 7 .7-5.3 4.7 1.6 6.9L12 17.7l-6.2 3.5 1.6-6.9-5.3-4.7 7-.7z"/>
+</svg>`;
+export const starFilledIcon = new LabIcon({
+    name: 'jupyterlab_claude_code_extension:star-filled',
+    svgstr: starFilledSvgStr
+});
+// Material-style icons matched verbatim to jupyterlab_trash_mgmt_extension so
+// header/menu icons render at identical size and theme.
+const refreshSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"/>
+</svg>`;
+export const refreshIcon = new LabIcon({
+    name: 'jupyterlab_claude_code_extension:refresh',
+    svgstr: refreshSvgStr
+});
+const removeSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM8 9h8v10H8V9zm7.5-5l-1-1h-5l-1 1H5v2h14V4h-3.5z"/>
+</svg>`;
+export const removeIcon = new LabIcon({
+    name: 'jupyterlab_claude_code_extension:remove',
+    svgstr: removeSvgStr
+});

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/index.js

@@ -0,0 +1,57 @@
+import { ILabShell, ILayoutRestorer } from '@jupyterlab/application';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { requestAPI } from './request';
+import { ClaudeCodeSessionsWidget } from './widget';
+const PLUGIN_ID = 'jupyterlab_claude_code_extension:plugin';
+const WIDGET_ID = 'jupyterlab-claude-code-extension';
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Side panel listing Claude Code sessions per project folder, with remote-control indicator, favourites, and one-click resume in a terminal.',
+    autoStart: true,
+    requires: [ILabShell],
+    optional: [ILayoutRestorer, ISettingRegistry, ITerminalTracker],
+    activate: async (app, labShell, restorer, settingRegistry, terminalTracker) => {
+        const settings = app.serviceManager.serverSettings;
+        let status;
+        try {
+            status = await requestAPI('status', settings);
+        }
+        catch (err) {
+            console.error('[jupyterlab_claude_code_extension] status check failed; panel will not be registered.', err);
+            return;
+        }
+        if (!status.enabled) {
+            console.info('[jupyterlab_claude_code_extension] `claude` binary not found on PATH; panel disabled.');
+            return;
+        }
+        const widget = new ClaudeCodeSessionsWidget(app, status.root_dir || '', terminalTracker);
+        labShell.add(widget, 'left', { rank: 600 });
+        if (settingRegistry) {
+            try {
+                const settings = await settingRegistry.load(PLUGIN_ID);
+                const apply = () => {
+                    const resolve = settings.get('resolveSessionNames')
+                        .composite;
+                    widget.setResolveSessionNames(resolve !== false);
+                };
+                apply();
+                settings.changed.connect(apply);
+            }
+            catch (err) {
+                console.warn('[jupyterlab_claude_code_extension] failed to load settings; using defaults', err);
+            }
+        }
+        // Register with the layout restorer so JL remembers whether the panel
+        // was active/visible across browser reloads and restarts.
+        if (restorer) {
+            restorer.add(widget, WIDGET_ID);
+        }
+        app.commands.addCommand('claude-code-sessions:refresh', {
+            label: 'Refresh Claude Code Sessions',
+            execute: () => widget.refresh()
+        });
+        console.log('[jupyterlab_claude_code_extension] panel registered (claude:', status.claude_path, ')');
+    }
+};
+export default plugin;

package/lib/request.d.ts

@@ -0,0 +1,10 @@
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Call the server extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param serverSettings The server settings to use for the request
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export declare function requestAPI<T>(endPoint: string, serverSettings: ServerConnection.ISettings, init?: RequestInit): Promise<T>;

package/lib/request.js

@@ -0,0 +1,35 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Call the server extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param serverSettings The server settings to use for the request
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export async function requestAPI(endPoint, serverSettings, init = {}) {
+    // Make request to Jupyter API
+    const requestUrl = URLExt.join(serverSettings.baseUrl, 'jupyterlab-claude-code-extension', // our server extension's API namespace
+    endPoint);
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(requestUrl, init, serverSettings);
+    }
+    catch (error) {
+        throw new ServerConnection.NetworkError(error);
+    }
+    let data = await response.text();
+    if (data.length > 0) {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (error) {
+            console.log('Not a JSON response body.', response);
+        }
+    }
+    if (!response.ok) {
+        throw new ServerConnection.ResponseError(response, data.message || data);
+    }
+    return data;
+}

package/lib/types.d.ts

@@ -0,0 +1,36 @@
+export interface ISession {
+    project_path: string;
+    encoded_path: string;
+    session_id: string;
+    name: string;
+    summary: string;
+    first_prompt: string;
+    message_count: number;
+    created: string | null;
+    modified: string | null;
+    file_mtime: number;
+    git_branch: string | null;
+    remote_control: boolean;
+    favourite: boolean;
+}
+export interface ISessionsListResponse {
+    sessions: ISession[];
+}
+export interface IStatusResponse {
+    enabled: boolean;
+    claude_path: string | null;
+    root_dir: string;
+}
+export interface IFavouriteRequest {
+    project_path: string;
+    favourite: boolean;
+}
+export interface IFavouriteResponse {
+    favourites: string[];
+}
+export interface IRemoveRequest {
+    encoded_path: string;
+}
+export interface IRemoveResponse {
+    removed: string;
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/widget.d.ts

@@ -0,0 +1,60 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { Widget } from '@lumino/widgets';
+import { Message } from '@lumino/messaging';
+export declare class ClaudeCodeSessionsWidget extends Widget {
+    constructor(app: JupyterFrontEnd, rootDir: string, terminalTracker?: ITerminalTracker | null);
+    refresh(): void;
+    /** Toggle whether explicit ``/rename`` names are honoured. */
+    setResolveSessionNames(on: boolean): void;
+    protected onAfterShow(_msg: Message): void;
+    protected onBeforeHide(_msg: Message): void;
+    protected onCloseRequest(msg: Message): void;
+    private _buildShell;
+    private _showLoading;
+    private _showError;
+    private _fetch;
+    private _toggleFavourite;
+    private _remove;
+    private _resumeInTerminal;
+    private _doResumeInTerminal;
+    private _shellQuote;
+    private _findTerminalForCwd;
+    private _wireTerminalDisposal;
+    /** Apply the resolve-names setting + path-segment disambiguation. */
+    private _displayName;
+    private _basename;
+    /** Walk path tails until every name in a colliding group is unique. */
+    private _disambiguate;
+    private _render;
+    private _renderSection;
+    private _renderRow;
+    private _lookupName;
+    private _buildRowTooltip;
+    private _displayPath;
+    private _formatRelativeTime;
+    private _setRefreshSpinning;
+    private _setActiveRow;
+    private _setupContextMenu;
+    private _startPolling;
+    private _stopPolling;
+    private readonly _app;
+    private readonly _serverSettings;
+    private _bodyEl;
+    private _statusEl;
+    private _refreshBtn;
+    private _sessions;
+    private _expanded;
+    private _commands;
+    private _contextMenu;
+    private _activeSession;
+    private _activeRowEl;
+    private _pollHandle;
+    private readonly _removingPaths;
+    private readonly _terminalTracker;
+    private readonly _terminalsByPath;
+    private readonly _pendingByPath;
+    private readonly _rootDir;
+    private _resolveNames;
+    private _displayNames;
+}