TechLatest

Posted on Jul 9 • Originally published at Medium on Jul 8

Orca Tutorial: Multi-Agent AI Coding Workspace from Scratch

#opensource #aiworkflow #agents #orcas

AI coding agents have completely changed the way we build software. Whether it’s Claude Code , Codex , OpenCode , Cursor , or another CLI-based assistant, it can write code, fix bugs, generate documentation, and even help review pull requests. But there’s one problem — most developers still use them one at a time.

You ask one agent a question, wait for the response, compare it manually with another model, switch Git branches, copy code between editors, and repeat the process. It works, but it isn’t the most efficient way to build modern software.

That’s where Orca comes in.

Orca is an open-source AI orchestration workspace that brings your repository, AI coding agents, Git worktrees, terminal, browser, and development tools together in a single application. Instead of choosing just one AI assistant, you can run multiple coding agents in parallel, compare their outputs, review the generated changes, and merge the best implementation into your project — all without leaving Orca.

One of the best things about Orca is that getting started doesn’t have to cost anything. In this guide, we’ll use OpenCode together with a free model from OpenRouter , so you can experience the complete workflow without paying for API credits. If you already have Claude Code, Codex, or another supported CLI agent installed, you can use those as well.

In this guide, we’ll start from scratch by installing Orca, completing the initial setup, connecting our first repository, creating worktrees, launching AI agents, and exploring the features that make Orca one of the most powerful workspaces for AI-assisted software development. Whether you’re an individual developer, an open-source contributor, or part of a large engineering team, this guide will help you get the most out of Orca.

Step 1: Download and Install Orca

The first step is to install Orca on your operating system. Orca is available for macOS, Windows, and Linux , making it easy to get started regardless of your development environment.

Visit the official Orca website and click the Download button. The website automatically detects your operating system and provides the appropriate installer. If you’re using a different platform, you can also choose from the available downloads for macOS (Apple Silicon & Intel), Windows, and Linux.

Note: In this guide, we’re using macOS (Apple Silicon).

After downloading the installer, complete the installation process just like any other desktop application. Once installed, launch Orca from your Applications folder (macOS) or Start Menu (Windows).

Tip: Orca is a desktop application, so no additional configuration is required before launching it for the first time.

Download Options

macOS (Apple Silicon)
macOS (Intel)
Windows (.exe)
Linux (AppImage)
Homebrew (macOS)
AUR (Arch Linux)

If you’re using Homebrew on macOS, you can install Orca directly from the terminal:

brew install --cask stablyai/orca/orca

Step 2: Complete the Getting Started Onboarding

After launching Orca for the first time, you’ll be presented with the Getting Started onboarding wizard. This setup walks you through the core features you’ll use while working with multiple AI coding agents. Completing these steps ensures Orca is configured correctly before you begin creating worktrees and running agents.

The onboarding consists of several setup tasks, and we’ll go through each one in detail.

Step 2.1: Enable Desktop Notifications

The first onboarding task is to turn on notifications.

Desktop notifications are useful because Orca can run AI agents for several minutes, especially when you’re working with large repositories or complex prompts. Instead of constantly checking the application, Orca notifies you whenever an agent:

Completes a task
Requires your attention
Gets blocked or encounters an error

This allows you to continue working on other tasks while Orca runs your agents in the background.

Enable Notifications on macOS

Click Open Mac Settings.
Navigate to Notifications.
Locate Orca in the application list.
Enable Allow Notifications.
(Optional) Choose your preferred notification style, such as banners or alerts.

Once enabled, return to Orca.

Step 2.2: Choose Your Default AI Agent

The next onboarding step is to choose your default agent. Orca automatically detects the AI coding agents installed on your system and lets you select which one should be used by default whenever you create a new worktree or start a new coding session.

This saves time, as you won’t need to manually select your preferred agent every time you begin working on a project.

In our setup, Orca detected the following AI agents already installed on the system:

Claude
OpenCode
Hermes
OpenClaw

Additionally, Orca supports many other CLI-based coding agents, including:

Codex
GitHub Copilot
Grok
OpenClaude
MiMo Code
Continue
Cline
Kiro
Qwen Code
Goose
Amp
Devin
Pi
and many more.

Select Your Preferred Agent

