링크로 세션 시작하기 (Deep links)

기준일: 2026-10-23
공식 기준: Launch sessions from links

개요

Deep link는 새 터미널 창에서 Claude Code를 여는 claude-cli:// URL입니다. URL에 작업 디렉터리와 미리 채울 프롬프트를 실을 수 있습니다. Claude Code가 설치된 사람이 링크를 클릭하면 프롬프트가 이미 입력된 세션이 열리며, 프롬프트는 채워지기만 하고 Enter를 누를 때까지 전송되지 않습니다. 링크가 들어갈 수 있는 곳이면 어디든 쓸 수 있습니다.

영향받는 서비스의 repo를 진단 프롬프트와 함께 여는 장애 런북 단계
특정 메트릭의 조사 프롬프트로 연결되는 모니터링 알림·대시보드
온보딩 프롬프트와 함께 프로젝트를 여는 README·위키
실패한 job 이름이 채워진 CI 실패 알림

핵심 개념

항목	설명
URL 스킴	`claude-cli://`. Claude Code가 OS에 등록하며 `mailto:`와 유사
최소 형태	`claude-cli://open`: 홈 디렉터리에서 빈 프롬프트로 열림
`q`	프롬프트 박스에 미리 채울 텍스트. URL 인코딩 필수, 줄바꿈은 `%0A`, 최대 5,000자
`cwd`	작업 디렉터리 절대 경로. 네트워크/UNC 경로, `..` 세그먼트, 보이지 않는/양방향 제어 문자가 든 경로는 거부
`repo`	GitHub `owner/name` 슬러그. Claude Code가 이전에 본 로컬 clone으로 해석. 일치하는 clone이 없으면 홈 디렉터리에서 열림
우선순위	`cwd`와 `repo`를 둘 다 주면 `cwd`가 우선하고 `repo`는 무시(`cwd` 경로가 없어도)

상세

동작 방식

브라우저나 앱이 URL을 OS에 전달
OS가 claude-cli:// 접두사를 인식해 내 머신에서 Claude Code 시작
링크가 지정한 디렉터리에서 Claude Code가 실행되는 새 터미널 창이 열리고 링크의 프롬프트 텍스트가 입력창에 채워짐
프롬프트를 읽고 필요하면 수정한 뒤 Enter로 전송

링크 자체는 어디에 호스팅해도 되지만 세션은 항상 클릭한 컴퓨터에서 로컬로 열립니다. 링크를 표시하는 플랫폼은 커스텀 URL 스킴을 허용해야 합니다.

실행된 세션이 보여주는 것: deep link는 스스로 아무것도 실행하지 않습니다. 디렉터리를 고르고 프롬프트 박스를 채울 뿐이므로 신뢰하지 않는 페이지의 링크를 클릭해도 프롬프트는 비활성이며, 채워진 내용을 읽고 Enter를 누르기 전에는 모델에 아무것도 닿지 않습니다. 세션이 열리면 입력창 아래에 Prompt from an external link 경고 줄이 프롬프트를 전송하거나 지울 때까지 남습니다. 1,000자를 넘는 프롬프트는 긴 프롬프트가 지시를 화면 밖으로 밀어낼 수 있으므로 경고가 글자 수를 포함하고 Enter 전에 전체 텍스트를 스크롤해 검토하라고 안내합니다. 권한 규칙, CLAUDE.md, 선택한 디렉터리의 trust 프롬프트는 다른 세션과 같이 적용됩니다.

링크 만들기

링크는 claude-cli://open으로 시작하고 선택적 쿼리 파라미터가 따릅니다.

claude-cli://open

페이지에 올리지 않고 시험하려면 브라우저 주소창에 붙여넣거나 셸에서 엽니다. 파라미터로 세션이 시작하는 위치와 프롬프트를 제어합니다. 아래 링크는 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 clone에서 Claude Code가 시작되며 프롬프트 박스에 디코딩된 텍스트가 채워집니다.

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

전송 전에 프롬프트를 수정할 수 있습니다.

cwd와 repo 선택

