링크로 세션 시작하기

claude-cli:// URL 하나로 Claude Code 터미널 세션을 열 수 있어요. 런북·알림·대시보드에 딥 링크를 심어 두면, 클릭 한 번으로 올바른 저장소에서 올바른 프롬프트가 채워진 상태로 Claude Code가 열리죠. 이 문서에서는 링크 만드는 법과 플랫폼별 등록·비활성화 방법을 다룹니다.

출처: 공식문서

본문

딥 링크는 새 터미널 창에서 Claude Code를 여는 claude-cli:// URL이에요. URL은 작업 디렉터리와 미리 채울 프롬프트를 실어 나를 수 있어요.

이 덕분에 작업의 원클릭 시작점을 공유할 수 있어요. Claude Code가 설치된 사람이 링크를 클릭하면 프롬프트가 이미 입력된 상태로 세션이 열리죠. 프롬프트는 채워질 뿐, Enter를 눌러야 전송돼요.

딥 링크는 URL이므로 링크를 넣을 수 있는 곳 어디든 넣을 수 있어요.

진단 프롬프트로 영향받은 서비스 저장소를 여는 인시던트 런북 단계
특정 메트릭에 대한 조사 프롬프트로 연결되는 모니터링 알림·대시보드
온보딩 프롬프트로 프로젝트를 여는 README·위키 페이지
실패한 작업 이름을 미리 채우는 CI 실패 알림

이 페이지는 링크 만들기, 런북에 임베드하거나 셸에서 실행하기, 플랫폼별 핸들러 등록·비활성화를 다뤄요.

딥 링크가 어떻게 동작하나요

claude-cli:// 접두사는 Claude Code가 운영체제에 등록하는 커스텀 URL 스킴으로, mailto: 링크가 이메일 클라이언트를 여는 것과 비슷해요. 딥 링크를 클릭하면 다음과 같이 동작해요.

브라우저나 앱이 URL을 운영체제에 넘겨요.
운영체제가 claude-cli:// 접두사를 인식하고 내 머신에서 Claude Code를 시작해요.
링크가 지정한 디렉터리에서 Claude Code가 실행되는 새 터미널 창이 열리고, 링크의 프롬프트 텍스트가 이미 입력 박스에 들어 있어요.
프롬프트를 읽고, 원하면 수정한 뒤 Enter를 눌러 전송해요.

링크 자체는 어디에나 호스팅할 수 있지만, 세션은 항상 클릭한 컴퓨터의 로컬에서 열려요. 운영체제별 어떤 터미널 에뮬레이터가 열리는지는 등록과 지원 플랫폼을 보세요.

링크를 표시하는 플랫폼은 커스텀 URL 스킴을 허용해야 해요. GitHub가 무엇을 하는지와 해결 방법은 링크가 클릭 가능 대신 일반 텍스트로 렌더링돼요를 보세요.

시작된 세션이 보여주는 것

딥 링크는 스스로 아무것도 실행하지 않아요. 링크는 디렉터리를 고르고 프롬프트 박스를 채울 뿐이죠. 신뢰하지 않는 페이지에서 링크를 클릭해도 프롬프트는 여전히 불활성 상태예요. 채워진 내용을 읽고 Enter를 누르기 전까지 모델에 아무것도 닿지 않아요.

세션이 열리면 입력 박스 아래 경고 줄에 Prompt from an external link가 나타나고, 프롬프트를 보내거나 지울 때까지 유지돼요. 프롬프트가 1,000자를 넘으면 경고가 문자 수를 포함하고, 긴 프롬프트는 화면 밖으로 지시를 밀 수 있으니 Enter 전에 전체 텍스트를 스크롤해 검토하라고 알려줘요. 선택한 디렉터리의 권한 규칙·CLAUDE.md·신뢰 프롬프트는 다른 세션과 똑같이 적용돼요.

링크 만들기

모든 딥 링크는 핸들러가 받아들이는 유일한 경로인 claude-cli://open으로 시작하고, 그 뒤에 선택적 쿼리 파라미터가 이어져요. 최소 형태는 홈 디렉터리에서 빈 프롬프트로 Claude Code를 열어요.

claude-cli://open

페이지에 올리지 않고 링크를 시험해 보려면 브라우저 주소 표시줄에 붙여넣거나 셸에서 열면 돼요.

세션이 어디서 시작되고 프롬프트 박스에 무엇이 들어가는지 제어하는 파라미터를 추가하세요.

파라미터	설명
`q`	프롬프트 박스에 미리 채울 텍스트. 값을 URL 인코딩하세요. 여러 줄 프롬프트의 줄 바꿈은 `%0A`를 사용. 최대 5,000자
`cwd`	작업 디렉터리로 쓸 절대 경로. 네트워크·UNC 경로와 `..` 세그먼트, 보이지 않거나 양방향 제어 문자를 포함한 경로는 거부돼요
`repo`	GitHub `owner/name` 슬러그. Claude Code가 이전에 본 로컬 클론으로 해석해 그곳에서 시작해요. 일치하는 클론이 없으면 홈 디렉터리에서 세션이 열려요