Simply click on the agent you want to use as your default. In this guide, we’ll use Claude as the default AI coding assistant, but you can choose any supported agent based on your workflow.

Once selected, Orca highlights the chosen agent, indicating that it will be used automatically for future tasks.

Step 2.3: Enable Orca CLI

The next onboarding step is to enable the Orca CLI. This installs the orca command on your system and sets up the built-in skills that allow Orca to orchestrate AI agents, interact with browsers, and control your desktop when needed.

Click Install CLI & Skills to begin the installation. Orca will automatically configure everything required in the background.

During the setup, Orca installs three core capabilities:

Agent Orchestration : Allows multiple AI agents to work together on the same project and coordinate multi-step tasks.
Agent Browser Use: Gives agents access to Orca’s built-in browser so they can open web pages, capture screenshots, inspect content, and interact with websites.
Computer Use: Enables agents to control your desktop by moving the mouse, clicking buttons, typing text, and interacting with applications when a workflow requires it.

On macOS, Orca may also request Full Disk Access. Granting this permission is recommended, especially if your projects are stored in protected folders such as Desktop , Documents , or Downloads. This ensures Orca can access and edit your repositories without permission issues.

Once the installation finishes, the setup will be marked as complete, and you’re ready to continue with the next onboarding step: Connect Integrations.

Tip: You can verify the installation at any time by opening a terminal and running:

orca --help

Step 3: Connect Your Integrations

With the initial onboarding complete, the next step is to connect the services you use every day. Orca integrates with tools like GitHub, Linear, and Jira , allowing you to manage your development workflow without constantly switching between applications.

If you’ve already connected your GitHub account, Orca can display the status of your pull requests and repositories directly within the application. This makes it easy to monitor ongoing work while your AI agents continue coding in the background.

For project management, Orca also supports:

Linear — Browse issues, start work directly from a task, and keep your AI-generated changes linked to your project.
Jira — Access Jira Cloud issues, create worktrees from tickets, and track development without leaving Orca.

To connect a service, simply click the corresponding Connect button and authorize your account. Once connected, the integration becomes available throughout Orca, making it easier to move from an issue or task to an AI-powered coding session in just a few clicks.

Note: Connecting GitHub is highly recommended if you’re working with Git repositories. Linear and Jira are optional and can be connected later from Settings if your team uses them.

After connecting the integrations you need, click Done to continue to the next step, Automate Workspace Setup.

Step 4: Automate Workspace Setup

The next step is to automate Workspace Setup. This feature lets Orca automatically run setup commands whenever it creates a new Git worktree. Instead of manually installing dependencies every time you start a new task, Orca can prepare the project for you.

For example, if your project uses pnpm , you can configure the setup command as:

pnpm install

Similarly, you can use commands such as:

npm install

yarn install

bun install

Or any custom setup script required by your project.

Once you’ve entered the command, click Save. From then on, every new worktree created for that repository will automatically execute the setup command, ensuring the environment is ready before your AI agents begin working.

Note: You’ll need to add a Git repository to Orca before configuring workspace automation. This setting is saved per repository, allowing different projects to use different setup commands.

This small automation can save a significant amount of time, especially when you’re working with multiple worktrees or frequently creating new AI coding sessions.

After saving your workspace setup, proceed to the next step: Start Work in Multiple Repositories.

Step 5: Add Your Git Repositories

The final setup step is to Start Work in Multiple Repositories. Instead of opening projects one at a time, Orca lets you add all of your frequently used Git repositories in one place. This makes it easy to switch between projects and start AI-assisted development without searching through folders.

To add a repository:

Click Add Project.
Browse to your local Git repository.
Select the project and import it into Orca.

Repeat the process for any additional repositories you work on regularly. Once added, they’ll appear in your Orca workspace, ready for creating worktrees, launching AI agents, and managing development tasks.

Tip: If you work across multiple client projects or open-source repositories, adding them all upfront makes it much easier to jump between projects without leaving Orca.

At this point, you’ve completed the initial setup. Orca is now configured with your preferred AI agent, CLI tools, integrations, and projects, so you’re ready to start building with AI-powered workflows.

Step 6: Try Multi-Tasking with Multiple Worktrees

