# Quickstart

This guide walks you through the core Polyscope workflow: adding a repository, creating a workspace, prompting an agent, and shipping the result.

## 1. Add a Repository

Click the **Add Repository** button at the bottom of the left sidebar or use **⌘K** and go for **Add Repository**. Enter the path to a local git repository – autocomplete suggestions appear as you type – or select the folder directly. You can also start by cloning a repository direct from GitHub.
.

![Adding a repository](/images/docs/add-repository-local.png)

## 2. Create a Workspace

Select your repository in the sidebar and click on the **+** icon to create a new workspace. Polyscope will:

1. Create a **copy-on-write clone** of your repository (fast, even for large repos)
2. Check out a fresh branch based on your base branch (usually `main`)
3. Run any **setup scripts** defined in `polyscope.json`

Each workspace gets a randomly generated name (like "brave-bunny" or "golden-raven") and its own isolated copy of your codebase.

![New workspace created](/images/docs/add-workspace.png)

## 3. Write a Prompt

Type your prompt in the input area at the bottom of the screen. Describe what you want the agent to do – it can be a debugging question, feature, bug fix, refactor, or any coding task.

You can also:

- **Attach images** — Drag and drop or paste screenshots
- **Mention files** — Type `@` to reference specific files
- **Use slash commands** — Type `/` to see which ones are available
- **Choose a model** — Switch between Claude and Codex models per prompt
- **Enable plan mode** — Have the agent propose a plan before making changes

## 4. Watch the Agent Work

The agent reads your codebase, makes changes, and shows its progress in the activity feed. You can follow along in real time and send follow-up messages while it works.

![Agent working](/images/docs/getting-started-agent.png)

When it finishes, switch to the **diff panel** (**⌘D**) to review all changes with syntax highlighting. You can toggle between **unified** and **split** diff views for side-by-side comparison. Leave inline comments if you want the agent to adjust anything.

## 5. Create a Pull Request

When you're happy with the changes, click the **PR** button in the workspace header. The agent will commit, push, and create a pull request on GitHub.

![Creating a pull request](/images/docs/getting-started-pr.png)

Alternatively, click **Merge** to merge changes directly into your base branch — ideal for small fixes or personal projects.

## Next Steps

- Learn the recommended [Workflow](/docs/core-concepts/workflows) for getting the most out of Polyscope
- Configure [setup scripts](/docs/core-concepts/workspaces) for automatic workspace preparation
- Explore the [Command Palette](/docs/digging-deeper/command-palette) for all available actions