cwd와 repo는 작업 디렉터리를 설정하는 두 방식이에요. 둘 다 넘기면 cwd가 우선하고 repo는 무시되며, cwd 경로가 존재하지 않아도 그래요.

다음 링크는 acme/payments라는 저장소를 두 줄 진단 프롬프트로 가리켜요. 직접 만들 때는 acme/payments를 내 저장소의 owner/name 슬러그로 바꾸세요.

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 로컬 클론에서 Claude Code가 시작되며, 프롬프트 박스에 디코딩된 텍스트가 채워져요.

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

Enter를 눌러 보내기 전에 프롬프트를 편집할 수 있어요. 클론·워크트리가 여러 개일 때 로컬 경로가 어떻게 선택되는지는 cwd와 repo 중 선택을 보세요.

cwd와 repo 중 선택

링크를 클릭하는 사람 모두가 프로젝트를 같은 절대 경로에 둘 때(표준화된 devcontainer나 VM 이미지 등) cwd를 쓰세요.

링크가 공유되고 각자가 다른 위치에 클론하는 경우 repo를 써요. Claude Code는 슬러그를 다음과 같이 로컬 경로로 해석해요.

repo는 가장 최근에 claude를 실행한 링크된 저장소의 클론·워크트리를 열어요. Git 저장소에서 claude를 실행할 때마다 Claude Code는 그 디렉터리 경로를 저장소의 GitHub owner/name 슬러그에 기록해요. 클론과 워크트리는 따로 추적돼요.
링크는 체크아웃된 브랜치를 바꾸지 않아요. 세션은 그 디렉터리가 현재 있는 상태로 열려요.

웰컴 헤더가 어떤 경로를 골랐는지 보여줘서 올바른 클론이 열렸는지 확인할 수 있어요.

예제

아래 섹션들은 딥 링크의 두 가지 흔한 사용법을 보여줘요. 문서의 Markdown 링크와 스크립트·셸 별칭의 명령이에요.

런북에 링크 임베드

런북의 딥 링크는 트리아지하는 사람에게 올바른 저장소에서 준비된 프롬프트로 조사를 시작하는 원클릭 방법을 줘요. 런북을 렌더링하는 플랫폼은 커스텀 URL 스킴을 허용해야 해요. GitHub 렌더링 Markdown은 claude-cli://를 허용하지 않아서, GitHub README·이슈·위키의 딥 링크는 클릭 가능한 링크 없이 라벨만 보여요. 해결 방법은 트러블슈팅 참고를 보세요.

프롬프트는 URL의 일부라 URL 인코딩해야 해요. 인코딩된 값을 만들려면 브라우저 콘솔의 encodeURIComponent나 아무 URL 인코더에 프롬프트 텍스트를 통과시키세요.

아래 예제는 web-gateway라는 서비스 인시던트 런북에 조사 진입점을 추가해요.

## web-gateway에서 높은 5xx 비율

