Projects & sessions

Two words come up a lot: project and session. They're easy to confuse early on, so here's the difference.

Projects

A project is one body of work. It holds your notebooks, the files in the workspace, the branches of each notebook, and your sessions. Think of it like a repo or a folder: one analysis, one model, one investigation. "Q3 churn," "receipt classifier," "clean the pricing data."

When you sign in, the dashboard shows your recent projects so you can pick up where you left off. Once you have more than a handful, a search box and sort options (last updated, name, creation date, session count) appear, and you can flip between a grid and a list. Each project also has a default runtime. New projects start on CPU, and you can change that.

Sessions

A session is a single conversation with the agent inside a project, and you can have several. You might keep one session for cleaning, another for feature work, another for modeling, each with its own chat history. They all see the same notebooks and files. What's separate is the conversation.

Sessions live under the Chats tab in the sidebar, where you can rename them inline. Starting a new one (⌘N, or from the chat header) gives you a fresh conversation without losing the old one, and ⌘K searches your sessions across every project.

Why bother splitting them up? Long chats drift. Keeping each line of work in its own session keeps the agent focused on the task in front of it, and makes it easier to come back to a specific thread later.

How they fit

The project owns the notebooks, the files in the workspace, the branches of each notebook, and the branch you're currently on. There is one of each, and every session in the project looks at that same one. Edit a notebook in one session and the change is already there in the other, because there's only one notebook. Switch to a different branch and every session in the project follows you, because the active branch is a property of the project, not of your conversation.

The session owns exactly one thing: the chat. Your messages, the agent's replies, the cards from its work. That's what's separate, and that's all that's separate.

So a project called "Churn analysis" might hold three sessions — "Cleaning," "Features," "Model" — with three independent conversations, all reading and writing the same notebooks, the same files, and the same branches.

Notebooks, files, branches — and the branch you're on — belong to the project: one copy, so an edit made in one session is already there in the others. The chat is the only thing a session keeps to itself.

Naming and deleting

Projects are named when you create them, and Clusy tidies up auto-generated names on its own as the work takes shape. You can delete a project from the dashboard; deleting removes its notebooks, branches, files, and sessions for good, so it asks you to confirm first.