Your first workspace

A workspace is the durable home for one kind of work. It can hold one project or several related repositories and remembers its theme, layout, tabs, agent defaults, and Git workflow settings.

This guide takes you from first launch through one completed task. You will add a repository, isolate the work on its own branch, run an agent, inspect the diff, and follow the Git action through cleanup.

1. Choose your defaults

First-run setup asks you to choose:

A default coding-agent provider and model. Installed CLIs appear first; additional and experimental providers are available behind More.
Chat UI or Terminal for new agent tabs. Chat UI renders messages, markdown, and inline diffs. Terminal runs the provider’s native command-line interface.
A Compact or Detailed left sidebar. Compact emphasizes tools and shows Git details on hover. Detailed keeps branch rows and status visible.

You can skip provider setup. Every choice remains editable in Settings.

2. Add the first project

Choose one action on the welcome screen:

Open project for an existing local repository or folder.
Clone from URL for a remote Git repository.
Quick start to create an Empty, Node, Python, or Rust project and initialize Git.

The app creates a workspace automatically and adds the project to it. Git, GitHub CLI, and GitLab CLI recommendations on the welcome screen are helpful but do not block local work.

Plain folders can open as non-Git projects, but branch-backed worktrees, diffs, and pull requests require Git.

3. Know the two places you can work

The project’s starred row is its primary worktree: the original checkout you opened or cloned. Use it for quick questions, small edits, or branch management.

Create a separate worktree for substantial tasks. Each task worktree has its own branch, working directory, tabs, process state, diff, and pull-request context. Parallel agents therefore do not edit the same checkout.

4. Create the first task worktree

Select the project, then click + or press .

With automatic worktree naming enabled—the default—the app immediately creates a temporary worktree and opens your default agent surface. Describe the task normally. The first meaningful prompt generates a branch name from your naming rules and renames the worktree once.

For example:

Add an empty state to the notifications queue and update its documentation.

The resulting branch might be feat/notification-empty-state.

If automatic naming is disabled, the app opens a naming form before creation. If the bundled sc helper is unavailable, it explains the problem and falls back to that manual form.

Use or New worktree from… when the starting point matters. The picker can start from:

A task prompt and selected provider.
A local or remote branch.
A GitHub pull request or GitLab merge request when the matching forge CLI is available.

See Branches and targets for base, target, and upstream branch semantics.

5. Work inside the task

All tools you open from the task use that worktree’s directory and context. You can:

Prompt an agent in Chat UI or a terminal.
Open files and diffs, attach context, and mention project files.
Split the view to keep a chat, terminal, diff, or browser visible together.
Start one or more named run scripts from the right panel.
Preview HTML in a native browser tab and send annotated elements back to a chat.
Leave a running task and respond later from the notification queue.

The worktree retains its tabs and layout when you switch projects or restart the app.

6. Review the result

Open Changes to see the recorded target, changed-file list, and branch diff for this worktree. Select a file for its line-level comparison, or open Review in the right panel for comment threads, AI findings, and agent submission controls.

Forge checks appear with the worktree’s PR or MR context and can change the adaptive Git action. The app does not invent a build or test command for the repository; use its configured run targets or an app-launched terminal when the project defines additional commands.

7. Follow the Git action

The Git button changes with the worktree’s state. It may offer Commit & push, Push, Create PR/MR, Fix CI, Resolve, Update, Ready for review, a merge strategy, or Delete worktree.

Some actions run directly through Git or the forge. Actions that need judgment open or reuse an agent according to your click, -click, provider, model, and prompt-template settings. Read Git actions and pull requests before customizing this flow.

8. Clean up

After the change is merged—or after you decide to discard it—delete the task worktree. Cleanup can stop run processes, execute configured hooks, remove the worktree directory, and optionally remove local branch or remote-tracking references according to your settings.

Deleting a task worktree does not delete the project’s primary checkout. Remote branch deletion is a separate forge or Git operation.

Customize after the first task

Open Settings with and search instead of browsing every category. Useful early changes include:

Provider, model, profile, and Chat UI versus Terminal defaults.
Automatic naming and branch naming rules.
Compact versus Detailed sidebar and visible worktree limits.
Manual and filtered worktree sections for a busy sidebar.
Project default branch, target branch, and worktree storage location.
Setup, named run, teardown, and cleanup scripts.
Git-action routing and prompt templates.
Notification delivery, queue behavior, and sounds.

Settings can apply globally, to one workspace, or to one project. The most specific configured value wins.