Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/javierpr0/Notchly/llms.txt

Use this file to discover all available pages before exploring further.

Notchly ships two git-aware features designed to make long Claude Code sessions safer: checkpoints let you snapshot your working tree before handing control to Claude, and worktrees let you spin up fully isolated copies of a repository so multiple Claude sessions can work the same project simultaneously without stepping on each other.

​
Checkpoints

Checkpoints are lightweight git snapshots stored as custom refs under refs/Notchy-snapshots/. They are not commits on your branch — they are detached saves you can restore at any time without affecting your commit history, branch pointers, or staged changes. Internally, Notchly creates a temporary index file (in a 0700-permissions directory to prevent symlink attacks), stages all working tree files into it with git add -A, then writes a tree object and a commit via git write-tree and git commit-tree. The resulting commit hash is stored under refs/Notchy-snapshots/<project>/<timestamp>. Your real staging area is never touched.

​
Saving a checkpoint

Press Cmd+S while in a tab whose working directory is inside a git repository. Notchly creates the snapshot immediately. A brief “Saving checkpoint…” status appears in the panel header while the operation runs off the main thread. You can also save from the menu bar icon: click the icon → Checkpoint → Save → select a session.

​
Restoring a checkpoint

1

Open the menu bar icon

Click the Notchly menu bar icon.
2

Navigate to Restore From

Hover over Checkpoint → Restore From to see eligible sessions.
3

Select a session

Click a session name. Notchly lists available checkpoints for that session (newest first, labeled with date and time).
4

Confirm

Notchly shows a confirmation dialog before applying the restore. Click Restore to proceed.
Before restoring, Notchly automatically takes a before-restore safety snapshot of the current state so you have a fallback if the restore is not what you wanted. This snapshot is best-effort — if it fails, the restore still proceeds.
Restoring a checkpoint resets your working tree by running git checkout <commit> -- .. Any uncommitted changes that were not captured in the checkpoint will be overwritten. Make sure to save a checkpoint or stash your work before restoring.

​
Listing checkpoints

The menu bar icon shows all available checkpoints per session under Checkpoint → Restore From. Only sessions with a project path inside a git repository appear in this list. Each checkpoint is labeled with the save date and time (e.g., “Mon 7 Jul 2:34pm”).

​
Git binary resolution

Notchly resolves the git binary in this order:
  1. Each directory in your shell’s $PATH (so asdf, mise, and Homebrew shims are honored)
  2. /opt/homebrew/bin/git
  3. /usr/local/bin/git
  4. /usr/bin/git
This means checkpoint operations use the same git version your shell would use, including any version managers you have configured.

​
Requirements

The working directory of the tab must be inside a git repository (git rev-parse --git-dir must succeed). Checkpoints are not available for non-git directories and the menu items are disabled in that case.

​
Worktrees

Git worktrees allow the same repository to be checked out into multiple directories at the same time, each on its own branch. Notchly automates worktree creation so you can give each Claude session an entirely isolated copy of the repo — separate working tree, separate branch, no shared modified files.

​
Creating a worktree

Right-click any project tab → Open in Worktree. Notchly performs these steps automatically:
1

Find the repo root

Resolves the git repository root of the tab’s working directory using git rev-parse --show-toplevel.
2

Create a branch

Creates a new branch named notchly/<tab-name>-<6hex> from the current HEAD (for example, notchly/myapp-a3f9c2).
3

Check out a worktree

Runs git worktree add <path> -b <branch> to check out the branch into ~/.notchly/worktrees/<repo-name>/<name>-<6hex>.
4

Open a new tab

The worktree directory is opened as a new tab immediately to the right of the original. The tab becomes active.

​
Visual indicator

Worktree tabs show a branch badge icon (⎇) next to the tab name. Hover over the badge to see the full branch name in a tooltip.

​
Closing a worktree tab

Closing a worktree tab opens a dialog with three choices:
  • Discard Worktree — removes the worktree directory with git worktree remove --force and deletes the branch with git branch -D
  • Keep — closes the tab in Notchly but leaves the worktree and branch on disk (you can re-open it later)
  • Cancel — does nothing

​
Storage location

All Notchly-created worktrees live under ~/.notchly/worktrees/. Each repository gets its own subdirectory named after the repo’s root folder.

​
When to use worktrees

Worktrees are most useful when you want to run multiple Claude sessions on the same codebase simultaneously. Without worktrees, two Claude sessions in the same directory would both try to edit the same files, producing conflicts. With worktrees, each session operates on its own checked-out branch — changes in one do not affect the other until you explicitly merge.
Combine worktrees with checkpoints for maximum safety: create a worktree, let Claude experiment freely in the isolated branch, then either merge the result into your main branch or discard the worktree entirely if the experiment did not pan out.
Worktrees require the tab’s directory to be inside a git repository. The “Open in Worktree” menu item is not shown for tabs running in non-git directories.

Build docs developers (and LLMs) love

Get started for freeTalk to us