Shell 플러그인 아키텍처

Omarchy 데스크톱은 omarchy-shell이라는 단일 상주 Quickshell 프로세스로 실행되며, 화면에 보이는 거의 모든 구성 요소가 플러그인(Plugin) 형태로 동작합니다. 상단 바는 플러그인입니다. 상단 바에서 내려오는 제어 패널, 이모지 선택기나 클립보드 관리자와 같은 전체 화면 오버레이, Omarchy 메뉴 자체, 잠금 화면, Polkit 권한 인증 대화상자, 그리고 배터리 상태를 모니터링하고 야간 색온도를 조절하는 헤드리스 백그라운드 서비스까지 모두 플러그인입니다.

이는 단순한 내부 구현 방식이 아닙니다. 데스크톱의 특정 부분을 자유롭게 끄거나 교체할 수 있고, Omarchy 소스코드를 한 줄도 건드리지 않고 자신만의 컴포넌트를 직접 제작할 수 있음을 의미합니다.

공식 퍼스트 파티 플러그인은 Omarchy에 기본 내장되어 $OMARCHY_PATH/shell/plugins/에 위치합니다. 사용자가 직접 추가한 플러그인(개인 실험작이나 GitHub에서 다운로드한 커뮤니티 플러그인)은 ~/.config/omarchy/plugins/에 저장됩니다. 두 플러그인 모두 부팅 시 동일한 방식으로 자동 탐색되며, 유일한 차이점은 디스크 상의 저장 위치뿐입니다.

설치된 플러그인 목록 확인

omarchy plugin list

이 명령은 감지된 모든 플러그인의 ID, 활성화 여부, 퍼스트 파티/서드 파티 구분, 플러그인 유형(kinds), 표시 이름을 출력합니다. 다른 도구와 연동하려면 --json 옵션을 사용할 수 있습니다.

플러그인 ID는 네임스페이스로 격리됩니다. 내장 플러그인은 모두 omarchy.로 시작하며(omarchy.clock, omarchy.network, omarchy.notifications 등), 이 네임스페이스는 시스템 예약어이므로 서드 파티 플러그인이 사용할 수 없습니다.

플러그인 활성화 및 비활성화

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

또는 GUI 메뉴를 사용할 수 있습니다: Setup > Plugins에서 Enable(활성화), Disable(비활성화), Add(추가), Clone(복제), Remove(제거)를 지원하며, 각 항목별로 적절한 선택지가 필터링되어 나타납니다.

활성화 상태는 ~/.config/omarchy/shell.json에 저장됩니다. 서드 파티 플러그인은 해당 파일의 상단 바 레이아웃 항목, plugins[] 배열 또는 bar.id 등 어디에든 ID가 포함되면 활성화된 것으로 간주됩니다. 반면 상단 바 위젯이 아닌 퍼스트 파티 플러그인은 기본적으로 모두 켜져 있으며, disabledPlugins[]에 명시된 경우에만 꺼집니다.

전체 바 플러그인은 '꺼짐' 상태가 없습니다. 시스템에는 항상 정확히 하나의 상단 바가 필요하므로 다른 바 플러그인을 활성화하여 교체하는 방식을 사용합니다. 바 위젯 배치는 상단 바를 참조하세요.

Git에서 서드 파티 플러그인 추가하기

서드 파티 플러그인은 루트에 manifest.json이 포함된 Git 리포지토리입니다.

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

명령을 실행하면 먼저 플러그인이 셸 프로세스 내부에서 샌드박스 없이 임의의 코드로 실행됨을 명확히 알리고 URL을 보여주며 확인을 요청합니다. 플러그인은 정적 설정 파일이 아니라 사용자의 모든 권한을 가진 채 세션 내내 실행되는 실행 코드이므로 신뢰할 수 있는 리포지토리만 추가하고 활성화 전에 코드를 검토하시기 바랍니다.

확인 후 리포지토리를 스테이징 디렉터리에 클론하고 매니페스트를 검증합니다. 기존에 사용 중인 ID와 충돌하면 설치를 거부하고, 정상인 경우 ~/.config/omarchy/plugins/<id>/로 이동합니다. --enable을 붙이지 않은 경우 즉시 활성화할지 묻고, 거절 후 코드를 먼저 검토할 수 있습니다. 플러그인 내부 코드가 임의로 실행되거나 설치 훅이 동작하지 않으며 sudo 권한도 요구하지 않습니다. 파일 클론, 매니페스트 확인, IPC를 통한 상태 변경만 수행합니다.

