Floors

Floors let you work on isolated branches without leaving your workspace. Each floor is a full copy of your repository that shares storage with the original — thanks to APFS (Apple Filesystem) copy-on-write, creating a floor is very fast and uses almost no extra disk space.

Why Floors?

When you're deep in a task and need to context-switch — maybe to fix a bug on another branch, review a PR, or try an experimental approach — you'd normally have to stash your work, switch branches, and later remember where you left off.

Floors eliminate this friction. Create a new floor, and you get a completely isolated environment with its own terminal, branch, and working tree. Your original workspace stays exactly as you left it.

Creating a floor

1. Click the floor button in the bottom-right corner of the app, next to the minimap.
2. The canvas repositions into a 3D space — click the new floor button.
3. Give it a name (e.g., "Fix login bug").
4. If you have a git repository initialized, choose to create a new branch or use an existing one.
5. Click Create.

Maestri clones your repository instantly and checks out the floor's branch. Any terminals you add in the new floor work in this isolated environment — you can even run simultaneous dev servers, IDEs, and build commands without conflicts.

Working in a floor

Each floor is a real git repository. You can:

• Make commits, create branches, run tests
• Open multiple terminals in the same floor
• See file changes and diff stats in the floor's panel
• Check for merge conflicts before landing

The floor's branch is mirrored in your original repository, so other tools (GitHub, your IDE) can see it too.

Landing a floor

When your work is ready, it's time to land. Make sure all changes are committed (no dirty working tree), then click Land in the floor's panel.

The landing UI shows your floor's branch on the left and the target branch (ground floor) on the right, with an airplane icon representing the transfer of commits.

Select which branch to land into:

• Same branch as the floor — Maestri transfers commits directly to the original repository.
• Different branch — Maestri performs a merge as well (if no conflicts are found).

After selecting, you'll see a merge preview with diff stats and any potential conflicts.

Click Merge to complete the landing. Maestri fetches your floor's commits into the original repository and merges them into the target branch.

Deleting a floor

Click the x on a floor to delete it. You can choose to:

• Keep the branch — the branch stays in your repository for later use
• Delete the branch — removes both the floor and its branch

The cloned directory is always removed, freeing up any disk space used by divergent files.

Requirements

Floors require two things to work:

• APFS volume — Floors use copy-on-write cloning, which only works on APFS (the default on modern Macs).
• Git repository — Your workspace must be a git repo.

How it works

Under the hood, floors use instant APFS cloning. The clone shares all unchanged files with the original — only modified files take up additional space.

When you land a floor, Maestri uses git fetch to pull commits from the clone back to your original repository, then merges using git plumbing commands to avoid disrupting your working tree.

Floors are stored in a .maestri/floors directory next to your project. This directory is automatically cleaned up when you delete the last floor.