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

Contributing to Omarchy requires forking the repository, running the comprehensive test suite via ./test/all, adhering to the commit conventions in 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, 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.

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

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:

./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 for the authoritative style guide and task-specific documentation. Use conventional commits with clear, atomic messages:

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

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:

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 conventions
• UI changes include visual verification as specified in agents/skills/visual-verification.md
• New functionality follows patterns established in migration scripts like migrations/1784950000.sh

Summary

• Start with the guide: Reference 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.
• 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 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.

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