# Notebooks

> Source: https://parallelworks.com/docs/ai/code/notebooks

# Notebooks

`pw code` can pair with a Jupyter notebook (`.ipynb`), so the agent can read and edit its cells. Pair it with a running platform kernel as well, and the agent can run Python in that kernel, with the same variables and imports the notebook has loaded.

## Pairing a Notebook

Pass `--notebook` when you start `pw code`:

```bash
# A notebook on this machine
pw code --notebook analysis/eda.ipynb

# A notebook in your platform user workspace, from any machine
pw code --notebook workspace:analysis/eda.ipynb
```

- **A local path** must point to an existing `.ipynb` file.
- **`workspace:<path>`** names a notebook by its path in your platform user workspace. `pw code` reads and writes it through the platform, so this works from your laptop or a cluster alike. Only the paired notebook is reachable this way; other files in your user workspace are not.

## Running Code in the Kernel

Add `--kernel` with the name of a kernel running on the platform's **Notebooks** page:

```bash
pw code --notebook workspace:analysis/eda.ipynb --kernel my-kernel
```

The agent can then run Python in that kernel. Because the code shares the notebook's state, the agent can inspect a DataFrame the notebook already loaded, or try code before writing it into a cell. `--kernel` requires `--notebook`.

In `accept-edits` mode, each run asks first and shows the whole code it is about to run. See [Approval Prompts](/docs/ai/code/permissions#approval-prompts).

Each run waits up to 120 seconds by default. The agent can ask for up to 600 seconds; when the time runs out, the kernel is interrupted so the notebook stays usable. Code that calls `input()` cannot run, since there is no one to type an answer.

If the kernel cannot be reached, the agent is told to check that it is running on the Notebooks page.

## Notebook Tools

Pairing gives the agent these tools:

| Tool | What it does |
| --- | --- |
| `NotebookRead` | Lists every cell's ID, type, execution count, source, and text output. |
| `NotebookEdit` | Replaces a cell's source, inserts a new cell, or deletes a cell. Editing a code cell clears its outputs. |
| `NotebookRun` | Runs Python in the paired kernel and returns its output. Only with `--kernel`. |

## Permissions

The notebook tools follow the [permission mode](/docs/ai/code/permissions):

| Mode | `NotebookRead` | `NotebookEdit` | `NotebookRun` |
| --- | --- | --- | --- |
| `read-only` | Allowed | Denied | Denied |
| `plan` | Allowed | Denied | Denied |
| `accept-edits` | Allowed | Allowed | Asks first |
| `bypass-permissions` | Allowed | Allowed | Allowed |

An [allow rule](/docs/ai/code/permissions#allow-rules) such as `NotebookRun` pre-approves kernel runs in `accept-edits` mode.

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Running a Jupyter Notebook](/docs/run/sessions/interactive-sessions/jupyter-notebook): Jupyter sessions on the platform
- [pw code command reference](/docs/cli/pw/code): Full CLI reference