How to Contribute to the Orca Project: A Complete Guide

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) for parsing worktree IDs and [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. UI primitives live under src/renderer/src/components/ui/—see [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.

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), and run the UI-focused lint and typecheck.

Extending the worktree engine – Modify files in src/shared/ (such as worktree-id.ts or 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). Violations will block CI.

• Never hard-code colors or radii – Use CSS variables from 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 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), you must pass:

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. 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. 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, use the cva (class-variance-authority) pattern:

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 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:

// 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:

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:

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:

{
  "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 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 for worktree logic, 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 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 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 next to 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 and worktree-ownership.ts files. These functions must be platform-agnostic and include co-located unit tests (e.g., worktree-utils.test.ts). Avoid placing worktree logic in the renderer layer, as it must remain agnostic of Electron-specific APIs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}