Build with a Team of AI Agents

Run parallel AI coding agents in isolated Git workspaces using Conductor.

Introduction

30 Second Summary

Coding with an AI assistant is fast, but you still work on one thing at a time. While your agent builds a navigation bar, you sit and wait instead of moving on to the next feature.

In this project, you will set up Conductor on your Mac to run multiple Claude Code agents in parallel, each in its own isolated workspace. You will review their changes, create pull requests, and merge finished code into your main branch.

What You'll Build

Picture opening Conductor and seeing three AI agents working on three different features of your project at the same time, each in its own workspace, while you review and merge their finished code.

By the end of this project, you'll have:

  • Spun up a new AI coding agent in one click and watched it work in its own isolated copy of your codebase.
  • Run multiple agents simultaneously on different features without them stepping on each other's code.
  • Reviewed every change in the diff viewer, created a pull request, and merged it without leaving the app.
  • Secret Mission: Configure project scripts so every new workspace automatically installs dependencies and starts a dev server.

Are there any prerequisites?

This project requires a Mac (Conductor is macOS only). You also need a GitHub account with the GitHub CLI installed and authenticated, plus a Claude Code subscription with the CLI logged in.

Before We Start

Before diving into the hands-on work, let's lock in what you're about to build and why it matters. This step is your chance to commit to the goal before any setup begins.

Install Conductor and Verify Your Setup

Conductor orchestrates AI coding agents on your Mac, managing isolated workspaces, branches, and pull requests. Before it can do any of that, it needs to confirm two things: that your GitHub CLI is authenticated and that Claude Code is logged in.

In this step, you will download Conductor, install it on your Mac, and make sure all its setup checks pass with green checkmarks.

In this step, get ready to:
  • Download and install Conductor on your Mac.
  • Verify that all setup checks pass with green checkmarks.
  • Confirm you see the Conductor home screen.
Download and install Conductor

Conductor is a Mac app you download directly from its website. There is no package manager or CLI install involved.

  • Open your browser and go to conductor.build.
  • Click Download Conductor on the page.
  • Once the download finishes, open your Downloads folder and drag the Conductor app into your Applications folder.
  • Press Cmd+Space to open Spotlight.
  • Type Conductor and press Enter to open the app.

Conductor launches and immediately displays a setup checklist on screen.

Seeing a security warning?

macOS may block the app from opening because it was downloaded from the internet. If this happens, open System Settings, go to Privacy & Security, and scroll down to the Security section. You will see a message about Conductor being blocked. Click Open Anyway and enter your password to confirm.

Help me open Conductor past the macOS security prompt.

Verify your setup checks

Conductor runs its setup checks automatically when it opens. It verifies your GitHub CLI authentication and your Claude Code login. Both checks should show green checkmarks since you set these up as prerequisites.

What does Conductor check?

The GitHub check is the same as running gh auth status in your terminal. Conductor needs GitHub to manage branches and pull requests for your workspaces.

The Claude Code check is the same as running claude /login in your terminal. Conductor needs Claude Code as the AI agent that reads and edits your code.

✔️ All checks show green checkmarks

All checks pass. You are ready to start using Conductor.

ⓧ One or more checks are failing

Conductor displays instructions next to each failing check. Follow the on-screen prompts to fix it.

  • For a GitHub CLI failure, Conductor guides you to authenticate with GitHub in your terminal.
  • For a Claude Code failure, Conductor guides you to log in to Claude Code in your terminal.

Once all checks turn green, you are ready to continue.

Still seeing a failing check?

Help me fix a failing Conductor setup check.

Confirm the Conductor home screen

What do you expect to see now that all setup checks have passed?

You should see the Conductor home screen with options to add a repository. All setup checks show green checkmarks with no warnings or missing credentials. This is the screen you will use in the next step to import a project.

Conductor is installed and connected. Next up, you will create a starter project and push it to GitHub so Conductor has a real repository to work with.

Create a Starter Project and Import It into Conductor