cwd: 링크를 클릭하는 모든 사람이 프로젝트를 같은 절대 경로에 두는 경우(표준화된 devcontainer, VM 이미지)
repo: 링크를 공유하고 사람마다 clone 위치가 다른 경우. claude를 마지막으로 실행한 그 저장소의 clone 또는 worktree를 엽니다. Git 저장소에서 claude를 실행할 때마다 Claude Code가 그 디렉터리 경로를 저장소의 GitHub owner/name 슬러그에 대해 기록하며 clone과 worktree를 따로 추적합니다.
링크는 어느 브랜치가 checkout되어 있는지를 바꾸지 않습니다. 세션은 그 디렉터리의 현재 상태로 열립니다. 환영 헤더에 선택한 경로가 표시되어 올바른 clone이 열렸는지 확인할 수 있습니다.

예시

런북에 링크 삽입: 런북 렌더링 플랫폼이 커스텀 URL 스킴을 허용해야 합니다. GitHub 렌더링 Markdown은 claude-cli://를 허용하지 않아 README·issue·wiki의 deep link는 라벨만 보이고 클릭할 수 없습니다(우회법은 트러블슈팅). 프롬프트는 URL의 일부이므로 인코딩해야 하며 브라우저 콘솔이나 URL 인코더에서 encodeURIComponent로 변환합니다. web-gateway 서비스 장애 런북에 조사 진입점을 추가하는 예:

## High 5xx rate on web-gateway

