# How to Contribute to the Omarchy Project: A Complete Developer's Guide

> Learn how to contribute to the Omarchy project. Fork the repo, run tests, follow commit conventions, and submit pull requests with visual verification for UI changes.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Contributing to Omarchy requires forking the repository, running the comprehensive test suite via `./test/all`, adhering to the commit conventions in [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md), and submitting pull requests that include visual verification for any UI changes.**

Contributing to the Omarchy project follows a well-defined workflow that mirrors the repository's modular architecture. The main entry point for contributors is the **contributing guide** located at [`default/agents/skills/omarchy/contributing.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/contributing.md), which outlines everything from bug reporting to code submission standards. This guide covers the essential steps to ensure your contribution passes automated checks and aligns with the project's organizational structure.

## Understand the Repository Layout

Before writing code, familiarize yourself with how the Omarchy project organizes its source. The repository uses distinct directories for different concerns, as detailed in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md).

### Key Directories

- **`agents/skills/`** – Contains task-oriented guides for developers, such as instructions for adding commands or running migrations.
- **`docs/`** – Houses reference documentation about system architecture, menu schemas, and testing protocols.
- **`manual/`** – End-user documentation that gets published separately from the codebase.
- **`bin/`** – Exposed CLI commands prefixed with `omarchy-`. The authoritative list of command groups and their routing lives in `bin/omarchy` within the `GROUP_DESCRIPTIONS` definition.
- **`test/`** – Automated test suite with entry points at `./test/all`, `./test/cli`, and `./test/shell`.

## Report Issues Effectively

The contributing workflow distinguishes between bugs, feature requests, and support questions, routing each to the appropriate channel.

### Verified Bugs

For confirmed bugs, open a GitHub issue using the bug template. Include a diagnostic log generated according to the steps in [`default/agents/skills/omarchy/contributing.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/contributing.md) to help maintainers reproduce the issue.

### Feature Ideas

Propose new features by starting a discussion in the *Suggestions* category on GitHub rather than opening an issue. This allows the community to refine ideas before implementation begins.

### Support Questions

For general help or configuration questions, use the Omarchy Discord server instead of GitHub issues to keep the tracker focused on development work.

## Prepare Your Contribution

### Fork and Clone the Repository

Never develop directly in `/usr/share/omarchy`. Instead, create your own fork:

```bash
gh repo fork basecamp/omarchy --clone
cd omarchy
git checkout -b your-feature-branch

```

### Run the Test Suite

Execute the relevant test suites before committing to catch regressions early:

```bash
./test/all          # Runs CLI + shell tests (full suite)

./test/cli          # Focus on command routing and metadata

./test/shell        # Runs all shell-related tests

```

### Follow Style and Commit Conventions

Consult [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md) for the authoritative style guide and task-specific documentation. Use conventional commits with clear, atomic messages:

```text
feat(theme): add dark variant for white theme

- Update colors.toml
- Add preview-unlock.png

```

For UI-related changes, reference [`agents/skills/visual-verification.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/visual-verification.md) to ensure you include appropriate screenshots or before/after captures.

## Submit a Pull Request

Push your branch to your fork and open a PR using the GitHub CLI:

```bash
git push origin your-feature-branch
gh pr create --title "Your Feature Title" --body "Closes #123"

```

Include a concise description, links to related issues, and visual diffs for any interface modifications. For example, if modifying themes, you might change [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml):

```bash
sed -i 's/background = "#ffffff"/background = "#101010"/' themes/white/colors.toml

```

## The Review and Merge Process

Maintainers review contributions by running the full test suite and verifying coding style compliance. They specifically check that:

- All tests pass (`./test/all` exits clean)
- Commit messages follow the [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md) conventions
- UI changes include visual verification as specified in [`agents/skills/visual-verification.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/visual-verification.md)
- New functionality follows patterns established in migration scripts like [`migrations/1784950000.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1784950000.sh)

## Summary

- **Start with the guide**: Reference [`default/agents/skills/omarchy/contributing.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/contributing.md) for the complete workflow.
- **Fork, don't modify**: Clone your own fork rather than editing `/usr/share/omarchy` directly.
- **Test everything**: Run `./test/all` before submitting to catch regressions.
- **Write atomic commits**: Follow the conventional commit style documented in [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md).
- **Verify visually**: Include screenshots for any UI changes referencing the visual verification guide.
- **Use proper channels**: GitHub issues for bugs, Discussions for features, Discord for support.

## Frequently Asked Questions

### Where is the main contributing guide located?

The primary contribution documentation lives at [`default/agents/skills/omarchy/contributing.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/contributing.md) in the repository. This file contains the bug report template, diagnostic procedures, and workflow instructions that all contributors must follow.

### How do I add a new CLI command to Omarchy?

New commands belong in the `bin/` directory with the `omarchy-` prefix. You must also update the `GROUP_DESCRIPTIONS` array in `bin/omarchy` to register the command group. Refer to `agents/skills/` for task-specific guides on extending the CLI.

### What testing is required before submitting a pull request?

You must run `./test/all` to execute both CLI and shell tests. If your changes affect specific subsystems, you can run `./test/cli` for command routing validation or `./test/shell` for shell integration tests. The maintainer will run the full suite during review.

### Can I develop directly in `/usr/share/omarchy`?

No. The contributing guide explicitly prohibits developing in the system installation directory. Always fork the repository, clone to a working directory, and test there before submitting a pull request.