Notebooks & cells

The notebook is where the work lives. If you know Jupyter, the basics carry over: a notebook is an ordered list of cells, code cells share a Python kernel, and output shows up underneath. Clusy notebooks are .ipynb-compatible: import one from the + menu on the canvas (or drop an .ipynb file into the file manager), and export the current branch as .ipynb from the same menu.

That + menu is the notebook's utility drawer. Alongside import and export it creates notebooks and cells, jumps to your plans and files, and holds shortcuts for publishing to Hugging Face and Kaggle:

The + menu on the canvas: create or import a notebook, export .ipynb, publish to Hugging Face or Kaggle, add cells, and open plans or files

A couple of things work differently.

Cell types

Not every cell is Python. You'll run into a few kinds:

• Code cells: Python that runs in the kernel.
• Markdown cells: formatted notes, written in a rich editor with a live preview.
• Agent insight cells: short notes the agent drops in to flag something worth your attention.
• Control cells: small inputs the agent uses to ask you for a value or a choice, inline in the notebook.

That's the whole list. Rich output — HTML, SVG, custom displays — is a property of what a code cell returns, not a cell type of its own; Reading output covers it.

Code cells have two faces

Every code cell holds two views of the same thing: a code face with the Python, and a text face with a plain-language description of what the cell does. You can read or edit either one, and switch between them with a click.

The two stay linked, and the cell shows you whether they still agree:

There's one move back from each. When a cell is text-ahead, the code face offers a Regenerate code button: press it and Clusy rewrites the Python to match your description. When it's code-ahead, Clusy rewrites the description for you, with no button to press. Either way the cell returns to synced.

diverged is the odd one out. It's a value the API accepts, but nothing in the app sets it: editing the other face doesn't fuse the two states, it moves the flag across. In practice a cell is synced, text_ahead, or code_ahead, and never both at once.

Two faces, two ways to drift, and one move back from each: regenerate the code when the text is ahead, and let Clusy rewrite the text when the code is ahead. Nothing in the app actually reaches diverged — edit the other face and the flag just moves across.

You decide how much of this you want. Auto-writing the text description is optional: the Generate readable text toggle in Settings → Models turns it on or off, and you can set the language it's written in. Turn it off and code cells behave like ordinary code cells. The Code & text cells guide goes deeper.

The kernel

Code cells share a running kernel, so a variable from one cell is available in the next. Running cells out of order works like it does in Jupyter, with the same gotcha: the kernel remembers what you last ran, not what's written above. Clusy doesn't flag that for you — there's no "stale" marker on a cell — so if a result looks out of date, re-run it.

A cell's execution status shows as a colored left border, and the border is the whole signal. There are five states:

Ghost cells

When the agent proposes a cell but hasn't committed it, it shows up as a ghost: a dashed, half-faded cell you can accept, edit, or dismiss. Accept and it solidifies into an ordinary idle cell. Dismiss and it disappears. Nothing the agent writes lands in your notebook before you've seen it this way.

Cell state lives in the left border: it breathes while the cell runs, clears itself about two seconds after a clean finish, and stays put — over a tinted traceback — when the cell raises. Cells the agent proposes arrive dashed and half-there, and only solidify once you accept them.

Output

Cells render output richly: DataFrames as tables, Plotly charts inline, images, progress bars for long loops and training runs, and readable tracebacks when something fails. Reading output covers each kind.

Working with cells

A code cell carries a toolbar along its top edge: a grip to drag the cell to a new position, a toggle between the code and text faces, run (which becomes stop while it's executing), and delete. A cell that produces a model gets a Publish button too, for pushing it to Hugging Face. Markdown cells don't have the toolbar; you edit them in place.

Adding cells happens somewhere else. Hover the gap between two cells and a thin row fades in with + Code, + Markdown, and Fork. That gap is also the answer to "where do I fork from a cell?" — the Fork button there starts a branch from that point in the notebook. Once a cell has forks, the gap below it is taken over by the fork selector, which has its own + for adding another branch.

The notebook is virtualized, so only the cells near your view are mounted and a long notebook stays responsive.