Branches

A Clusy branch is not a Git branch. It's an experiment branch inside a notebook, and the thing that makes it useful is that forking keeps your kernel state.

One notebook, forked at the last shared cell: three arms run side by side on their own kernels, and come back as a single comparison.

The problem it solves

You're partway through a notebook. You've loaded some data, cleaned it, built features, a chunk of compute now sitting in memory. Now you want to compare two models. In a plain notebook you'd duplicate a pile of cells and hope they don't drift, or comment things in and out and lose track of which result came from which setup.

Branching handles this. You fork from the cell where the two ideas split. Clusy checkpoints the kernel at that point (your loaded data, cleaned frames, fitted objects) and the new branch starts from there. You don't recompute anything, and the original branch is untouched.

How a fork works

Hover the gap under the cell where your approaches diverge. The insert strip appears, and next to Code and Markdown there's a Fork button. That forks at that cell.

What happens then: Clusy checkpoints the parent kernel's namespace, creates a fresh kernel for the new branch, and restores the checkpoint into it. None of the cells above the fork are executed a second time, so df, X_train and anything else you'd already computed are simply there when the branch opens. The new branch starts with no cells of its own; the first one you write can use that state right away. The original branch keeps running on its own kernel and doesn't notice.

Forking checkpoints the kernel and hands it to the new branch: everything the cells above the fork left in memory is already there, so not one of them runs a second time.

What a fork doesn't carry

Forking is cheap, but it isn't magic, and it's better to know the edges before you hit them.

• Unpicklable objects don't survive. The checkpoint is a dill dump of the namespace. Anything dill can't serialize is left out of it: open file handles, live database connections, CUDA and other device contexts, an np.load handle you never closed, some OpenCV and Torch internals. The rest of the namespace still makes it across; those specific names just won't exist on the new branch. Re-create them in the branch's first cell.
• Big namespaces are refused. A checkpoint over 256 MB is not carried across. That's a lot of loose arrays in memory, but a few large dataframes plus a big model will get there.
• When the fork fails, the branch still gets created — with an empty kernel. Clusy does not silently pretend it worked. The agent tells you the fork degraded and that the branch has none of the parent's variables, so you re-run the setup rather than hitting NameError. In a batch experiment, a variant that started without inherited state is flagged in the comparison card.

If a branch needs something heavy and unpicklable, load it inside the branch rather than upstream of the fork.

Where branches show up

Once you've branched, the notebook isn't a straight list anymore: branches share their early cells and then diverge. The canvas still shows you one thread at a time, which is the readable thing to do.

• The notebook renders the active branch, top to bottom.
• At the cell a fork was cut from, a fork selector appears inline: a pill for each fork off that cell, plus a + to cut another. Click a pill to follow that fork.
• The branch control at the top right of the canvas shows the active branch and the branch count, and switches branches from anywhere in the notebook.

There is no separate tree or map view. The branch graph is a concept you hold in your head (and see in these diagrams); the UI navigates it one thread at a time.

Branch status

Each branch carries a status so you can keep track of it:

running and error are transient: they describe what the branch is doing, and they clear. active, dormant and completed are how you file it.

You can also delete a branch outright. Since that discards its cells and any convergence links, Clusy asks you to confirm first; setting a dead end to dormant is the gentler option when you want to keep the record.

Batch experiments

You don't have to fork by hand one branch at a time. Ask the agent to compare several variants ("try learning rates 0.1, 0.01, and 0.001") and it can run a batch experiment: it forks a branch per variant from the same checkpoint, runs them, and reports back in chat with a comparison table and a chip for each branch, so you can jump straight to any of them.

Read that table carefully:

• The quickest clean run gets a neutral Fastest badge. That's a stopwatch, not a verdict. In an accuracy sweep the fastest arm is usually the worst model, because it's the one with the fewest epochs or the smallest config.
• A variant that failed never carries the badge; it keeps its error dot.
• A variant that ran without inherited state is flagged, because its numbers aren't comparable to the others.

Nothing in the card decides which variant won. Reading the result is still your job.

Bringing branches back together

When you've decided which approach won, you converge. Ask the agent to converge the branches; the cell they rejoin gets a bar across the top showing how many variants feed it, a chip per variant, and the mode.

Three ways to bring branches back together, on the same graph: Winner carries one branch's state past the join into the cells below, Comparison holds both at the join and carries nothing on, and Manual lets you take a piece of each.

There are three modes, and the difference is what reaches the cells below the join:

• Winner carries one branch's kernel state past the join, so the next cell runs against it. The other branches stop where they are; they aren't deleted.
• Comparison keeps the branches side by side at the join and carries nothing forward. Use it when the comparison itself is the deliverable, or when you haven't decided.
• Manual lets you take pieces from each and stitch them together on the way down.

You can switch mode, or pick which variant feeds the cell, from that bar on the converged cell. A convergence point is where branches that split earlier rejoin into one downstream cell, a diamond in the graph. It's how you branch at cell 3 and come back together at cell 8.

The Branching experiments guide walks through a full comparison, with code.