시작하기
이 가이드는 처음 설치부터 ADHDev를 통해 첫 번째 AI 에이전트와 채팅하는 것까지 안내합니다. 약 5분이 소요됩니다.
ADHDev는 두 가지 모드로 실행됩니다. 시작하기 전에 하나를 선택하세요 — 설치 명령은 동일하지만 대시보드 URL과 계정 흐름이 다릅니다.
| Standalone | 클라우드 | |
|---|---|---|
| 계정 | 없음 | GitHub 또는 Google |
| 대시보드 | http://localhost:3000 | https://adhf.dev |
| 적합한 경우 | 단일 머신, 로컬 사용, 프라이버시 | 멀티 머신, 원격 접근, 공유 |
확실하지 않다면 Standalone으로 시작하세요. 재설치 없이 나중에 전환할 수 있습니다.
1단계 — CLI 설치
설치 스크립트를 실행하세요. 플랫폼을 감지하고 필요하면 Node.js를 설치하며 adhdev CLI를 PATH에 추가합니다.
macOS / Linux:
curl -fsSL https://adhf.dev/install | shWindows (PowerShell):
irm https://adhf.dev/install.ps1 | iexmacOS / Linux (Homebrew):
brew tap vilmire/adhdev
brew install adhdevHomebrew는 자체 Node.js 런타임을 함께 설치하므로 전역 npm 환경과 분리된 상태로 adhdev를 유지합니다. (위 설치 스크립트도 macOS에서 Homebrew가 있으면 자동으로 Homebrew 경로를 사용합니다.)
npm 경유 (모든 플랫폼):
npm install -g adhdevWARNING
Windows에서 Node.js 24+의 전역 npm 설치는 현재 지원되지 않습니다. PowerShell 설치 프로그램이 이식 가능한 Node.js 22 런타임을 자동으로 부트스트랩합니다.
기대 결과:
adhdev --version버전 번호가 출력됩니다. command not found가 표시되면 새 터미널 창을 열어보세요 — 설치 스크립트가 PATH를 User scope에 영구 등록하므로 재부팅 후에도 유효합니다. 재부팅 후에도 안 된다면 Windows PATH 트러블슈팅을 참고하세요.
그런 다음 최초 실행 마법사를 실행하세요:
adhdev setupStandalone의 경우 로컬 전용 옵션을 선택하세요 — 브라우저 로그인이 필요하지 않습니다. 클라우드의 경우 마법사가 adhf.dev에 대한 기기 인증을 위해 브라우저 탭을 엽니다. GitHub 또는 Google로 로그인하세요.
TIP
클라우드 로그인에는 OAuth 공급자의 인증된 이메일이 필요합니다. GitHub/Google 계정에 인증된 이메일이 없으면 어떤 계정을 연결할지 추측하는 대신 로그인이 거부됩니다.
기대 결과: 마법사가 Setup complete를 출력하고 데몬을 시작하는 명령을 알려줍니다.
2단계 — 대시보드 열기
Standalone
adhdev standalonestandalone 명령은 데몬(localhost:3847)과 대시보드(localhost:3000)를 함께 시작합니다.
브라우저에서 http://localhost:3000을 여세요.
기대 결과: 로컬 머신이 "온라인" 상태인 빈 머신 목록을 보여주는 대시보드가 로드됩니다. 로그인 화면 없음.
네트워크의 다른 기기에서 LAN 접근을 원한다면:
adhdev standalone --host 0.0.0.0 --token <some-secret>클라우드
adhdev daemon데몬이 api.adhf.dev에 연결하고, 이 머신을 등록하고, 머신 ID를 출력합니다.
브라우저에서 https://adhf.dev를 여세요. 필요하면 로그인하세요.
기대 결과: 대시보드 머신 목록에 몇 초 이내로 녹색 표시기와 함께 머신이 온라인 상태로 표시됩니다. WebRTC 채널이 올라오면 "P2P connected"가 표시됩니다.
머신이 나타나지 않으면:
adhdev doctor이 명령은 데몬 프로세스, WebSocket 연결, 로컬 프로바이더 레지스트리를 확인합니다. 대부분의 문제는 특정 수정 방법과 함께 플래그됩니다.
3단계 — 프로바이더 선택
프로바이더는 ADHDev의 하나의 AI 에이전트에 대한 어댑터입니다. 첫 사용에서 중요한 두 가지 카테고리:
- CLI 프로바이더 — Claude Code, Codex CLI, Antigravity CLI, Hermes CLI 같은 터미널 기반 에이전트. 데몬이 PTY 아래에서 실행하고 터미널을 대시보드로 파이핑합니다.
- IDE 프로바이더 — Cursor, VS Code, Antigravity, Windsurf 같은 실행 중인 에디터. 데몬이 Chrome DevTools Protocol(CDP)을 통해 연결하고 IDE 내부의 에이전트 패널을 읽고/씁니다.
ADHDev가 머신에서 감지한 것을 보려면:
adhdev detect기대 결과: 알려진 각 프로바이더에 대해 installed: yes/no가 있는 목록. yes로 표시된 것은 바로 실행할 수 있습니다.
권장 시작점
가장 원활한 첫 실행을 위해 이미 설치된 것 중 하나를 선택하세요:
- Claude Code (CLI) —
adhdev launch claude - Codex CLI —
adhdev launch codex - Cursor (IDE) —
adhdev launch cursor
adhdev launch는 데몬 아래에서 에이전트를 엽니다. IDE의 경우 CDP가 활성화된 상태로 에디터를 다시 실행합니다.
WARNING
adhdev launch <ide>는 CDP가 활성화된 상태로 시작할 수 있도록 IDE를 닫고 다시 엽니다. 먼저 작업을 저장하세요.
기대 결과: 대시보드에 에이전트에 대한 새 카드(또는 머신 뷰 내의 새 탭)가 나타나고 터미널 출력 또는 IDE 상태가 실시간으로 표시됩니다.
4단계 — 첫 번째 프롬프트 보내기
대시보드에서 방금 실행한 에이전트의 카드를 클릭하면 두 가지 뷰 중 하나가 나타납니다:
- CLI 뷰 — 하단에 입력창이 있는 라이브 터미널. 로컬 터미널에서 하듯이 프롬프트를 입력하고 Enter(또는 Send 클릭)를 누르세요.
- IDE 뷰 — 에디터 내부의 에이전트 패널을 미러링하는 채팅 패널. 프롬프트를 입력하고 Send를 클릭하세요.
간단한 것을 시도해보세요:
현재 디렉토리의 파일 목록을 보여주고 이것이 어떤 종류의 프로젝트인지 알려줘.
기대 결과:
- 프로바이더가 에이전트의 응답을 실시간으로 대시보드에 스트리밍합니다.
- CLI 에이전트의 경우 로컬 터미널에서 볼 수 있는 동일한 토큰이 표시됩니다.
- IDE 에이전트의 경우 모델이 생성함에 따라 채팅 버블이 업데이트됩니다.
- 에이전트가 발생시키는 도구/승인 프롬프트는 동일한 승인/거부 버튼과 함께 대시보드에 미러링됩니다.
프롬프트는 도착했지만 응답이 없는 경우:
adhdev status # 데몬 정상 작동?
adhdev provider list # 프로바이더 로드됨?
adhdev doctor # 인증 또는 네트워크 문제?에이전트 자체가 API 키나 로그인(Anthropic, OpenAI, Google 등)을 요청하면 에이전트 자체 UI 또는 ~/.config에서 처리하세요. ADHDev는 해당 자격증명을 저장하거나 프록시하지 않습니다 — 각 도구가 자체 인증을 유지합니다.
준비 완료
이제 데몬이 실행되고, 대시보드가 연결되고, ADHDev 전송을 통해 적어도 하나의 에이전트가 응답하고 있습니다.
다음 단계
- 대시보드 가이드 — 패널, 머신 스위처, 세션 공유
- CLI 에이전트 — PTY 세션 관리, 스크롤백, 재시작
- 원격 뷰 — 다른 기기에서 IDE 제어 (클라우드 전용)
- 멀티 머신 — 노트북 + 데스크탑 + 작업용 PC 연결 (클라우드 전용)
- 호환성 및 주의사항 — 검증된 것 vs 실험적인 것
- 문제 해결 — 일반적인 오류 및 수정
심화 학습
- 프로바이더 가이드 — 커스텀 프로바이더 작성
- 프로바이더 SDK — 매니페스트, TUI 프리미티브, 디버깅
- 아키텍처 — 데몬, 대시보드, P2P, 서버 (인프라 및 타이밍 값의 정보 출처)
제거
adhdev uninstall # 데몬 중지, ~/.adhdev/ 제거
npm uninstall -g adhdev # CLI 자체도 제거로컬 상태를 잃지 않고 계정을 전환하려면 대신 adhdev logout을 사용하세요.