Clone & add project
Ghostex registers every repository as a sidebar project group. Add an existing folder with the Projects header + button, or clone a remote repository and add it in one step. gxserver owns project registration; the sidebar updates immediately.
WorkflowProjects
Add project
- Projects section header → + button (tooltip and aria: Add project).
- macOS NSOpenPanel prompt: Add Project — Choose a project folder to add to Ghostex.
- gxserver addProjectPath registers the folder and returns worktree metadata when applicable.
- Sidebar row appears immediately; worktree paths nest under their parent project.
- Remote machines expose the same Add project button via connected remote gxserver.
Clone Repository modal
| Option | What it does |
|---|---|
Clone Repository | Modal title, header download icon tooltip, palette entry |
Repository | GitHub shorthand (maddada/zehn), HTTPS, or SSH URL |
Folder location | Choose — native picker; remembers ghostex.addRepository.lastLocation |
New folder | Optional subfolder name — empty uses repo name |
Branch | Optional — empty clones default branch (main/master) |
Clone branch only | Single-branch checkout option (unchecked by default) |
Shallow clone | Depth-limited clone option (unchecked by default) |
Clone & Add | Submit — modal closes; progress in toasts |
Remote clone description: Clone a Git repository on {machine} and add it as a remote project.
Clone & Add workflow
- Open via Projects header Clone Repository icon or Cmd+Shift+P → Clone Repository.
- Fill repository and destination — gxserver /api/previewRepositoryClone validates (debounced 220 ms).
- Submit Clone & Add → modal closes → /api/startRepositoryClone background job.
- Poll until success → addProject + toast Repository cloned.
- Existing destination path blocks clone — preview shows a warning before submit.
- Running toast includes Cancel action while clone is in progress.
Preview validation
- Repository field accepts GitHub owner/repo shorthand, full HTTPS, and SSH URLs.
- Branch name validated against remote refs when preview succeeds.
- Preview warns when destination folder already exists or is not writable.
- canSubmitAddRepositoryClone gates the Clone & Add button until required fields pass.
Command palette
Built-in palette command Clone Repository — searchable as clone, add project, git, github, codeberg, repository.
- Cmd+Shift+P (command mode) — type Clone Repository.
- No dedicated hotkey — use palette or sidebar header icon.
- Remote destination browse available via remote project picker modal.
CLI
ghostex add-project /path/to/repo --name my-project
ghostex switch-project --path /Users/you/dev/project| Option | What it does |
|---|---|
add-project | Register an existing folder — same gxserver path as Add project UI |
switch-project | Focus a registered project by path |
Clone jobs are UI-driven through gxserver clone APIs — there is no single gx clone command in the public CLI.
Worktree detection
When addProjectPath detects a Git worktree checkout, gxserver returns worktree metadata and Ghostex nests the row under the parent repository instead of creating a duplicate top-level project.
- Use Add project for folders you already cloned with git clone or git worktree add.
- Use Clone & Add when starting from a remote URL.
- Worktree projects inherit parent Actions and worktreeCommand settings.
Remote projects
- Connected remote Mac sections expose Add project and Clone Repository against remote gxserver.
- Clone runs on the remote machine — the sidebar row represents a remote project path.
- Remote destination folder picker browses the remote filesystem via SSH tunnel.
Tips
- Shallow clone saves time for large monorepos when you only need recent history.
- Clone branch only when you know exactly one branch matters — speeds CI-style checkouts.
- Folder location persists — set it once per machine and reuse for multiple clones.
- After clone, configure beadsDisplayKey and worktreeCommand in Settings → Projects before heavy use.
- Use ghostex add-project in scripts to register folders without opening the native picker.