코딩 에이전트의 제어 평면: ADHDev

코딩 에이전트를 위한 제어 평면: 모든 기기의 모든 에이전트를 한눈에 보고, 공유 작업 큐를 사용하며, 테스트를 통과한 작업만 main 브랜치에 도달하게 합니다. AI 코딩 에이전트가 장시간 실행되는 백그라운드 워커가 되었습니다. ADHDev는 이들을 위한 제어 평면입니다: 웹 또는 모바일 대시보드에서 Claude Code, Codex, Kimi, Cursor CLI, Antigravity CLI 등 여러 에이전트 세션을 시작하고, 관찰하고, 승인하고, 조향할 수 있으며, 완료된 작업을 main에 병합하는 무인 파이프라인으로 전환합니다.

. 충돌 없는 병렬 에이전트: 모든 작업은 자체 git worktree에서 실행됩니다. Refinery 게이트가 완료된 작업을 검증하고 main에 rebase한 후, main이 움직이지 않았을 때만 병합하며 — merge-day hangover(병합일의 숙취)는 없습니다.

웹사이트: adhf.dev · 문서: docs.adhf.dev

단 하나의 명령어로 사용해 보세요: npx @adhdev/daemon-standalone를 실행한 다음, http://localhost:3847을 엽니다.

작동 방식 (The loop): 채팅에서 작업을 설명 → 코디네이터가 이를 파일로 만들고, 태그를 지정하고, 큐에 넣음 → 유휴 상태의 기기가 새로운 worktree로 이 작업을 가져옴 → 리포지토리 자체 게이트가 결정함 → main에 rebase된 후, main이 움직이지 않았을 때만 병합되고, worktree는 사라짐. 휴대폰은 승인이 필요한 경우에만 진동합니다.

ADHDev는 이런 방식으로 구축되었습니다. ADHDev가 개발되는 비공개 모노레포지토리에서 — 이 엔진은 서브모듈로 게시됩니다 — main 커밋의 약 6분의 1이 Refinery를 통한 자동 병합 (Auto-merge via Refinery) 커밋입니다: 에이전트가 완료하고, 리포지토리 자체 게이트가 승인했으며, 사람이 git merge를 실행하지 않고도 Refinery가 도달한 작업입니다. 이 기록은 상위 모노레포지토리에 존재하므로, 이 공개 미러의 로그에는 이러한 병합 커밋이 표시되지 않습니다.

(단일 머신 메시는 완전히 로컬에서 실행됩니다. 여러 머신에 걸쳐 확장하려면 클라우드 에디션이 필요합니다.) 의존성이 있는 작업을 큐에 넣고 코디네이터가 여유 용량을 가진 노드(사용자의 노트북, 데스크톱, 빌드 박스 등)로 분배하도록 맡기세요. 이것은 단순히 하나의 호스트에 SSH 접속하는 것이 아니라 P2P 메쉬를 통한 진정한 다중 머신 오케스트레이션입니다. 각 작업은 자체 워크트리에서 실행되므로 에이전트들이 서로 간섭하지 않습니다. 이 메쉬와 Refinery 엔진은 이 리포지토리에 포함되어 있으며, 크로스-머신 분배는 클라우드 에디션에서 작동합니다.

메시는 하나의 git 저장소에 바인딩되며 사용자가 수동으로 조정해야 할 움직이는 부분들을 소유합니다:

작업 큐 (Task queue) |
풀 기반(Pull-based). 대기 중 → 할당됨 → 완료/실패 상태를 가지며, depends_on 순서 지정과 재시도 기능을 지원합니다. 유휴 노드는 스스로 작업을 가져가므로 동기화에서 벗어나지 않도록 푸시 스케줄러가 필요하지 않습니다. |
미션 (Missions) |
여러 작업을 그룹화한 목표로, 따라서 재시작된 코디네이터는 모든 것을 다시 큐에 넣는 대신 마지막 작업이 중단된 지점부터 이어서 진행합니다. |
워크트리 노드 (Worktree nodes) |
병렬 작업당 격리된 브랜치 체크아웃으로, 어떤 작업이 분배되기 전에 자동으로 부팅(설치, 네이티브 리빌드, gitignore 빌드 출력)됩니다. |
추가 전용 원장 (Append-only ledger) |
모든 분배, 완료, 실패, 정지, 체크포인트가 메쉬의 로컬 SQLite 저장소에 추가 전용 기록으로 남습니다. 이는 사후적으로 '실제로 무슨 일이 일어났는지' 답변할 수 있게 만드는 감사 추적(audit trail)입니다. |
운영 노트 (Operating notes) |
런타임에 기록된 교훈(제공자 특이점, 복구 절차 등)은 모든 미래 코디네이터 프롬프트에 주입되어 지식이 학습한 세션보다 오래 지속되게 합니다. |
실시간 상태 프롬프트 (Live-state prompt) |
코디네이터의 시스템 프롬프트는 정적인 텍스트가 아닙니다. 시작할 때에는 실시간 메쉬 상태(노드 상태, 활성 미션, 최근 실패, 축적된 노트)를 렌더링한 것이며, 런타임 중 이벤트 발생 시 폴링하는 대신 세션에 주입됩니다.