Conductor is installed and all your setup checks pass. Now you need a project for your AI agents to work on.

Conductor creates isolated workspaces from Git repositories. In this step, you will create a minimal HTML project, push it to GitHub, and import it into Conductor so it can start managing branches and workspaces for you.

In this step, get ready to:
  • Create a starter HTML project and push it to a GitHub repository.
  • Import the repository into Conductor and create your first workspace.
  • Verify your workspace has its own branch and working tree with your project files.
Create a starter project and push it to GitHub
  • Press Cmd+Space to open your search bar.
  • Type Terminal and press Enter to open it.
  • Move to your Desktop by running this command:
cd ~/Desktop
  • Create your project folder and initialize a Git repository by running these commands:
mkdir conductor-demo
cd conductor-demo
git init

You should see a message that says Initialized empty Git repository in the output.

Don't see the initialized message?

Make sure you ran all three lines. If your terminal shows conductor-demo at the end of your prompt path, you are in the right place. Run git status to confirm the repository exists.

Help me set up a Git repository in my conductor-demo folder.

Now you will create two starter files. The index.html file is a simple web page, and style.css controls its appearance.

  • Create index.html by running this command:
cat > index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Conductor Demo</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <main>
        <h1>Welcome to My Project</h1>
        <p>This is a starter page. AI agents in Conductor will improve it.</p>
    </main>
</body>
</html>
EOF

What does this command do?

The cat > index.html << 'EOF' pattern is called a heredoc. It creates a file and fills it with everything between the two EOF markers.

The HTML itself is a basic page with a heading and a paragraph inside a <main> element. It links to style.css for styling. The content is intentionally simple so any AI agent prompt produces visible changes.

  • Create style.css by running this command:
cat > style.css << 'EOF'
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: system-ui, -apple-system, sans-serif;
    line-height: 1.6;
    color: #333;
    max-width: 800px;
    margin: 0 auto;
    padding: 2rem;
}

h1 {
    margin-bottom: 1rem;
}
EOF

What does this file do?

The * selector resets default browser spacing on every element. The body rule sets a clean, centered layout with a system font. Your AI agents will add to these styles when they modify the project.

  • Confirm both files exist by running:
ls

You should see index.html and style.css in the output.

Missing a file?

If only one file appears, the heredoc command for the missing file may not have completed. Check that you pasted the entire command including the closing EOF on its own line. Run the missing file's cat command again.

Help me create my starter files in the conductor-demo folder.

✔️ Awesome, I've got everything!

Great. Make sure both files are saved and you see them in the output of your last command.

ⓧ I'd like to double check the full code

Here is the full content of each file. Compare them against what you created.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Conductor Demo</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <main>
        <h1>Welcome to My Project</h1>
        <p>This is a starter page. AI agents in Conductor will improve it.</p>
    </main>
</body>
</html>
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: system-ui, -apple-system, sans-serif;
    line-height: 1.6;
    color: #333;
    max-width: 800px;
    margin: 0 auto;
    padding: 2rem;
}

h1 {
    margin-bottom: 1rem;
}
  • Commit your files and push them to a new GitHub repository by running these commands:
git add .
git commit -m "Initial commit"
gh repo create conductor-demo --public --source=. --push

What do these commands do?

  • git add . stages both files for commit.
  • git commit -m "Initial commit" saves a snapshot of your project.
  • gh repo create uses the GitHub CLI to create a new public repository called conductor-demo on your GitHub account. The --source=. flag tells it to use your current folder, and --push sends your commit to GitHub in the same step.

You should see output confirming the repository was created, including a URL like https://github.com/your-username/conductor-demo.

Seeing an authentication error?

If gh repo create fails with a permissions error, your GitHub CLI session may have expired. Run gh auth status to check, then gh auth login to re-authenticate if needed.

If you see an error that the repository name already exists, you may have created it during a previous attempt. Delete the existing repo on GitHub or choose a different name.

Help me push my conductor-demo project to GitHub.