업데이트는 해당 리포지토리의 fast-forward pull로 수행됩니다:

omarchy plugin update acme.weather
omarchy plugin update

ID 없이 실행하면 Git으로 관리되는 모든 플러그인을 일괄 업데이트합니다. 적용 전 diff를 보여주고, 로컬 변경 사항이 있으면 업데이트를 중단하며, 새 버전의 매니페스트 검증이 실패하면 자동 롤백합니다.

omarchy plugin remove acme.weather

플러그인을 제거하면 먼저 비활성화한 다음, Git 클론인 경우 삭제하고 심볼릭 링크인 경우 링크를 해제합니다. Git 리포지토리가 없는 수동 생성 플러그인 폴더는 삭제 대신 타임스탬프가 포함된 백업 디렉터리로 이동됩니다.

내장 플러그인 복제 및 수정

가장 강력한 커스터마이징 기능입니다. 공식 내장 위젯의 동작을 수정하고 싶을 때 $OMARCHY_PATH 아래의 파일을 직접 수정하지 마세요(패키지 업데이트 시 덮어쓰기됩니다). 대신 복제(Clone) 기능을 사용합니다:

omarchy plugin clone omarchy.clock

이 명령은 플러그인 전체를 ~/.config/omarchy/plugins/<username>.clock에 복사하고, 이름을 'My Clock'으로 변경하며, 자동으로 활성화하고 셸의 연결 대상을 공식 내장 버전에서 사용자의 복제본으로 전환합니다(기존 바 위치와 설정은 그대로 유지). --edit 옵션을 붙이면 새 디렉터리가 $EDITOR에서 즉시 열리며, 메뉴의 Setup > Plugins > Clone Plugin도 동일하게 작동합니다.

사용자 이름을 접두사로 사용하므로 ID 충돌이 발생하지 않으며 다른 사람과 공유해도 안전합니다. 기존 공식 ID(omarchy.clock)로의 호출이 사용자의 복제본으로 자동 라우팅되므로 다른 설정을 고칠 필요가 없습니다. 문제가 생기면 omarchy plugin remove <username>.clock을 실행하여 즉시 공식 내장 버전으로 복구할 수 있습니다.

~/.config/omarchy/plugins/ 아래의 파일을 저장하면 플러그인 코드가 즉시 핫 리로드되므로 에디터를 열어둔 채 변경 사항을 실시간으로 확인할 수 있습니다.

나만의 플러그인 만들기

플러그인은 manifest.json과 QML 파일들로 구성된 디렉터리입니다. 매니페스트는 schemaVersion: 1, id, name, version, 하나 이상의 kinds(유형), 그리고 각 유형별 QML 파일을 가리키는 entryPoints 객체를 선언합니다:

하나의 플러그인이 여러 유형을 동시에 선언할 수 있습니다(예: 미디어 플러그인은 service이자 bar-widget). 상단 바 위젯은 표시 이름, 카테고리, 기본 섹션(defaultSection), 다중 인스턴스 허용 여부(allowMultiple)를 포함하는 barWidget 블록을 가집니다.

배포 전 다음 명령으로 검증할 수 있습니다:

omarchy plugin validate ./my-plugin

이 명령은 셸이 로드 시 수행하는 것과 동일한 검사(스키마 버전, 필수 필드, 예약 ID 충돌 여부, 안전하고 실제 존재하는 진입점 경로, 선언한 모든 유형의 진입점 존재 여부, 심볼릭 링크 포함 여부 등)를 진행합니다.

자세한 내용은 Omarchy 리포지토리의 shell/README.md(매니페스트 스키마, IPC 명세, shell.json 구조) 및 shell/plugins/README.md(모든 공식 플러그인 ID, 유형, 진입점 목록)를 참조하세요.

전 세계와 플러그인 공유하기

플러그인을 완성했다면 공개 Git 리포지토리에 푸시하세요. 그것이 배포의 전부입니다. 다른 사람들은 omarchy plugin add <URL> 명령으로 몇 초 만에 설치하여 사용할 수 있습니다.

더 많은 사람들에게 알리기 위해 omarchyplugins.com에 등록해 보세요. Omarchy Shell 플러그인의 공식 커뮤니티 디렉터리이며, 개발을 시작하기 전에 이미 유사한 위젯이 만들어져 있는지 확인하기에 가장 좋은 곳입니다. 개발 전에 꼭 둘러보세요!