Jupyter Agent Runner

Project-centered AI coding assistance inside JupyterLab.

Jupyter Agent Runner adds a Project Center and persistent Chatrooms to JupyterLab 4. Open a workspace, talk to the built-in Pi Manager, attach files, and keep each project's conversation and activity separate.

Not sure what to do next? Ask the Manager in Chatroom.

Highlights

• Works without VS Code. The package includes its own Pi coding-agent runtime and starts it automatically with JupyterLab.
• Project-bound Chatrooms. Every conversation belongs to one workspace, so messages and replies from different projects do not get mixed together.
• Persistent history. Conversations survive JupyterLab and browser restarts.
• Built-in project context. The Manager receives the selected project directory and can inspect or modify files there when asked.
• File attachments. Attach a file and reference it from your prompt without exposing the Agent Runner data directory to the browser.
• Compatible with Agent Runner for VS Code. Both interfaces use the same projects, Manager session, authentication, and Chatroom history when they run as the same operating-system user.

Requirements

• Python 3.11 or newer
• JupyterLab 4.4 or newer
• Node.js 22.19 or newer for the bundled Pi runtime
• An OpenAI Codex account for the built-in Manager

You do not need a global Pi installation or the Agent Runner VS Code extension.

Install

Install the package in the same Python environment as JupyterLab:

pip install jupyter-agent-runner

Then start or restart JupyterLab:

jupyter lab

The Python package includes both the JupyterLab frontend and its authenticated Jupyter Server extension. No separate npm installation is required.

First Run

1. Open the Agent Runner icon in JupyterLab's left sidebar.
2. Choose townhall for general conversation, or open the project created for your Jupyter Server root directory.
3. Open that project's Chatroom.
4. If prompted, click Sign in to Pi, open the displayed sign-in page, and enter the device code.
5. Ask the Manager to explain the workspace, inspect a notebook, fix code, add tests, or implement a change.

For example:

Review this project and explain how its main components fit together.

Find why the current tests fail, fix the issue, and summarize the change.

Create a notebook that explores the CSV file I attached.

In the composer, Enter adds a line break and Shift+Enter sends the message.

Project Center

The Project Center is the entry point for your Agent Runner workspace:

• TOWNHALL is the default space for general coordination and work that is not tied to a repository.
• PROJECTS lists known work directories. Selecting one opens or reveals its persistent Chatroom in JupyterLab's main area.
• AGENTS shows the built-in Manager and any Agent Runner agents already present in the shared workspace.
• ISSUES summarizes the selected project's current and completed work.
• AGENDA summarizes scheduled and recently dispatched tasks when that state exists.

Each project has its own workdir and stable project identity. Live replies and stored history are filtered to that project before they appear in its Chatroom.

Using Chatroom

Unaddressed messages go to the built-in Manager. The Manager runs as a long-lived Pi coding session and continues its most recent session after a restart.

Messages go to the built-in Manager by default. Agent Runner routing mentions such as @manager, @agent, or @channel remain available when connected to a full Agent Runner backend.

Attached files are stored as Agent Runner resources and inserted into the composer as #filename references. The browser communicates only with the authenticated Jupyter Server; it never reads ~/.agent-runner directly.

Standalone and Shared Use

Jupyter Agent Runner can run by itself. When no Agent Runner backend is active, JupyterLab starts the bundled backend and Pi Manager.

If Agent Runner for VS Code is already running for the same user, the JupyterLab package reuses that healthy backend instead of starting a competing owner. The two products have different browser-facing WebSocket connections, but share the durable Agent Runner state and Manager session.

Data Location

Agent Runner keeps local state under:

~/.agent-runner

This includes project descriptors, project-scoped Chatroom history, uploaded resources, Agent Runner status, and the resumable Manager session. Pi credentials are stored separately under ~/.pi/agent/.

Troubleshooting

If Agent Runner does not appear after installation, confirm that the package is installed in the environment used to launch JupyterLab, then restart the Jupyter Server:

python -m pip show jupyter-agent-runner
jupyter server extension list
jupyter labextension list

If the built-in Manager cannot start, check node --version. Node.js 22.19 or newer is required. If sending is unavailable, open a Chatroom and complete the Sign in to Pi flow.

Development

Contributor setup, architecture, contracts, and build commands are documented in JUPYTERLAB.md.