Import your repository into Conductor

Your project is on GitHub. Now you will bring it into Conductor so it can create workspaces from it.

  • Switch back to Conductor.
  • Click Open GitHub project on the home screen.
  • Find and select your conductor-demo repository from the list.

Conductor imports the repo and creates your first workspace. Each workspace gets a unique city name (like "tokyo" or "sacramento") and its own branch and working tree.

What is a workspace?

A workspace is an isolated copy of your repository. It gets its own branch, its own set of files, and its own terminal. Changes in one workspace never affect another.

Under the hood, Conductor uses Git worktrees to keep each workspace's files separate while sharing the same repository history.

Don't see your repository in the list?

Make sure the gh repo create command finished successfully in your terminal. Conductor fetches repositories from your authenticated GitHub account. If the repo does not appear, try closing and reopening Conductor.

Help me import my repository into Conductor.

Verify your workspace and project files

Before you start giving tasks to AI agents, take a moment to confirm your workspace is set up correctly.

  • In the sidebar, check that your workspace appears with a city name and a branch name underneath it. The branch name is different from main. This confirms the workspace is isolated from your main branch.
  • Look at the bottom of the screen to find the chat composer. This is where you will send prompts to your AI agents in the next step.
  • Check the terminal panel on the right side. This is the workspace's own isolated terminal, separate from the one you used to create your project.

Before you move on, what files do you expect to see in this workspace?

The workspace contains index.html and style.css from your initial commit. These are the files your AI agents will modify. Your main branch stays untouched while agents work on the workspace's branch.

Your project is inside Conductor with its own workspace and branch. Next up, you will give your first AI agent a task and watch it modify your code in real time.

Launch Your First AI Agent in a Workspace

Your starter project is imported into Conductor. Your first workspace is ready with its own branch and working tree.

In this step, you'll give Claude Code a task and watch it modify your project in real time. The agent edits your files on the workspace's branch while your main branch stays exactly as it is.

In this step, get ready to:
  • Send a prompt to Claude Code in your workspace's composer.
  • Watch the agent read, plan, and edit your code in real time.
  • Review every change in the Diff Viewer.
Give Claude Code its first task

Conductor's chat composer sits at the bottom of the screen. This is where you talk to your AI agent.

  • Look at the model picker in the composer area at the bottom of the screen.
  • Confirm Claude Code is selected. If a different model is shown, click the picker and choose Claude Code.
  • Send Claude Code its first task by typing this prompt in the composer:
Add a navigation bar with Home, About, and Contact links. Style it with a dark background and white text. Also add a hero section below the nav with a heading and subtitle.

What happens when you send a prompt?

Conductor routes your prompt to the Claude Code agent running inside the workspace. The agent can see every file in the workspace's working tree.

It has full permission to read and edit those files. All changes happen on the workspace's branch, so your main branch is never touched.

After pressing Enter, Claude Code begins working in the terminal panel on the right side of the screen.

Watch Claude Code work in real time

The terminal panel shows every step the agent takes. You can follow along as it reads your files, plans its approach, and edits them.

  • Watch the terminal panel as Claude Code reads index.html and style.css, then writes its changes.
  • Wait for the agent to finish. You'll see it stop outputting in the terminal when the task is complete.

Why is my main branch safe?

Each workspace uses a Git worktree under the hood. A worktree is a separate copy of your repository's files tied to its own branch.

Claude Code edits files inside this worktree. The workspace's branch gets all the changes, while main stays untouched.

Review changes in the Diff Viewer

Claude Code has finished editing your files. Before you look at exactly what changed, take a guess: do you think the changes show up on your main branch, or only on the workspace's branch?

  • Open the Diff Viewer by pressing Command + Shift + D.
  • Review every file Claude Code changed. Click through the file list to see additions and modifications highlighted in the diff.

The diff shows all of Claude Code's additions on the workspace's branch. Your main branch has not been touched. This is the same diff you would see in a pull request, but you haven't left Conductor.

