설치

최신 릴리스에서 .dmg를 받아 열고 dira.app을 응용 프로그램으로 끌어다 놓으세요. 업데이트는 앱이 스스로 받습니다.

필요한 것

준비할 것은 둘입니다. 지금 하나도 없어도 순서대로 따라오시면 됩니다.

1. Apple Silicon 맥

앱은 여기서만 돕니다. 화면 왼쪽 위 사과 메뉴에서 이 Mac에 관하여를 열어 보세요. 칩이 Apple M으로 시작하면 맞습니다. Intel 맥이라면 앱을 쓸 수 없습니다. 그 경우 아래 앱 없이 엔진만 쓰기로 가세요.

2. 엔진 설정하기

dira를 돌리려면 CLI로 부르는 LLM 엔진이 하나 있어야 합니다. 워커가 티켓을 맡아 띄우는 세션이 이것이라, 없으면 티켓이 대기에서 움직이지 않습니다. 기본값은 claude입니다.

방금 옮겨 놓은 dira.app을 열고 헤더 오른쪽 끝의 설정을 누르세요. 인증의 claude 항목에서 맨 윗줄을 봐주세요. 설치돼 있으면 claude CLI — 뒤에 앱이 찾은 경로가 붙습니다. 없으면 claude CLI를 찾지 못했습니다 — 워커가 세션을 띄우지 못합니다라고 나옵니다.

엔진을 설치하고 나면 앱을 껐다가 다시 열고 같은 자리를 보세요. 앱이 프로그램을 탐색할 경로 목록은 앱이 켜질 때 한 번 정해집니다. 그 줄이 경로로 바뀌어 있으면 준비가 끝났습니다.

워커가 티켓을 맡아 이 엔진을 실행하는 동안 macOS가 권한이나 키체인 접근을 물어올 수 있습니다. 그 창에는 dira라는 이름 대신 숫자(예: 2.1.222)가 뜹니다. 워커가 방금 설정한 CLI 엔진을 그대로 실행하기 때문입니다. 낯선 프로그램이 뜬 상황은 아닙니다. 그 엔진 자신이 필요해서 띄우는 창이니 허용해 주시면 됩니다.

python3와 bash는 macOS에 이미 있습니다. 엔진 자체는 그 둘의 표준 라이브러리만 쓰고, 페르소나와 프로토콜 패키지를 까는 apm 명령은 dira가 필요할 때 직접 설치합니다(아래 §새 기계에서 패키지 설치하기).

새 기계에서 패키지 설치하기

페르소나, 스쿼드, 프로토콜은 큐 폴더 안 .dira/team/ 아래에 패키지로 들어 있고, 무엇을 어떤 버전으로 쓰는지는 .dira/team/apm.yml과 .dira/team/apm.lock.yaml이 고정합니다. .dira는 통째로 gitignore라서 이 폴더는 프로젝트 저장소에 커밋되지 않습니다. 운영 정보는 프로젝트 코드와 따로 다루기 때문입니다. 그래서 저장소를 새 기계에 clone해도 팀 폴더는 따라오지 않습니다.

예전에는 이 폴더가 프로젝트 저장소의 dira-team/에 있었고 커밋 대상이었습니다. 그런 프로젝트는 업데이트할 때 마이그레이션 0003-team-into-queue가 옛 dira-team/을 .dira/team/으로 옮기고, 커밋돼 있던 dira-team/을 저장소에서 지우는 커밋을 한 번 냅니다. push는 하지 않으니 직접 하세요(아래 §업데이트한 뒤 화면이 흐려졌을 때).

큐 폴더를 다른 기계로 옮겨 왔거나 .dira/team/apm_modules/를 지웠다면 패키지를 한 번 깔아야 합니다. 명령은 하나입니다.

cd ~/Library/Application\ Support/dira/engine     # 앱에 들어 있는 엔진. 레포로 쓰면 그 clone 폴더
python3 dira_apm.py install <프로젝트 루트>

bash

<프로젝트 루트>는 .dira 폴더가 들어 있는 저장소 폴더입니다. .dira 폴더 자체가 아닙니다. 앱을 쓰면 이 명령을 직접 칠 일은 드뭅니다. 워커가 티켓을 가져가기 전에 설치 상태를 확인하고, lock과 다르면 스스로 한 번 설치하기 때문입니다. 이 명령이 하는 일은 넷입니다.