Once the basic setup is complete, Orca introduces one of its most powerful features — Multi-tasking. This feature lets you work on multiple tasks simultaneously by creating separate Git worktrees for each one.

Each worktree is completely isolated, even if they belong to the same repository. This means you can develop different features, fix bugs, or experiment with new ideas in parallel without affecting one another.

To explore this feature, click Try it out. Orca will guide you through creating multiple worktrees, each with its own AI agent and dedicated workspace.

For example, you could have:

Worktree 1: Build a user authentication system using Claude.
Worktree 2: Create a new dashboard using Codex.

Both tasks run independently, allowing you to compare progress, review changes, and merge the best implementation when you’re ready.

Why it matters: Instead of waiting for one task to finish before starting another, Orca lets you run multiple AI coding sessions in parallel, helping you prototype, compare solutions, and ship features much faster.

After exploring multi-tasking, proceed to the final milestone: Use Orca’s Browser.

Step 7: Use Orca’s Built-in Browser

The final milestone in the onboarding process is to use Orca’s Browser. Orca includes a built-in Chromium-based browser that lets you inspect and interact with your web application without leaving the workspace.

One of its standout features is Design Mode. Instead of manually describing a UI issue to an AI agent, you can simply click on any element in your application. Orca automatically captures the selected element’s HTML, CSS, and a cropped screenshot , then sends that information directly to the AI agent as part of your prompt.

To enable this feature, click Install CLI & Skill if it hasn’t already been installed. Once enabled, your AI agents can use the browser to inspect pages, capture screenshots, and interact with web applications as part of their workflow.

This is especially useful for tasks such as:

Fixing UI bugs.
Improving layouts and styling.
Updating specific components.
Debugging frontend issues.
Generating design improvements directly from the live interface.

Why it matters: Instead of explaining a UI problem in words or taking screenshots manually, Orca provides your AI agent with the exact HTML, CSS, and visual context it needs, making frontend development much faster and more accurate.

With this step complete, you’ve finished the Getting Started guide. Your Orca workspace is now fully configured, and you’re ready to create your first project, launch AI agents, and start building with parallel worktrees.

Step 8: Verify the Orca CLI Installation

Although we installed the Orca CLI during the onboarding process, it’s a good idea to verify that everything has been configured correctly before moving on.

Open a new terminal and run:

orca --help

If the installation was successful, Orca will display the list of available commands and options instead of showing a command not found error.

You can also check the installed version by running:

orca --version

Seeing the version number confirms that the CLI is installed correctly and is available from your terminal.

From this point onward, you’ll be able to use the orca command to create worktrees, automate workflows, interact with browsers, and perform other tasks directly from the command line.

Step 9: Clone Your First Repository in Orca

Now that the onboarding is complete, it’s time to add your first project to Orca. Instead of cloning the repository from the terminal, Orca can clone it directly from a Git URL, making it quick to import a project and start working with AI agents.

Click Add Project , then choose Clone from URL. A dialog box will appear where you need to provide the repository details.

Fill in the Repository Details

Enter the following information:

Git URL: Paste the HTTPS or SSH URL of the Git repository you want to clone.
Parent Folder: Select the local directory where Orca should clone the repository.

For this guide, we’ll clone the official Orca repository:

https://github.com/stablyai/orca

Choose a destination folder on your machine — for example:

/Users/abcd/orca

After verifying both fields, click Clone.

Orca will download the repository, register it as a project, and prepare it for creating worktrees and launching AI coding agents.

Tip: You can clone any Git repository hosted on GitHub, GitLab, Bitbucket, or any Git server, provided you have the necessary access permissions.

Once the cloning process is complete, the repository will appear in your Orca workspace, and you’ll be ready to create your first worktree and start coding with AI agents in the next step.

Step 10: Explore the Orca Workspace

Once the repository has been cloned successfully, Orca opens it in its main workspace. This is where you’ll spend most of your time managing projects, launching AI agents, reviewing code, and working with multiple Git worktrees.

Let’s take a quick tour of the interface.

Projects Panel

On the left side, you’ll find the Projects panel. Every repository you add to Orca appears here, making it easy to switch between projects without leaving the application.

In our workspace, you can see two projects:

agentic-ai-ecosystem
orca

