Getting started

Setup wizard

First launch opens /setup. The wizard has three stages.

1. Account login

   Connect with GitHub OAuth (device flow / web callback) or a personal access token. This step is skipped automatically if profiles already exist on this machine.

2. Workspace select

   Pick from configured local workspaces or add a new one with the + card.

3. Setup mode

   Choose one of two paths:

   • GitHub · clone a remote repository to a local path (commonly under ~/Documents/GitHub on macOS, or your Documents\GitHub folder on Windows)
   • Local · point OmniSync at an existing folder on disk

   Both paths create a profile, set it as the active session, and redirect to the dashboard.

Tooling setup prompt

If Node.js, Git, or the GitHub CLI is missing, a bottom-right setup prompt appears on the select-workspace screen. You can:

• Expand the checklist to see what is missing
• Install tools from the app when available (Homebrew on macOS, or a local copy)
• Dismiss the prompt and install tools yourself later

Folder permissions

OmniSync needs access to the folders where you keep repositories so it can clone, scan, and edit workspace files.

• macOS · the system may ask for Documents access (or Full Disk Access for broader paths). Prefer Documents if you keep repos under ~/Documents/GitHub.
• Windows · install under a normal user-writable path and allow the app through Controlled Folder Access if Windows Security blocks writes.

After setup

Once you land on the dashboard:

• Explore files in Workspace
• Fetch and sync remotes in Git Sync
• Verify the environment in Diagnostics
• Reopen the product tour anytime from the header Guide Tour control