# How to Contribute to the Orca Project: A Complete Guide

> Contribute to the Orca project by improving UI components, worktree logic, or build scripts. Follow design system guidelines and run CI checks before submitting PRs to stablyai/orca.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**You can contribute to Orca by fixing UI components in `src/renderer/src/components/ui/`, extending worktree logic in `src/shared/`, or improving build scripts in `config/scripts/`, provided you follow the cross-platform design system and run the full CI check suite locally before submitting a PR.**

Orca is an Electron-based IDE that enables developers to run multiple AI coding agents side-by-side in isolated Git worktrees. The `stablyai/orca` repository organizes its codebase into three distinct architectural layers, each with specific contribution pathways and testing requirements. Understanding these boundaries ensures your PR passes review without architectural violations.

## Understand the Three-Layer Architecture

The codebase splits responsibilities across **Core**, **Renderer**, and **CLI** layers. Knowing which layer owns your change prevents cross-boundary coupling.

### Core / Shared Layer

The **shared layer** handles worktree identifiers, filesystem paths, session state, and cross-platform utilities. Key files include [[`src/shared/worktree-id.ts`](https://github.com/stablyai/orca/blob/main/src/shared/worktree-id.ts)](https://github.com/stablyai/orca/blob/main/src/shared/worktree-id.ts) for parsing worktree IDs and [[`src/shared/worktree-ownership.ts`](https://github.com/stablyai/orca/blob/main/src/shared/worktree-ownership.ts)](https://github.com/stablyai/orca/blob/main/src/shared/worktree-ownership.ts) for SSH worktree permissions. When you modify this layer, you must add unit tests in the same directory.

### Renderer (UI) Layer

The **renderer process** displays the IDE interface, editors, terminals, and the worktree sidebar. It follows the **shadcn-ui** design system with style tokens defined in [`src/renderer/src/assets/main.css`](https://github.com/stablyai/orca/blob/main/src/renderer/src/assets/main.css). UI primitives live under `src/renderer/src/components/ui/`—see [[`button.tsx`](https://github.com/stablyai/orca/blob/main/button.tsx)](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/ui/button.tsx) for the standard component pattern.

### CLI / Build Layer

The **CLI and build infrastructure** includes packaging scripts, development servers, and release automation. These reside in `config/` and `scripts/`, with the Electron builder configuration tested via [`config/scripts/electron-builder-config.test.mjs`](https://github.com/stablyai/orca/blob/main/config/scripts/electron-builder-config.test.mjs).

## Three Ways to Contribute to Orca

Choose your contribution type based on the architectural layer you need to touch:

**Fixing a bug or adding a small UI improvement** – Edit a component in `src/renderer/src/components/ui/`, add a corresponding test file (e.g., [`button.test.tsx`](https://github.com/stablyai/orca/blob/main/button.test.tsx)), and run the UI-focused lint and typecheck.

**Extending the worktree engine** – Modify files in `src/shared/` (such as [`worktree-id.ts`](https://github.com/stablyai/orca/blob/main/worktree-id.ts) or [`workspace-statuses.ts`](https://github.com/stablyai/orca/blob/main/workspace-statuses.ts)) and include unit tests in the same folder to validate worktree parsing logic.

**Improving build scripts or CI** – Update the scripts in `config/scripts/` or the GitHub Actions workflows under `.github/workflows/`. Ensure you test the script locally before pushing.

## Follow Cross-Platform Design System Rules

All contributions must respect the **cross-platform** and **design-system** constraints documented in [[`docs/STYLEGUIDE.md`](https://github.com/stablyai/orca/blob/main/docs/STYLEGUIDE.md)](https://github.com/stablyai/orca/blob/main/docs/STYLEGUIDE.md). Violations will block CI.

- **Never hard-code colors or radii** – Use CSS variables from [`src/renderer/src/assets/main.css`](https://github.com/stablyai/orca/blob/main/src/renderer/src/assets/main.css). Always reference tokens like `bg-primary` or `rounded-md` instead of literal values.

- **Never use platform-specific shortcuts** – Choose `CmdOrCtrl` for accelerators. Display `⌘` on macOS and `Ctrl` elsewhere in UI labels (see the **Keyboard shortcut chips** section of the style guide).

- **Wrap shadcn primitives for new components** – Create a wrapper that forwards `className` to `cn()` and adds the `data-slot` attribute. Follow the pattern in [`src/renderer/src/components/ui/button.tsx`](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/ui/button.tsx) where the component wraps the base primitive.

## Validate Your Changes Locally

Before opening a PR, run the same checks that CI executes. According to [[`.github/CONTRIBUTING.md`](https://github.com/stablyai/orca/blob/main/.github/CONTRIBUTING.md)](https://github.com/stablyai/orca/blob/main/.github/CONTRIBUTING.md), you must pass:

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build

```

Run these commands in order. If `pnpm build` fails due to type errors or lint violations, the PR workflow will reject your submission.

## Submit Your Pull Request

The repository provides a GitHub PR template at [`.github/pull_request_template.md`](https://github.com/stablyai/orca/blob/main/.github/pull_request_template.md). Fill it out completely, including your X (Twitter) handle, a short description, and test instructions.

- **For UI changes:** Include a screenshot or short screen recording in the PR description.
- **For non-visual changes:** Explicitly state **"No visual changes"** in the description.

**Note:** Release creation is a maintainer-only workflow defined in [`.github/workflows/release-cut.yml`](https://github.com/stablyai/orca/blob/main/.github/workflows/release-cut.yml). Normal contributors should not modify version numbers, tags, or release notes.

## Code Examples

### Adding a New UI Button Variant

When extending the button component in [`src/renderer/src/components/ui/button.tsx`](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/ui/button.tsx), use the `cva` (class-variance-authority) pattern:

```tsx
import { cva } from 'class-variance-authority'

const buttonVariants = cva(
  "inline-flex items-center justify-center ...",
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground',
        destructive: 'bg-destructive text-white',
        // Add new variant below
        warning: 'bg-destructive text-white hover:bg-destructive/90',
      },
    },
    defaultVariants: { variant: 'default' },
  }
)

```

Add a test in [`src/renderer/src/components/ui/button.test.tsx`](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/ui/button.test.tsx) that renders the button with `variant="warning"` and asserts the presence of the `bg-destructive` class.

### Parsing Worktree IDs in Utilities

For logic involving worktree identifiers, import the parser from the shared layer:

```ts
// src/shared/worktree-utils.ts
import { splitWorktreeId } from './worktree-id'

export function getRepoName(worktreeId: string): string | null {
  const parsed = splitWorktreeId(worktreeId)
  return parsed?.repoId ?? null
}

```

Add a unit test in [`src/shared/worktree-utils.test.ts`](https://github.com/stablyai/orca/blob/main/src/shared/worktree-utils.test.ts):

```ts
import { expect, test } from 'vitest'
import { getRepoName } from './worktree-utils'

test('extracts repo ID from worktree string', () => {
  expect(getRepoName('my-repo::my/path')).toBe('my-repo')
})

```

### Updating CI Workflows

To add a new lint step for custom scripts, edit [`.github/workflows/pr.yml`](https://github.com/stablyai/orca/blob/main/.github/workflows/pr.yml):

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pnpm install
      - name: Run ESLint
        run: pnpm lint
      - name: Run New Linter
        run: pnpm lint:new-script

```

Then add the corresponding script to [`package.json`](https://github.com/stablyai/orca/blob/main/package.json):

```json
{
  "scripts": {
    "lint:new-script": "eslint scripts/**/*.mjs"
  }
}

```

## Summary

- **Orca's architecture** splits into three layers: `src/shared/` (core logic), `src/renderer/src/` (UI), and `config/scripts/` (build tooling).
- **Design system rules** prohibit hard-coded colors, platform-specific shortcuts, and unwrapped shadcn primitives—always use CSS variables from [`main.css`](https://github.com/stablyai/orca/blob/main/main.css) and the `cn()` utility.
- **Pre-submission requirements** include running `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build` locally.
- **PR etiquette** requires filling out the template, including screenshots for UI changes, and leaving version bumps to maintainers.
- **Key files** for reference include [`worktree-id.ts`](https://github.com/stablyai/orca/blob/main/worktree-id.ts) for worktree logic, [`button.tsx`](https://github.com/stablyai/orca/blob/main/button.tsx) for UI patterns, and `electron-builder-config.test.mjs` for build validation.

## Frequently Asked Questions

### Who can create releases in the Orca project?

Release creation is restricted to maintainers only. The workflow defined in [`.github/workflows/release-cut.yml`](https://github.com/stablyai/orca/blob/main/.github/workflows/release-cut.yml) handles versioning and tagging automatically. Contributors should never modify version numbers or create tags in their pull requests.

### What design system does Orca use for UI components?

Orca uses **shadcn-ui** with Tailwind CSS. All components must consume design tokens from [`src/renderer/src/assets/main.css`](https://github.com/stablyai/orca/blob/main/src/renderer/src/assets/main.css) rather than hard-coding values. When creating new components, you must wrap the base shadcn primitive, forward `className` through the `cn()` utility, and add the `data-slot` attribute.

### How do I test UI components locally?

Add a test file adjacent to your component (e.g., [`button.test.tsx`](https://github.com/stablyai/orca/blob/main/button.test.tsx) next to [`button.tsx`](https://github.com/stablyai/orca/blob/main/button.tsx)) using the project's testing framework. Run `pnpm test` to execute the suite. For manual verification, execute `pnpm build` to ensure the component renders without type errors, and include a screenshot in your PR description.

### Where should I add utility functions for worktree operations?

Place worktree-related utilities in `src/shared/` alongside the existing [`worktree-id.ts`](https://github.com/stablyai/orca/blob/main/worktree-id.ts) and [`worktree-ownership.ts`](https://github.com/stablyai/orca/blob/main/worktree-ownership.ts) files. These functions must be platform-agnostic and include co-located unit tests (e.g., [`worktree-utils.test.ts`](https://github.com/stablyai/orca/blob/main/worktree-utils.test.ts)). Avoid placing worktree logic in the renderer layer, as it must remain agnostic of Electron-specific APIs.