| 난이도 및 할당량 라우팅 | 작업을 쉬움/보통/어려움으로 태그하면 해당 등급에 맞는 노드 슬롯(제공자, 모델, 사고 수준, 병렬 처리 용량)이 이를 가져갑니다. 따라서 일상적인 작업은 저렴한 모델에서 실행되고 어려운 작업만 값비싼 모델을 사용하게 됩니다. 각 머신은 또한 모든 CLI 구독의 남은 5시간 및 주간 기간을 읽습니다. 거의 소진된 플랜은 건너뛰어지며(작업이 대기하거나 노드의 다음 제공자로 넘어감), 나머지 할당량 중에서는 다음 초기화 시점까지 사용되지 않고 만료될 할당량이 먼저 소모됩니다. 어떤 작업도 실행되기 전에 대시보드에서 난이도별 라우팅 예측을 확인할 수 있습니다. |
| 작업 체이닝 | depends_on을 사용하여 작업을 연결합니다. 종속된 작업은 선행 작업이 완료될 때까지 기다린 후, 그들의 완료 요약 정보를 "Upstream results" 부록으로 받습니다. 실패하거나 취소된 선행 작업은 하위 체인을 유지(또는 메시 정책에 따라 취소)하고 코디네이터에게 알립니다. mesh_enqueue_batch는 이미 확인된 여러 작업을 단일 원자적 호출로 예약합니다. |

모든 머신은 각 CLI 구독의 남은 5시간 및 주간 기간을 읽습니다. 작업이 할당될 때, 거의 소진된 플랜은 건너뛰어지며(작업이 대기하거나 해당 머신의 다음 CLI로 넘어감), 나머지 중에서는 다음 초기화 시점까지 사용되지 않고 만료될 할당량이 먼저 소모됩니다. Machines 페이지는 전체 플릿을 하나의 그리드에 보여주며, 메시의 Tasks 탭은 어떤 작업도 실행되기 전에 각 난이도별로 다음 작업을 어떤 슬롯이 가져갈지 예측합니다.

병렬 처리는 실제로 작업이 병합될 때만 효과를 발휘합니다. Refinery는 리포지토리별 검증 게이트, 패치 등가성 확인, 서브모듈 인식 리베이스-및-병합(main 브랜치가 이동하지 않은 경우에만), 그리고 자동 워크트리 정리 기능을 통해 완료된 작업을 수렴시킵니다—사용자의 개입 없이 자동으로 처리합니다. 에이전트들이 작업을 마치면, Refinery가 이를 최종적으로 반영합니다. 위의 메시 보드는 파이프라인을 실시간으로 보여줍니다: 대기열을 통과하는 작업들, 수렴 과정이 진행되는 동안의 정제(refine) 작업들, 그리고 활동 피드에 기록된 모든 전송, 완료 및 중단 상태입니다.

병렬 워크트리(Parallel worktrees)와 무인 병합(unattended merges)은 git submodule이 등장하는 순간 취약해집니다. ADHDev는 이 경우를 정면으로 다룹니다. 실제로 이 프로젝트 자체가 서브모듈 모노레포(submodule monorepo, 루트 레포에 AGPL 엔진과 프로바이더 카탈로그가 서브모듈로 포함된 형태)이며, 저희는 매일 이 위에서 메시와 Refinery를 테스트합니다. Refinery는 수렴 과정 중 서브모듈을 일급 시민(first-class)처럼 취급합니다:

