Code & text cells
Switching a code cell between its code and text faces, keeping them in sync, and generating one from the other.
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. Click to toggle. 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 agent-written cells open to in Settings → Models.
Generating one from the other
The faces aren't independent:
- Code to text. Write or accept some code and Clusy can write the description for you. This is the auto-generation path, and it's optional. When it's on, agent cells get a text face written for them, in the language you set.
- 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 a per-model toggle. 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:
| Status | Meaning |
|---|---|
synced | Code and text match |
text_ahead | The description changed, and the code hasn't |
code_ahead | The code changed, and the description hasn't |
diverged | Both changed separately |
When a cell is text-ahead, regenerate the code to match. When it's code-ahead, regenerate the text. You're never forced to. A divergence is just information, and sometimes you'll leave it 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.