Each project displays its active Git branch, helping you quickly identify the repository you’re currently working on.

Integrated Terminal

The center of the workspace contains Orca’s built-in terminal. This behaves like a regular terminal, allowing you to run Git commands, install dependencies, start development servers, or execute any command required by your project — all without switching to another terminal application.

For example, you can run commands such as:

git status

pnpm install

pnpm dev

Or any other project-specific commands directly from the integrated terminal.

File Explorer

On the right side is the File Explorer , where you can browse your repository’s folders and files.

You’ll see the complete project structure, including directories like:

docs
src
mobile
native
tests
resources

You can expand folders, search for files, and open them directly inside Orca without needing a separate code editor.

Why This Workspace Matters

Orca combines your Git repositories , terminal , and project files into a single interface. As you continue through this guide, this workspace will also be used to create AI worktrees, launch coding agents, compare implementations, and review generated code.

With your repository now imported and the workspace ready, you’re all set to create your first AI worktree and begin building with Orca in the next step.

Step 11: Create Your First AI Worktree

This is where Orca starts to shine.

Click the + button or Create Worktree
Choose the Orca repository
Give the worktree a name (for example, documentation-update)
Select your default agent (Claude, Codex, OpenCode, etc.)
Enter a prompt
Create the worktree

This is the first real AI workflow.

Step 12: Launch Your First AI Coding Agent

With the worktree created, it’s time to start your first AI coding session. Orca supports multiple CLI-based coding agents, and for this guide we’ll use OpenCode.

When creating the worktree, we selected OpenCode as our AI coding agent. Because of that, Orca opens an OpenCode session inside the integrated terminal for this worktree, allowing us to immediately start chatting with the AI and assign coding tasks.

In this guide, we’re using the Poolside Laguna XS 2.1 (Free) model through OpenRouter. OpenRouter offers a variety of free AI models that you can use by simply adding your OpenRouter API key to OpenCode. At the time of writing, the model shown in our setup is poolside/laguna-xs-2.1:free , which is available free of charge for coding tasks.

You can also explore many other free models available on OpenRouter, including coding, reasoning, and general-purpose LLMs, and switch between them depending on your use case.

Why Use OpenRouter?

Using OpenRouter gives you several advantages:

Access to multiple AI models with a single API key.
Easily switch between free and paid models.
Compare different coding models without changing your workflow.
Experiment with the latest open-source models as they become available.

Start Your First Prompt

Now that OpenCode is running, simply type your prompt into the chat box. For example:

Analyze this repository and explain its architecture.

Review this codebase and suggest improvements for performance and maintainability.

Find potential bugs and recommend fixes.

Once you submit the prompt, OpenCode begins analyzing your repository and generates code, explanations, or suggestions directly within the worktree. From here, you can continue the conversation, refine the output, or compare the results with other AI agents by creating additional worktrees.

Step 15: Let the Agent Modify the Project

Now ask something like:

Improve the README.

Add installation instructions.

Create a CONTRIBUTING.md file.

Then demonstrate:

AI editing files.
Git diff.
Changed files.

Step 16: Review and Accept the Changes

Show:

Changed files.
Diff viewer.
Git status.
Commit changes.

Step 17: Compare Another Agent

This is where Orca becomes unique.

Create another worktree.

Choose Claude , Codex , or another supported agent.

Give the same prompt.

Compare:

Speed
Code quality
Explanation
Files changed

This demonstrates Orca’s biggest advantage: parallel AI development.

Conclusion

Orca is more than just another AI coding tool — it’s a complete workspace designed for modern AI-assisted software development. By bringing together Git worktrees, multiple AI coding agents, an integrated terminal, browser automation, and powerful collaboration features, Orca makes it easy to experiment with different approaches, compare results, and ship better code faster.

In this guide, we covered everything from installing Orca and completing the initial setup to creating worktrees, launching AI agents, and working with free models through OpenRouter. Whether you’re building solo projects, contributing to open source, or collaborating with a team, Orca provides a flexible workflow that keeps everything in one place.

Now it’s your turn. Install Orca, connect your favorite AI coding agent, create your first worktree, and experience how parallel AI development can streamline your workflow. As Orca continues to evolve with new features and integrations, it’s quickly becoming one of the most capable platforms for developers building with AI.