A Notebook the Agent Can Edit — but Never Run

There’s a category error at the heart of most AI-plus-notebook workflows, and it burns both money and trust: the agent treats notebook code like script code.

A notebook isn’t a script. It’s a session. The dataframe you loaded twenty minutes ago, the model you fitted, the cleaning step you ran once and would rather not run again — that state lives in the kernel’s memory, not in the file. Which means an agent that “verifies” its notebook edit by running python file.py in a fresh process has proven exactly nothing: the fresh process can’t see your dataframes, so the test neither exercises your session nor could it. You paid for a verification theater performance.

Yee’s Python Space fixes this with an architecture and a contract. The architecture is a real notebook. The contract is one sentence: the agent edits cells; only the human runs them.

A Jupyter-quality notebook, zero Jupyter installed

Press ▶ on a Python repo and Yee opens a live notebook pane — no pip install jupyter, no lab server, no browser tab. What you get is the real thing, not a toy:

• A persistent kernel: variables, imports, and loaded data survive across cells for the whole session.
• Plots and pandas tables rendered inline.
• Real-notebook compatibility: %magics, !shell commands, display(), pickling of classes defined in cells, even top-level await — the long tail that makes or breaks “it just works.”
• Environment detection that finds your venv, conda, poetry, or pipenv setup — including when the app was launched from the Dock and inherited none of your shell’s environment, the classic macOS trap.
• Both formats: .ipynb and # %%-style .py files, edited on disk like any file.

That last point is the hinge. Because cells live on disk in standard formats, the agent can edit them with the same file tools it uses everywhere else — and the pane reloads edits automatically. No special notebook API for the model, no privileged execution path. Files in, files out.

The human-only execution contract

Here’s the note the agent actually receives, verbatim, whenever the kernel is live:

“The USER runs cells by hand — you cannot execute cells yourself. Do NOT run python file.py, python -c ..., or start a REPL to ‘test’ notebook code: a fresh process cannot see the kernel’s in-memory state (loaded dataframes, fitted models), so it proves nothing and wastes a turn. Edit the notebook file like any file… then tell the user in one short sentence which cell to re-run.”

Notice what this is not: a safety theater rule. It’s an epistemics rule. The agent is barred from executing cells because execution against the wrong state produces confident nonsense — the most expensive kind. The human holds the run button because the human is the only party who knows what the session state means. Twenty minutes into an analysis, “re-run cell 4” is a judgment call about your afternoon, not a tool call.

When something does break, the loop stays human-gated the way all of Yee’s fix loops are: a cell error ships its source and traceback to the agent through the ⚠ fix button — when you click it. The agent gets exactly the failing cell’s reality, you get a proposed edit, and the kernel state sits untouched until you decide.

Division of labor is the feature

Strip it down and the design is one sentence long: the model is good at code, the kernel is good at state, and the human is the only one who knows what the state means. Most agent-notebook integrations blur those roles and get the worst of each — agents re-running expensive cells to “check,” sessions clobbered mid-analysis, verification that verifies nothing.

Keeping the roles separate is why this earns its place in our publicly graded support ladder as Python’s headline feature — and why the grade sits at A rather than higher: by house rule, no tier climbs without a measured bench behind it. The notebook shipped; its eval scenario is the gate it still has to walk through. Same standard as every number we publish.

If your team lives in notebooks and wants the AI loop without surrendering the session — that’s the exact seat Yee built the Python Space for.