Getting started

Add a repository, create a session, and watch Claude Code go to work — your first run, end to end.

This walkthrough assumes Plexus is already installed and that the Claude Code CLI and git are on your PATH. If not, start with Install and Requirements.

Launch Plexus

Open the app. The left sidebar already holds a Default workspace, so you're never staring at an empty tree. A workspace is just a grouping for related repositories — rename it or add more whenever you like. For the full hierarchy behind workspaces, projects, and sessions, see Concepts.

Add a repository

A project is a single git repository. Hover the Default workspace row, open its ⋯ menu, and choose Add repository…. (An empty workspace also shows an inline + Add repository button.)

The dialog offers three ways to add a repository — pick whichever fits:

From a local folder

Point Plexus at a git repository already on your machine.

1. Pick a folder in the native picker. If the folder isn't a git repository, Plexus offers to run git init for you.
   

   

2. Enter a project name and confirm.
   

   

The folder on disk is never moved or modified — Plexus just points at it.

From a connected provider

If you've connected GitHub or Bitbucket under Settings → Git providers, search your repositories and clone the one you want — no URL to copy.

1. Search your repositories — your own, ones you collaborate on, and your organizations' — across every provider you've connected, and select one.
2. Choose a parent folder on disk. Plexus clones into a <repo-name> subfolder of it; the folder name defaults to the repository name and is editable.
3. A live progress bar shows the clone's percentage and current phase, with a Cancel button if you change your mind. When it finishes, the cloned repository is registered as a project just like a local folder.

Private repositories authenticate automatically using the connection Plexus already holds — the token stays on your device, and the clone talks to GitHub or Bitbucket directly.

From a URL

Paste any https or ssh git URL to clone it.

1. Paste the repository URL.
2. Choose a parent folder, adjusting the destination folder name if you like (it defaults to the repository name).
3. Watch the same live progress bar with Cancel, then Plexus registers the clone as a project.

ssh URLs and public repositories use your own local git setup — the keys and credentials git clone would use.

However you add it, the project appears in the tree under the workspace.

Create a session

A session is a named Claude Code conversation. On the project row, open the ⋯ menu and pick one of:

• New session… — name the session and choose a base branch (a smart default is pre-selected). Plexus cuts a fresh worktree and feature branch from that base, keeping the work isolated from your main checkout.
  

  

• Start session on root tree — name the session only, with no base-branch picker. It runs directly in the project's root working tree and starts immediately. Good for quick edits.

Start the agent

By default, both root-tree and standard sessions launch the moment you create them — a short "Starting…" spinner walks through the stages (creating the worktree, running any setup hooks, then starting the agent) before Claude Code appears in the Agent tab. Prefer to start standard sessions yourself? Click Start in the Agent tab.

Send your first prompt

In the Agent tab, type a prompt and press Enter. Watch the activity dot on the session row:

• green, pulsing — the agent is working,
• amber — it's waiting for your input or approval,
• gray — idle.

These same indicators surface on the Dashboard, so you can track several sessions at once. See Session status for what each state means.

Explore the tabs

While the agent works, switch between the per-session tabs:

Read more about each: the Agent tab, Review tab, Explorer tab, and Git tab.

Next steps

• Understand the model in Concepts.
• Get gitignored files like .env into worktrees with Worktrees.
• Wrap up by opening a pull request.
• Learn every shortcut on the Shortcuts page.