apm 명령이 없으면 먼저 깝니다. 버전은 엔진의 apm-version 파일 한 줄이 정하고(지금 0.33.0), 자리는 ~/.config/dira/tools/apm/<버전>/입니다. uv가 있으면 uv로, 없으면 3.10 이상의 python3.x로 그 자리에 가상환경을 만들어 깝니다. PATH에 따로 깔아 둔 apm은 쓰지 않습니다.
저장소 루트에 apm.yml이 있으면 거기서, .dira/team/apm.yml이 있으면 거기서 lock대로 설치합니다.
설치 결과를 검사합니다(check).
큐의 .dira/protocols/를 다시 씁니다(프로토콜).

맨 끝에 오류 줄이 없으면 끝입니다. 지금 깔린 상태만 확인하려면 install 자리에 check를 넣으세요. 설치하지 않고 어긋난 곳마다 한 줄씩 적어 주고, 어긋남이 있으면 rc 1로 끝납니다.

uv도 3.10 이상의 python3.x도 없으면 apm 설치 실패: uv도 python3.10 이상도 없다로 멈춥니다. macOS 기본 python3는 3.9라 해당하지 않습니다. uv를 깔고 다시 실행하세요.

`멈춤: 패키지 설치 상태가 lock과 다릅니다`

워커는 티켓을 가져가기 전에 그 프로젝트의 패키지가 lock과 같은지 확인합니다. 다르면 lock대로 한 번 설치해 보고, 그래도 다르면 그 프로젝트의 티켓을 가져가지 않습니다. 화면 맨 아래 status bar의 다음 디스패치 시계 뒤에 멈춤: 패키지 설치 상태가 lock과 다릅니다와 어긋난 내용 한 줄이 붙는 것이 이때입니다. 그 프로젝트의 runner.log에는 아래 줄이 남습니다.

SKIP apm 설치 상태가 lock과 다르다 - <어긋난 내용 한 줄>

text

같은 lock으로는 설치를 한 번만 시도하니 저절로 풀리지 않습니다.

위 §새 기계에서 패키지 설치하기의 명령을 그대로 실행합니다. 대부분은 이것으로 풀리고, 다음 tick에 워커가 다시 티켓을 가져갑니다.
그래도 같은 줄이 남으면 check가 낸 줄을 읽습니다. 줄은 아래 넷 중 하나로 시작합니다.
- 스킬 이름 충돌: <스킬> <- <패키지>, <패키지> - 두 패키지가 같은 이름의 스킬을 냅니다. 한쪽에서 그 스킬을 빼거나 이름을 바꿉니다.
- 페르소나 <이름>: skills.md의 <스킬>가 패키지 폐포에 없다 - 그 스킬은 다른 패키지에 깔려 있는데 이 페르소나 패키지와 그 의존성에는 없습니다. 페르소나 패키지의 .apm/skills/에 넣거나 그 스킬을 가진 패키지를 의존성으로 걸거나, skills.md에서 그 줄을 지웁니다.
- apm_modules 사본이 원본과 다르다: <패키지> 또는 원본 없음: <패키지> - 로컬 패키지를 고치거나 옮긴 뒤 다시 설치하지 않았습니다. 1의 명령을 다시 실행하면 됩니다.
- team: apm audit rc 1: ... - 깔린 파일이 lock과 다릅니다. 누군가 .dira/team/apm.yml만 고치고 lock을 새로 만들지 않은 경우가 많으니 .dira/team/apm.lock.yaml을 확인합니다. 의존성을 바꾼 것이 맞다면 그 폴더에서 ~/.config/dira/tools/apm/<버전>/bin/apm install로 lock을 새로 만듭니다. 커밋할 것은 없습니다.
고친 뒤 1의 명령을 한 번 더 실행합니다.

테스트처럼 워커가 설치를 시도하지 않게 하려면 환경변수 DIRA_APM_NO_INSTALL=1을 줍니다 (워커 환경변수). 다른 멈춤 이유와의 우선순위는 문제 해결의 표에 있습니다.

업데이트한 뒤 화면이 흐려졌을 때

2026-10-16 현재 이 화면은 아직 구현 중입니다. 아래 migrate.py 명령은 지금도 쓸 수 있습니다.