Don't see any changes in the Diff Viewer?

  • Make sure Claude Code has finished working. Look for the agent to stop outputting in the terminal panel before opening the Diff Viewer.
  • Double-check the keyboard shortcut: Command + Shift + D. A similar shortcut might open a different panel.
  • If the agent encountered an error, try sending a simpler prompt like "Add a navigation bar with three links at the top of the page" and let it try again.

Help me figure out why my Diff Viewer is empty

You've seen a single agent transform your starter page on its own branch. Next up, you'll run multiple agents in parallel across separate workspaces, each tackling a different feature at the same time.

Run Parallel Agents Across Workspaces

In the last step, you launched your first Claude Code agent and watched it modify your project files in an isolated workspace. That agent handled one task well, but you had to wait for it to finish before starting something new.

Conductor can run multiple agents at the same time, each in its own workspace with its own branch and working tree. In this step, you will spin up two more workspaces and watch three agents work in parallel on completely independent features. No waiting, no conflicts.

In this step, get ready to:
  • Create two more workspaces, each with its own Claude Code agent and task.
  • Watch three agents work simultaneously on independent features.
  • Compare the independent diffs across all three workspaces.
Create a second workspace with a new task

Every new workspace in Conductor starts from the latest commit on your main branch. This means your second agent starts from the same clean codebase as the first, with zero awareness of Workspace 1's changes.

  • Press Command + N to open the Dispatcher and create a new workspace.
  • A second workspace appears in the sidebar with its own city name (like "warsaw" or "sacramento") and its own fresh branch.

What are Git worktrees?

Under the hood, Conductor uses Git worktrees to create each workspace. A worktree is a separate copy of your repository's files that is tied to its own branch. This is what makes true isolation possible.

Because each workspace is a separate worktree, one agent can rewrite index.html in its workspace without touching the same file in any other workspace.

  • In the new workspace's chat composer, type a prompt asking Claude Code to add a footer. For example: "Add a footer with copyright info, social media links, and a back-to-top button. Style it to match the dark nav theme."
  • Press Enter to send the prompt.

Watch the agent start working in the terminal panel. It reads your files and begins editing index.html and style.css on its own branch, completely independent of Workspace 1.

Agent not starting?

Make sure you selected Claude Code from the model picker in the new workspace. Each workspace has its own model selection.

If Claude Code still does not respond, check that your Claude Code subscription is active.

Why is my Claude Code agent not starting in the new workspace?

Spin up a third workspace for another feature

You do not need to wait for the second agent to finish. That is the whole point. Spin up a third workspace while the second one is still working.

  • Press Command + N again to create a third workspace.
  • In this workspace's composer, type a prompt for a completely different feature. For example: "Add an About page (about.html) linked from the navigation. Include a short bio section and a skills list with styled cards."
  • Press Enter to send the prompt.

Look at the sidebar. You now have three workspaces, each with its own city name and its own agent working on a separate feature. Three tasks running at once, each on its own branch.

Multiple workspaces vs. multiple agents in one workspace

Use multiple workspaces when tasks should land independently as separate pull requests. Each workspace gets its own branch.

Use multiple agents in one workspace when the work shares the same branch and code state. That keeps related changes together.

Switch between workspaces and compare diffs

Before you start switching between workspaces, think about what you expect to see. Will all three workspaces show the same changes, or will each diff be different?

  • Click on your second workspace (the footer task) in the sidebar.
  • Press Command + Shift + D to open the Diff Viewer.
  • Review the changes. This workspace only shows footer additions. No nav bar, no hero section.
  • Click on your third workspace (the About page task) in the sidebar.
  • Press Command + Shift + D to open the Diff Viewer.
  • This workspace shows about.html and navigation changes. No footer code appears here.

Each workspace's diff is completely independent. Workspace 1 has the nav bar and hero section. Workspace 2 has the footer. Workspace 3 has the About page. Your main branch remains untouched through all of this.

This is the parallel agent workflow