도달 가능성 게이트 (Reachability gate) — 루트 브랜치가 main에 도달하기 전에, 참조된 서브모듈 커밋이 해당 서브모듈의 origin/main에서 도달 가능한지 확인합니다. 그렇지 않다면, 해당 커밋들이 게시될 때까지 작업은 차단(blocked) 상태로 유지됩니다.패치 동등성 감지 (Patch-equivalence detection) — 서브모듈 커밋이 리베이스되거나 스쿼시되어 SHA가 변경되더라도, Refinery는 이미 내용물이 도착했는지 여부를 판단하므로 이중 병합을 하거나 잘못된 분기(divergence) 플래그를 지정하지 않습니다.원자적 포인터 증가 (Atomic pointer bumps) — 서브모듈 포인터 증가는 루트 변경과 함께 수렴하므로, 무인 병합이 root가 손상되거나 유령(dangling) 서브모듈 커밋을 가리키는 상태로 남지 않습니다.

사용자는 한 곳과 소통합니다. 코디네이터가 모든 워커와 머신을 비동기적으로 오케스트레이션하며 — 사용자가 기다릴 필요 없이 이벤트에 반응합니다. 세션 감시(session babysitting)가 필요 없습니다. 각 에이전트 창 앞에 앉아 완료를 지켜보는 대신, 작업을 단일 코디네이터에게 맡깁니다. 이 코디네이터는 모든 워커를 병렬로 구동하고, 실제 완료, 승인 또는 상태 이벤트가 도착했을 때만 반응합니다 — 폴링(polling)도, 차단 대기(blocking waits)도 없습니다. 사용자에게는 하나의 대화창이 제공되고, 그 밑단에는 비차단 이벤트 루프(non-blocking event loop)가 작동합니다.

에이전트는 로컬에서 실행되지만, 사용자는 어떤 브라우저에서도 이를 관찰하고 구동할 수 있습니다. 이 대시보드는 실제 제어 표면입니다 — 활성 세션을 검사하고, 채팅 및 터미널 상태를 읽고, 작업을 승인하거나 중단하며, 올바른 히스토리를 다시 열고, 브라우저나 휴대폰에서 다음 명령을 보낼 수 있습니다. 터미널 감시가 필요 없습니다. 승인 푸시는 명령어 자체의 시작 부분을 담고 오기 때문입니다. 예를 들어 rm -rf build/를 승인하거나 git push --force를 승인하는 경우에 그렇습니다.

다른 반응 시간을 요구합니다: 푸시가 도착하면 → 탭하고 → 한 번의 탭으로 승인합니다 (push-to-phone은 클라우드 에디션과 함께 제공됩니다).

|
|

중요한 읽기 전용 조사 — 버그 RCA, 디자인 검토, 감사 — 코디네이터에게 제2의 의견을 요청하세요: 이는 서로 다른 프로바이더의 2~3명의 작업자에게 동일한 질문을 보내고, 그들의 보고서를 기다린 다음, 어디에 동의하고, 어디에 이견이 있으며, 어떤 주장이 오직 한 명만이 했는지 정리해 줍니다. 높은 합의가 옳다는 것과 같지는 않습니다 — 같은 모델이라도 같은 컨텍스트에서는 같은 실수를 반복하기 때문입니다 — 따라서 의견 불일치가 읽을 가치가 있는 부분입니다.

채팅, 명령어, 스크린샷 및 원격 입력은 암호화된 WebRTC 데이터 채널을 통해 대시보드와 데몬 간에 직접 전송됩니다. 서버는 로그인, 시그널링 및 경량 메타데이터를 처리하며, 한 가지 의도적인 예외가 있습니다: 클라우드 에디션에서는 푸시 알림을 구축하기 위해 승인 프롬프트(명령어 및 버튼 레이블)를 수신하고, 푸시는 최대 80자까지 표시됩니다. 채팅, 터미널 출력 및 코드는 다른 사람의 장치에 저장되지 않습니다. 이것은 업셀링이 아니라 디자인의 신뢰 속성입니다.

Claude Code Remote Control, Codex Remote: 휴대폰으로 단일 공급업체의 세션을 구동하는 데 탁월합니다. ADHDev는 여러 공급업체와 머신이 공유하는 큐를 추가하고, 그들 사이의 할당량 인식 라우팅 및 테스트 게이트 병합을 추가합니다. 하나의 CLI를 하나의 머신에서 실행하는 경우, 내장된 원격 기능만으로 충분할 수 있습니다.Paseo, Happy: 코딩 에이전트를 위한 오픈 소스 원격 제어 및 모바일 앱입니다. ADHDev의 초점은 프롬프트 이후의 작업에 맞춰져 있습니다: 유휴 머신들이 작업을 가져오고, 각각 고유한 워크트리에서 처리하며, 테스트를 통과한 작업만이 main 브랜치에 반영됩니다.