업데이트 중에는 프로젝트 폴더의 파일 형식이 바뀌는 경우가 있습니다. 그러면 앱을 다시 열었을 때 화면 전체가 흐려지고, 그 위에 dira를 업데이트하는 중입니다 창이 뜹니다. 고장이 아닙니다. 등록한 프로젝트를 새 형식으로 하나씩 옮기는 중이고, 다 끝나면 창이 저절로 닫힙니다. 그동안에는 아무것도 누르지 말고 기다리세요. 옮기는 동안에는 어느 프로젝트에서도 워커가 새 티켓을 가져가지 않습니다.

창에는 프로젝트마다 한 줄이 있습니다. 회색 점은 차례를 기다리는 중이고, 스피너 옆에는 지금 적용하는 항목이 보이며, 체크 표시는 끝났다는 뜻입니다. 진행 중인 세션 {n}개가 끝나기를 기다립니다가 보이면 그 프로젝트에서 아직 돌고 있는 세션이 있다는 뜻입니다. 세션을 끊지 않고 끝날 때까지 기다린 다음에 옮깁니다. 20분이 넘으면 버튼 둘이 나옵니다. 세션이 곧 끝날 것 같으면 20분 더 기다리기를, 그 프로젝트를 나중에 처리하려면 이 프로젝트 건너뛰기를 누르세요.

실패한 줄이 있으면 그 줄에 원인 한 줄, 로그 경로, 백업 경로가 나옵니다. 실패한 프로젝트는 바뀌기 전 상태로 이미 되돌려져 있고, 다른 프로젝트는 그대로 계속 진행됩니다. 원인 줄을 읽고 고칠 수 있는 문제(디스크가 꽉 찼다든지)였다면 고친 뒤 다시 시도를 누르세요. 원인을 모르겠거나 지금 시간을 쓰기 싫으면 이 프로젝트 건너뛰기를 누릅니다. 건너뛴 프로젝트는 줄에 건너뜀 - 이 프로젝트는 디스패치하지 않습니다가 붙고, 그 프로젝트의 티켓은 다시 적용할 때까지 아무도 가져가지 않습니다. 나머지 프로젝트는 평소대로 돕니다.

백업은 프로젝트마다 <프로젝트>/.dira/migrations/backup/<항목 ID>/<시각>/에 남습니다. 바뀌기 전 파일이 zip으로 묶이지 않은 원본 그대로 프로젝트 안 위치 그대로 들어 있습니다. dira는 이 폴더를 지우지 않으니 필요 없어지면 직접 지우세요. 무엇을 했는지는 <프로젝트>/.dira/migrations/migrate.log에 시각과 함께 한 줄씩 적혀 있습니다.

건너뛴 프로젝트를 나중에 적용하려면 터미널에서 아래처럼 실행합니다. 앱에 들어 있는 엔진은 ~/Library/Application Support/dira/engine/에 있습니다. <루트>는 그 프로젝트의 .dira 폴더입니다.

cd ~/Library/Application\ Support/dira/engine
python3 migrate.py list --root <루트>                 # 건너뜀으로 남은 항목 ID를 확인한다
python3 migrate.py apply --root <루트> --id <항목 ID>  # 그 항목을 적용한다

bash

건너뛴 항목이 여럿이면 ID마다 한 번씩 실행합니다. --id 없이 apply를 실행하면 건너뛴 항목은 그대로 남습니다. 남은 항목이 모두 적용되면 그 프로젝트도 다시 디스패치됩니다. 명령 전체는 CLI에 있습니다.

앱 없이 엔진만 쓰기

화면이 필요 없거나 Linux에서 돌리실 때입니다. 이 경우에는 레포를 직접 받습니다.

git clone https://github.com/proofer-tech/dira.git ~/Projects/dira

bash

워커 파일을 손으로 만들고 cron에 거는 절차는 부록 엔진만으로 돌리기에 있습니다. 앱을 같이 쓰셔도 상관없습니다. 앱은 자기 몫의 엔진을 번들 안에 따로 포함하고 있습니다. 둘 다 같은 큐 루트(<프로젝트>/.dira)만 보고 있으면 서로의 존재를 몰라도 한 프로젝트를 같이 운영합니다.

다음은 첫 프로젝트 만들기입니다.