Split your work into independent tasks. Assign each to its own workspace. Let agents handle them concurrently. Then review each result on its own terms.

This workflow scales to as many workspaces as you need. The only constraint is that one branch can only be checked out in one workspace at a time.

Diffs look similar across workspaces?

Each workspace branches from your latest main branch commit, not from another workspace. If two diffs look similar, the agents may have independently decided to add similar elements. Check that you gave each workspace a distinct prompt.

Also confirm you are clicking different workspaces in the sidebar. The highlighted workspace name tells you which one you are viewing.

Why do my Conductor workspaces show similar diffs?

Three agents, three features, zero conflicts. Next up, you will review an agent's work, create a pull request, and merge it into your main branch.

Review, Create a PR, and Merge

In the last step, you launched three agents across separate workspaces. Each one tackled a different feature on its own branch, and now you have three sets of changes waiting to be reviewed.

Speed without review is chaos. Conductor keeps you in control by letting you inspect every diff, request fixes from the agent, create pull requests, and merge finished work into your main branch. All without leaving the app.

In this step, get ready to:
  • Review an agent's changes in the Diff Viewer and request fixes if needed.
  • Create a pull request from within Conductor.
  • Merge the PR and archive the finished workspace.
Review your agent's changes in the Diff Viewer

Before any code reaches your main branch, you need to see exactly what the agent changed. Conductor's Diff Viewer shows a side-by-side comparison of every file the agent modified on the workspace's branch.

  • Pick the workspace you are most excited about from the sidebar.
  • Open the Diff Viewer by pressing Cmd+Shift+D.

You should see a color-coded diff with green lines for additions and red lines for removals. Every change is scoped to this workspace's branch. Your main branch is untouched.

What can I do in the Diff Viewer?

The Diff Viewer is more than a read-only view. You can leave comments on specific changed lines, send those comments back to the agent for targeted fixes, and even revert individual files you do not want to keep.

  • Review each changed file in the diff. Look for anything that seems off or incomplete.
  • If something looks wrong, type feedback in the composer at the bottom of the workspace. Claude Code will make corrections on the same branch.

Use inline comments for precise feedback

Instead of describing a problem in the composer, click on a specific line in the diff to leave an inline comment. You can then send those comments back to the agent for a targeted fix. This is faster and more accurate than describing the issue in plain text.

Don't see any changes in the Diff Viewer?

Make sure the agent has finished working. Check the terminal panel on the right side of the workspace. If the agent is still running, wait for it to complete before reviewing.

Also confirm you selected the correct workspace in the sidebar. Each workspace has its own independent diff.

Why isn't my Diff Viewer showing any changes?

Check merge readiness and create a pull request

Once you are happy with the diff, you need to confirm the branch is in a clean state before creating a pull request. The Checks tab gathers everything that determines whether a workspace is ready to merge.

  • Open the Checks tab in the workspace.
  • Confirm the git status shows a clean branch with no uncommitted changes.

What does the Checks tab show?

The Checks tab gathers git status, pull request metadata, CI and status checks, deployments, GitHub comments and review threads, and todos. For this project, you are mainly looking at git status to make sure nothing is uncommitted.

  • Create a pull request by pressing Cmd+Shift+P.

Conductor sends the current diff and repository context to Claude Code so it can draft a PR description. It then pushes the branch to GitHub and opens the pull request.

  • Wait for Conductor to finish creating the PR. You should see the pull request metadata appear in the Checks tab.
  • Open your conductor-demo repository on GitHub in your browser. Navigate to the Pull requests tab to confirm the PR is there.

You should see a new pull request with a description drafted by Claude Code, listing the changes the agent made.

PR not appearing on GitHub?

Make sure Conductor finished creating the PR. Watch the terminal panel for any errors during the push. If you see an authentication error, check that gh auth status still shows you as logged in.

Why is my pull request not showing up on GitHub?

Merge the PR and archive the workspace