.Conductor, Superset, Vibe Kanban: 워크트리 내의 병렬 에이전트로, 검토하고 병합할 diff 또는 PR로 끝납니다. ADHDev는 Mac, Windows 및 Linux 머신들이 가져오는 단일 큐를 실행하며, 게이트가 통과하면 자동으로 병합해 줍니다.

ADHDev는 사용자의 에이전트를 대체하거나 자체적으로 생성하지 않습니다. 대신, 이미 장치에 설치된 에이전트에 연결하여 제어 표면(control surface)을 제공합니다.

browser / phone
│ chat, commands, screenshots, remote input
▼
...

데몬이 통합 기능을 소유합니다. 세 가지 프로바이더 카테고리가 있습니다: cli (PTY), ide (Chrome DevTools Protocol), extension (CDP webview). 장기 실행 런타임은 별도의 프로세스입니다. adhdev-sessiond가 PTY를 소유하므로, CLI 세션이 데몬 재시작이나 업그레이드를 거쳐도 유지됩니다. 셀프 호스팅(Self-hosted)의 경우 직접 HTTP + WebSocket을 통해 localhost:3847에서 데몬과 통신합니다. 클라우드 에디션에서는 동일한 데이터가 WebRTC 데이터 채널(browser↔daemon)을 타고 전송되며, 서버는 시그널링만 수행합니다.

mesh_enqueue_task → SQLite 큐 (대기)
→ 유휴 노드가 이를 가져감 (할당)
→ 워커 에이전트가 자체 git worktree에서 실행됨
...

모든 것을 형성하는 네 가지 속성:

코디네이터는 구현하지 않고 라우팅합니다. 코드를 직접 읽거나 편집하기보다는 메시(mesh) 도구들을 오케스트레이션하므로, 컨텍스트가 작게 유지되고 소유권이 데몬 재시작에도 살아남습니다. 폴링(Polling)은 없습니다. 워커 완료, 승인 및 개선 보고서는 구조화된 report_completion 호출을 통해 발생 즉시 코디네이터 세션으로 직접 전달됩니다. 루프를 돌며 상태를 요청하는 것이 아니라, 이벤트에 따라 기다립니다. Git이 증거이며 에이전트의 말이 아닙니다.

독립 패키지로 직접 셀프 호스팅:

npm install -g @adhdev/daemon-standalone
adhdev-standalone

모든 것이 임베디드 대시보드가 있는 로컬 데몬으로 사용자의 장치에서 실행됩니다. 독립형 경로를 위해서는 클라우드 계정이 필요하지 않습니다. 두 패키지 모두 adhdev 명령어를 설치하므로, 둘 중 하나만 설치하고 둘 다 설치하지 마십시오.

클라우드 에디션 (여러 대의 장치, 푸시 알림):

curl -fsSL https://adhf.dev/install | sh # macOS / Linux
irm https://adhf.dev/install.ps1 | iex # Windows (PowerShell)
adhdev setup # 로그인 후 https://adhf.dev 열기

유용한 플래그:

adhdev standalone --host 0.0.0.0 # 동일 LAN의 다른 장치 허용
adhdev standalone --port 8080 # 사용자 지정 포트
adhdev standalone --token mysecret # 스크립트 / 운영자 액세스를 위한 토큰 인증
...

독립형은 기본적으로 localhost 전용입니다. LAN 액세스를 위해 0.0.0.0에 바인딩하는 경우, 토큰 인증이나 대시보드 비밀번호가 구성되지 않으면 대시보드가 경고합니다.

Windows 참고: Windows + Node.js 24+는 현재 일반 시작/설치 경로에서 차단됩니다. Node.js 22.x를 사용하거나 PowerShell 설치 프로그램(irm https://adhf.dev/install.ps1 | iex)을 사용하십시오 (문서 참조).

공식 셀프 호스팅 문서:

데몬 시작하기 — adhdev standalone을 실행한 다음, http://localhost:3847을 여십시오.