1. PagerDuty에서 페이지를 승인하세요.
2. [게이트웨이 저장소에서 Claude Code 열기](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. #incident에 초기 조사 내용을 올리세요.

직접 런북에 쓰려면 acme/web-gateway를 내 서비스 저장소 슬러그로 바꾸세요. 그러면 Claude Code가 설치되고 그 저장소 로컬 클론이 있는 엔지니어가 2단계를 클릭해 프롬프트가 전송 준비된 상태로 조사를 시작해요.

셸에서 링크 열기

클릭 대신 셸 스크립트·별칭·자동화에서도 딥 링크를 열 수 있어요. 링크를 인자로 해서 운영체제의 URL 열기 명령을 호출하세요. 이 명령들은 머신에서 Claude Code가 대화형 세션의 첫 프롬프트를 보낼 때 등록하는 핸들러에 의존해요.

macOS: 내장 open 명령이 등록된 claude-cli:// 핸들러에 URL을 전달해요.

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

성공하면 Claude Code가 실행되고 프롬프트가 미리 채워진 새 터미널 창이 열려요.

Linux: 대부분 데스크톱 환경이 xdg-open을 제공하고, 이게 등록된 핸들러에 URL을 전달해요.

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

성공하면 Claude Code가 실행되고 프롬프트가 미리 채워진 새 터미널 창이 열려요. 셸이 xdg-open을 찾지 못한다고 하면 트러블슈팅을 보세요.

Windows: PowerShell에서는 Start-Process가 등록된 핸들러에 URL을 전달해요.

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

cmd.exe에서는 start가 첫 번째 따옴표 인자를 창 제목으로 취급하므로, URL 앞에 빈 제목을 전달하세요.

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

성공하면 Claude Code가 실행되고 프롬프트가 미리 채워진 새 터미널 창이 열려요.

등록과 지원 플랫폼

Claude Code는 macOS·Linux·Windows에서 대화형 세션의 첫 프롬프트를 보낼 때 claude-cli:// 핸들러를 운영체제에 등록해요. 프롬프트를 보내지 않고 claude를 시작하고 종료하면 등록되지 않아요. 별도 설치 명령은 없으며, 등록은 사용자 수준 위치에만 기록돼요.

플랫폼	핸들러 위치
macOS	`~/Applications/Claude Code URL Handler.app`
Linux	`$XDG_DATA_HOME/applications` 아래의 `claude-code-url-handler.desktop`, 기본 `~/.local/share/applications`
Windows	`HKEY_CURRENT_USER\Software\Classes\claude-cli`

핸들러는 감지된 터미널 에뮬레이터에서 Claude Code를 시작해요. macOS에서 Claude Code는 가장 최근 대화형 세션의 터미널을 기억해 재사용하며 iTerm2·Ghostty·kitty·Alacritty·WezTerm·Terminal.app을 지원해요. Linux에서는 $TERMINAL 환경 변수, 그다음 x-terminal-emulator, 그다음 흔한 에뮬레이터 목록을 존중해요. Windows에서는 Windows Terminal, 그다음 PowerShell, 그다음 cmd.exe를 선호해요.

등록을 완전히 막으려면 settings.json에서 disableDeepLinkRegistration을 "disable"로 설정하세요. 조직 전체에서 사용자가 다시 켤 수 없게 강제하려면 관리 설정에 설정하세요.

터미널 대신 VS Code 탭 열기

VS Code 확장은 vscode://anthropic.claude-code/open에 자체 핸들러를 등록해서, 터미널 창 대신 Claude Code 편집기 탭을 열어요. 그 URL의 파라미터는 다른 도구에서 VS Code 탭 실행을 보세요.

트러블슈팅

링크 클릭해도 아무 일도 안 일어나요

핸들러가 아직 등록되지 않았을 가능성이 커요. 등록은 세션이 시작될 때가 아니라 대화형 세션의 첫 프롬프트를 보낼 때 일어나요. 그 머신에서 대화형 claude 세션을 시작하고, 아무 프롬프트를 보내고, 종료한 뒤 링크를 다시 시도하세요. 데스크톱 환경이 없는 Linux라면 xdg-open이 보낼 대상이 없을 수 있어요.

Linux에서 xdg-open을 찾지 못해요

xdg-open 명령은 xdg-utils 패키지의 일부인데, 최소 서버 이미지·컨테이너·WSL 배포판은 종종 빼먹어요. 배포판 패키지 관리자로 xdg-utils를 설치하고 명령을 다시 실행하세요. 예를 들어 sudo apt install xdg-utils. 명령이 실행되는데 아무것도 열리지 않는다면 xdg-open이 디스패치할 데스크톱 환경이 없을 수 있어요. 링크 클릭해도 아무 일도 안 일어나요를 보세요.

링크가 클릭 가능 대신 일반 텍스트로 렌더링돼요

일부 Markdown 렌더러는 http와 https 링크만 허용하고 다른 URL 스킴은 제거해요. GitHub는 README·이슈·풀 리퀘스트·위키에서 이렇게 해요. [label](claude-cli://...)는 URL이 제거된 채 그냥 label로 렌더링돼요. 이런 플랫폼에서는 딥 링크를 코드 블록에 넣어 독자가 URL을 보고 브라우저 주소 표시줄에 붙여넣게 하세요.

세션이 저장소 대신 홈 디렉터리에서 열려요

repo 파라미터는 Claude Code가 이미 본 클론만 해석해요. 클론 안에서 claude를 한 번 실행해 Claude Code가 경로를 기록하게 하거나, 절대 경로의 cwd를 쓰도록 링크를 바꾸세요.

링크가 엉뚱한 터미널을 열어요

macOS에서 선호하는 터미널에서 claude를 한 번 시작하면 다음 딥 링크가 그걸 써요. Linux에서 $TERMINAL 환경 변수를 선호하는 에뮬레이터의 명령 이름으로 설정하세요. Windows에서는 순서가 고정이라, PowerShell·cmd.exe 창 대신 링크가 거기서 열리길 원하면 Windows Terminal을 설치하세요.

더 알아보기

Claude Code 세션을 실행하거나 확장하는 관련 방법을 다루는 페이지예요.

스킬: 긴 런북 프롬프트를 저장소의 /skill로 저장해서 딥 링크의 q 파라미터가 그 이름만 지칭하게 해요
비대화형 모드: 터미널을 열지 않고 스크립트에서 Claude를 실행하고 출력을 캡처해요