Code & text cells

Every code cell carries two views of the same thing: a code face with the Python, and a text face with a plain-language description of what it does. This guide is about using them. For why they exist, see Notebooks & cells.

Switching faces

A code cell shows one face at a time. The toggle is the Text / Code control in that cell's toolbar, and it applies to that cell alone — flipping one leaves every other cell on the face it was already showing. Only the active face is mounted, which keeps long notebooks fast, but both are saved and switching is instant. You can set which face new cells open to (the Default cell face) in Settings → Appearance.

Not two cells and not a comment above some code: one cell, turning around. The Text / Code control in its toolbar swaps which face is mounted, that cell alone flips, and the face you left behind is the one Clusy rewrites.

Generating one from the other

The faces aren't independent:

• Code to text. Write or accept some code and Clusy writes a short description for you (a note of up to about 70 words, in the language you set). This is the auto-generation path, and it's optional.
• Text to code. Write a description of what the cell should do and have the agent turn it into Python. Handy when you know the step but not the exact call.

Auto-generation is the Generate readable text toggle in Settings → Models. Switch it off and code cells stay code-only unless you ask for a description.

Sync status

Since a cell can be edited from either face, Clusy tracks whether they still agree, and marks a cell that's out of sync with an amber dot in the top-right corner of its code face. There's no matching green dot: when the faces agree, the dot is simply gone. The four statuses and the way out of each are in Notebooks & cells.

The short version: edit the text and the text face offers a Regenerate code button, which writes the code face from your words; edit the code and Clusy rewrites the description on its own, with no button to press. You're never forced to do either. A cell that's out of sync still runs, and sometimes you'll leave it that way on purpose.

The editors

The code face is a full editor with Python highlighting and autocomplete, and it saves as you type. The text face and markdown cells use a rich-text editor with a live preview rather than raw markup.

A habit worth keeping

Treat the text faces as the readable version of your notebook. When you hand it to someone, or come back to it in a month, reading the text faces top to bottom should tell the story, and you flip to code where the detail matters. Keeping them roughly in sync as you go costs little and pays off each time you revisit the work.