The pull request is live on GitHub. Now it is time to merge the agent's work into your main branch and clean up the finished workspace.

  • Return to the workspace in Conductor.
  • Merge the pull request from within Conductor.

Before you check GitHub, what do you expect to see on your repository's main branch now?

  • Open your conductor-demo repository on GitHub and switch to the main branch.

Your main branch now contains the merged feature's changes. The pull request appears as merged in the repository's PR history. The agent's code is officially part of your project.

  • Back in Conductor, archive the workspace you just merged.

The workspace disappears from your sidebar. If you ever need to revisit it, you can restore it from the History pane in the sidebar, including its full chat history.

Why archive instead of delete?

Archiving removes a workspace from your active sidebar without destroying it. Conductor saves the git state and chat history so you can restore the workspace later if needed. This keeps your sidebar focused on work in progress while preserving a record of finished tasks.

  • Repeat this review-and-merge cycle for your other workspaces as practice. Open each workspace's Diff Viewer, review the changes, create a PR, merge it, and archive the workspace.

Watch for merge conflicts

If two workspaces changed the same file (like both editing index.html), the second PR may have merge conflicts. If that happens, type a message in the composer asking Claude Code to resolve the conflicts. It will update the branch, and you can review the resolution in the Diff Viewer before merging.

Workspace won't archive?

If the workspace has an archive script configured and it fails, Conductor may not complete the archive. For this project, you have no archive script, so this should not happen. If the workspace still does not archive, check for any running processes in the workspace's terminal and stop them first.

Help me archive my Conductor workspace.

Secret mission

Configure Project Scripts for Every Workspace

Every new Conductor workspace starts bare. You have to manually install dependencies and start servers each time. In this mission, you will create a shared settings file that automates workspace setup and serves your project on its own port.

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally on Conductor's free plan, so there are no ongoing costs.

Resources you used:

  • A GitHub repository (conductor-demo) with branches and merged pull requests.
  • A local conductor-demo project folder on your Desktop.
  • Conductor workspaces (local directories managed by Conductor).

Keep everything running

No action needed. Choose this if you plan to keep experimenting with Conductor and your demo project.

  • Your GitHub repository stays as it is. Merged pull requests and branches remain accessible.
  • Conductor's free plan has no time limit for local workspaces, so nothing costs money.
  • Conductor remains installed in your Applications folder and is ready whenever you want to use it again.

Pause - I'll come back to this later

Archive your active workspaces to free up local disk space while keeping everything restorable.

  • In Conductor, archive any remaining active workspaces. You can restore them later from the History pane.
  • Your GitHub repository and local project folder stay intact. No data is lost.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow each step below to fully clean up.

  • In Conductor, archive all remaining workspaces. Then right-click the project in the sidebar to remove it from Conductor entirely.
  • Delete the local project folder by running this command in your terminal:

macOS

rm -rf ~/Desktop/conductor-demo

Windows

Conductor is macOS only, so this command applies to your Mac terminal:

rm -rf ~/Desktop/conductor-demo
  • Delete the GitHub repository. Open your browser and go to your conductor-demo repository on GitHub.
  • Click the Settings tab near the top of the repository page.
  • Scroll down to the Danger Zone section at the bottom.
  • Click Delete this repository and follow the confirmation prompts. You will need to type the full repository name to confirm.

That's a Wrap!

That's a Wrap!

Nice work! You've just built a parallel AI coding workflow using Conductor and Claude Code. You can now spin up isolated agents, let them work simultaneously, and merge their results into your main branch.

You've learned how to:

  • Create isolated workspaces in Conductor, each with its own Git branch and working tree, and run an AI agent to modify your codebase without touching the main branch.
  • Run multiple AI agents in parallel across separate workspaces, each working on independent features simultaneously with no conflicts.
  • Review diffs in the Diff Viewer, create pull requests, and merge agent work into your main branch without leaving Conductor.
  • Secret Mission: Configured shared project scripts in .conductor/settings.toml so every new workspace automatically runs setup and can serve your project on its own port.

Ready to quiz yourself?