본문으로 건너뛰기

Deep Links

claude-cli:// URL을 README·문서·알림에 한 줄 박아두면, 클릭 한 번에 Claude Code가 그 프로젝트 폴더에서 미리 채운 프롬프트와 함께 열립니다. 프롬프트는 입력창에 들어가지만 자동 전송되지 않아 — 본인이 한 번 더 보고 Enter.

팁

Claude Code v2.1.91+에서 동작. 핸들러는 처음 인터랙티브 세션 시작 시 자동 등록 — 별도 설치 명령 X.

어디 박을 수 있나​

URL이라 링크가 들어가는 자리면 어디든:

  • 본인 프로젝트 README — "이 레포 셋업"·"새 기여자 온보딩" 시작 prompt
  • 모니터링 알림·대시보드 — 특정 메트릭 조사 prompt
  • CI 실패 알림 — 실패한 job 이름 미리 채움
  • 위키·노션·내부 문서 — 자주 하는 진단·점검 작업
GitHub Markdown은 claude-cli:// 차단

GitHub README·issue·PR·wiki는 http·https만 허용하고 다른 scheme은 strip. [label](claude-cli://...)이 label만 표시되고 링크 사라짐. 회피: code block 안에 URL 박아 사용자가 직접 보고 주소창에 복붙.

동작 흐름​

[클릭] → 브라우저가 URL 넘김 → OS가 claude-cli:// 핸들러 인식
→ Claude Code 시작 → 지정 디렉토리에서 새 터미널 + 프롬프트 미리 채움
→ 본인이 읽고 Enter

링크 자체는 어디 있어도 되지만 세션은 항상 클릭한 컴퓨터에서 로컬로 열림.

URL 만들기​

모든 deep link는 claude-cli://open으로 시작. 옵션 query parameter로 위치·프롬프트 제어:

파라미터설명
q입력창에 미리 채울 텍스트. URL-encode 필수. 줄바꿈은 %0A. 최대 5,000자
cwd작업 디렉토리 절대 경로. 네트워크·UNC 경로는 거부
repoGitHub owner/name 슬러그. Claude Code가 본인이 전에 쓴 로컬 clone 경로를 찾아 거기서 시작. 없으면 홈 디렉토리에서 시작

cwd와 repo 둘 다 보내면 cwd가 이김.

실전 예시​

본인 README에 박을 deep link — acme/payments 레포에서 두 줄 진단 prompt 미리 채우기:

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

클릭하면 새 터미널이 본인 로컬 acme/payments clone에서 열리고 입력창에:

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

이미 채워진 상태. 본인이 한 번 더 보고 Enter.

cwd vs repo​

  • cwd: 모두가 같은 절대 경로에 프로젝트 가지고 있을 때 (표준화된 devcontainer·VM 이미지)
  • repo: 사람마다 clone 위치 다른 공유 링크. Claude Code가 본인이 그 레포에서 claude 마지막 실행한 경로를 찾아 거기서 시작

repo는 본인이 그 레포에서 최소 한 번 claude 실행한 적 있어야 경로 찾음. 처음 보는 레포면 홈 디렉토리에서 열림.

스크립트·alias·자동화에서 호출:

macOS:

open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Linux:

xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Windows PowerShell:

Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Windows cmd.exe: (첫 인자가 윈도우 제목으로 처리되니 빈 제목 먼저)

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

보안 — 신뢰 안 되는 링크 클릭하면?​

Deep link 자체는 아무 코드도 실행 X. 디렉토리 선택 + 입력창에 텍스트 채움이 전부. 모델한테는 본인이 Enter 누르기 전까지 아무것도 안 감.

세션 열리면 입력창 위 배너에 — 외부 링크가 시작했다 + 어느 디렉토리 표시. 1,000자 넘는 긴 프롬프트면 "스크롤해서 전체 검토 후 Enter" 안내. 권한 룰·CLAUDE.md·디렉토리 신뢰 프롬프트는 일반 세션과 동일하게 작동.

핸들러 등록 끄기​

조직 전체 또는 본인 PC에서 등록 막으려면 settings.json에 disableDeepLinkRegistration: "disable". 조직 강제는 managed settings로 전달.

핸들러 위치:

플랫폼위치
macOS~/Applications/Claude Code URL Handler.app
Linux~/.local/share/applications/claude-code-url-handler.desktop
WindowsHKEY_CURRENT_USER\Software\Classes\claude-cli

트러블슈팅​

증상원인
클릭해도 아무 일 없음핸들러 미등록 — claude 한 번 인터랙티브 실행 후 재시도. Linux 데스크탑 환경 없으면 xdg-open이 dispatch 불가
링크가 plain text로 표시GitHub Markdown처럼 claude-cli:// strip하는 플랫폼. URL을 code block에 박아 사용자가 복붙
repo 지정했는데 홈 디렉토리에서 열림그 clone에서 claude 실행 기록 없음 — clone 안에서 claude 한 번 실행해 경로 등록
의도와 다른 터미널이 열림macOS는 본인이 마지막에 claude 실행한 터미널 기억. Linux는 $TERMINAL 환경변수 우선. Windows는 Windows Terminal → PowerShell → cmd.exe 고정 순서

VS Code 탭으로 열기 (다른 핸들러)​

VS Code 확장은 별도 vscode://anthropic.claude-code/open 핸들러 등록 — 터미널 대신 Claude Code 에디터 탭이 열림. 공식 VS Code 페이지 참고.

정리​

  • claude-cli://open?repo=owner/name&q=prompt가 기본 형식
  • q는 URL-encode 필수, %0A로 줄바꿈, 최대 5,000자
  • repo는 본인이 그 레포에서 claude 실행 기록 있어야 작동
  • README·런북·알림에 박아 한 번 클릭에 작업 시작
  • Deep link 자체는 코드 실행 X — Enter 누르기 전까지 모델한테 안 감

본 챕터는 공식 deep-links 페이지를 베이스로 한국어 시청자용으로 정리.

다음 챕터: 설정 디버깅 →

최종 수정: 에