1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](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. Post initial findings in #incident.

acme/web-gateway를 자기 서비스 저장소 슬러그로 바꿔 쓰세요. Claude Code가 설치되고 그 저장소의 로컬 clone이 있는 엔지니어가 2번 단계를 클릭해 프롬프트가 준비된 채 조사를 시작합니다.

셸에서 링크 열기: 스크립트, alias, 자동화에서 클릭 대신 열 수 있으며 OS의 URL 열기 명령에 링크를 인자로 넘깁니다. 머신에서 대화형 세션의 첫 프롬프트를 보낼 때 Claude Code가 등록하는 핸들러에 의존합니다.

macOS (open이 등록된 claude-cli:// 핸들러에 URL 전달):

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

Linux (대부분의 데스크톱 환경에서 xdg-open):

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

xdg-open을 찾을 수 없다고 나오면 트러블슈팅을 보세요. Windows PowerShell:

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:// 핸들러를 OS에 등록합니다. 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는 가장 최근 대화형 세션의 터미널을 기억해 재사용하며 iTerm2, Ghostty, kitty, Alacritty, WezTerm, Terminal.app을 지원합니다. Linux는 $TERMINAL 환경 변수, 그다음 x-terminal-emulator, 그다음 일반 에뮬레이터 목록을 따릅니다. Windows는 Windows Terminal, PowerShell, cmd.exe 순으로 선호합니다.

등록을 완전히 막으려면 settings.json에서 disableDeepLinkRegistration을 "disable"로 설정합니다. 조직 전체에 강제해 사용자가 다시 켜지 못하게 하려면 managed settings에 설정합니다. 이 설정은 claude-cli:// 링크만 다룹니다.

다른 진입점

터미널 대신 VS Code 탭: VS Code 확장은 vscode://anthropic.claude-code/open에 자체 핸들러를 등록해 터미널이 아니라 Claude Code 에디터 탭을 엽니다. 파라미터는 VS Code 문서를 보세요.
SSH 연결의 Claude Desktop 세션: Claude Desktop은 자체 claude:// 링크를 처리합니다. 원격 머신에서 SSH로 Desktop 세션을 열려면 Desktop 문서의 "Open an SSH session from a link"를 보세요.

트러블슈팅

클릭해도 아무 일 없음: 핸들러가 아직 등록되지 않았을 가능성이 높습니다. 등록은 세션 시작이 아니라 대화형 세션의 첫 프롬프트 전송 때 일어납니다. 그 머신에서 대화형 claude 세션을 시작해 아무 프롬프트를 보내고 종료한 뒤 링크를 다시 시도하세요. 데스크톱 환경이 없는 Linux에서는 xdg-open이 전달할 대상이 없을 수 있습니다.
Linux에서 xdg-open을 찾을 수 없음: xdg-utils 패키지의 명령으로 최소 서버 이미지, 컨테이너, WSL 배포판에 없는 경우가 많습니다. 예: sudo apt install xdg-utils 후 다시 실행. 실행은 되는데 아무것도 열리지 않으면 디스패치할 데스크톱 환경이 없는 것입니다.
링크가 클릭되지 않고 일반 텍스트로 렌더링: 일부 Markdown 렌더러는 http/https만 허용하고 다른 스킴을 제거합니다. GitHub는 README, issue, PR, wiki에서 이렇게 해서 [label](claude-cli://...)가 링크와 URL 없이 label로만 렌더링됩니다. 이런 플랫폼에서는 deep link를 코드 블록에 넣어 독자가 URL을 보고 브라우저 주소창에 붙여넣을 수 있게 하세요.
세션이 repo가 아니라 홈 디렉터리에서 열림: repo 파라미터는 Claude Code가 이미 본 clone으로만 해석됩니다. clone 안에서 claude를 한 번 실행해 경로를 기록하게 하거나 링크를 절대 경로 cwd로 바꾸세요.
엉뚱한 터미널이 열림: macOS는 선호 터미널에서 claude를 한 번 시작하면 다음 링크가 그것을 씁니다. Linux는 $TERMINAL 환경 변수를 선호 에뮬레이터 명령 이름으로 설정합니다. Windows는 순서가 고정이므로 링크가 PowerShell이나 cmd.exe 창 대신 Windows Terminal에서 열리길 원하면 Windows Terminal을 설치하세요.

함께 보기

Skills: 긴 런북 프롬프트를 repo의 /skill로 저장해 링크의 q는 이름만 지정
Non-interactive mode: 터미널을 열지 않고 스크립트에서 Claude를 실행해 출력 캡처
Server-managed settings
VS Code

링크로 세션 시작하기 (Deep links)

기준일: 2026-10-23
공식 기준: Launch sessions from links

개요

영향받는 서비스의 repo를 진단 프롬프트와 함께 여는 장애 런북 단계
특정 메트릭의 조사 프롬프트로 연결되는 모니터링 알림·대시보드
온보딩 프롬프트와 함께 프로젝트를 여는 README·위키
실패한 job 이름이 채워진 CI 실패 알림

핵심 개념

항목	설명
URL 스킴	`claude-cli://`. Claude Code가 OS에 등록하며 `mailto:`와 유사
최소 형태	`claude-cli://open`: 홈 디렉터리에서 빈 프롬프트로 열림
`q`	프롬프트 박스에 미리 채울 텍스트. URL 인코딩 필수, 줄바꿈은 `%0A`, 최대 5,000자
`cwd`	작업 디렉터리 절대 경로. 네트워크/UNC 경로, `..` 세그먼트, 보이지 않는/양방향 제어 문자가 든 경로는 거부
`repo`	GitHub `owner/name` 슬러그. Claude Code가 이전에 본 로컬 clone으로 해석. 일치하는 clone이 없으면 홈 디렉터리에서 열림
우선순위	`cwd`와 `repo`를 둘 다 주면 `cwd`가 우선하고 `repo`는 무시(`cwd` 경로가 없어도)

상세

동작 방식

브라우저나 앱이 URL을 OS에 전달
OS가 claude-cli:// 접두사를 인식해 내 머신에서 Claude Code 시작
링크가 지정한 디렉터리에서 Claude Code가 실행되는 새 터미널 창이 열리고 링크의 프롬프트 텍스트가 입력창에 채워짐
프롬프트를 읽고 필요하면 수정한 뒤 Enter로 전송

링크 만들기

링크는 claude-cli://open으로 시작하고 선택적 쿼리 파라미터가 따릅니다.

claude-cli://open

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에서 Claude Code가 시작되며 프롬프트 박스에 디코딩된 텍스트가 채워집니다.

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

전송 전에 프롬프트를 수정할 수 있습니다.

cwd와 repo 선택

cwd: 링크를 클릭하는 모든 사람이 프로젝트를 같은 절대 경로에 두는 경우(표준화된 devcontainer, VM 이미지)
repo: 링크를 공유하고 사람마다 clone 위치가 다른 경우. claude를 마지막으로 실행한 그 저장소의 clone 또는 worktree를 엽니다. Git 저장소에서 claude를 실행할 때마다 Claude Code가 그 디렉터리 경로를 저장소의 GitHub owner/name 슬러그에 대해 기록하며 clone과 worktree를 따로 추적합니다.
링크는 어느 브랜치가 checkout되어 있는지를 바꾸지 않습니다. 세션은 그 디렉터리의 현재 상태로 열립니다. 환영 헤더에 선택한 경로가 표시되어 올바른 clone이 열렸는지 확인할 수 있습니다.

예시

## High 5xx rate on web-gateway

1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](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. Post initial findings in #incident.

macOS (open이 등록된 claude-cli:// 핸들러에 URL 전달):

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

Linux (대부분의 데스크톱 환경에서 xdg-open):

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

xdg-open을 찾을 수 없다고 나오면 트러블슈팅을 보세요. Windows PowerShell:

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가 실행되고 프롬프트가 채워진 새 터미널 창이 열립니다.

등록과 지원 플랫폼

플랫폼	핸들러 위치
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`

다른 진입점

터미널 대신 VS Code 탭: VS Code 확장은 vscode://anthropic.claude-code/open에 자체 핸들러를 등록해 터미널이 아니라 Claude Code 에디터 탭을 엽니다. 파라미터는 VS Code 문서를 보세요.
SSH 연결의 Claude Desktop 세션: Claude Desktop은 자체 claude:// 링크를 처리합니다. 원격 머신에서 SSH로 Desktop 세션을 열려면 Desktop 문서의 "Open an SSH session from a link"를 보세요.

트러블슈팅

클릭해도 아무 일 없음: 핸들러가 아직 등록되지 않았을 가능성이 높습니다. 등록은 세션 시작이 아니라 대화형 세션의 첫 프롬프트 전송 때 일어납니다. 그 머신에서 대화형 claude 세션을 시작해 아무 프롬프트를 보내고 종료한 뒤 링크를 다시 시도하세요. 데스크톱 환경이 없는 Linux에서는 xdg-open이 전달할 대상이 없을 수 있습니다.
Linux에서 xdg-open을 찾을 수 없음: xdg-utils 패키지의 명령으로 최소 서버 이미지, 컨테이너, WSL 배포판에 없는 경우가 많습니다. 예: sudo apt install xdg-utils 후 다시 실행. 실행은 되는데 아무것도 열리지 않으면 디스패치할 데스크톱 환경이 없는 것입니다.
링크가 클릭되지 않고 일반 텍스트로 렌더링: 일부 Markdown 렌더러는 http/https만 허용하고 다른 스킴을 제거합니다. GitHub는 README, issue, PR, wiki에서 이렇게 해서 [label](claude-cli://...)가 링크와 URL 없이 label로만 렌더링됩니다. 이런 플랫폼에서는 deep link를 코드 블록에 넣어 독자가 URL을 보고 브라우저 주소창에 붙여넣을 수 있게 하세요.
세션이 repo가 아니라 홈 디렉터리에서 열림: repo 파라미터는 Claude Code가 이미 본 clone으로만 해석됩니다. clone 안에서 claude를 한 번 실행해 경로를 기록하게 하거나 링크를 절대 경로 cwd로 바꾸세요.
엉뚱한 터미널이 열림: macOS는 선호 터미널에서 claude를 한 번 시작하면 다음 링크가 그것을 씁니다. Linux는 $TERMINAL 환경 변수를 선호 에뮬레이터 명령 이름으로 설정합니다. Windows는 순서가 고정이므로 링크가 PowerShell이나 cmd.exe 창 대신 Windows Terminal에서 열리길 원하면 Windows Terminal을 설치하세요.

함께 보기

Skills: 긴 런북 프롬프트를 repo의 /skill로 저장해 링크의 q는 이름만 지정
Non-interactive mode: 터미널을 열지 않고 스크립트에서 Claude를 실행해 출력 캡처
Server-managed settings
VS Code

링크로 세션 시작하기 (Deep links)

개요

핵심 개념

상세

동작 방식

링크 만들기

예시

등록과 지원 플랫폼

다른 진입점

트러블슈팅

함께 보기

관련 가이드

링크로 세션 시작하기 (Deep links)

개요

핵심 개념

상세

동작 방식

링크 만들기

예시

등록과 지원 플랫폼

다른 진입점

트러블슈팅

함께 보기

관련 가이드