이 글은 누구를 위한 것인가

• Claude Code를 일상적으로 사용하며,
  자리를 비워도 작업을 멈추고 싶지 않은 사람
• 공식 Remote Control (2026년 2월 출시)을 사용해 보았거나 관심이 있는 사람
• Claude Code를 "가끔 사용하는 도구"가 아니라,
  **상주하는 에이전트 기반 (Agent Infrastructure)**으로 운용하고 있는(또는 하고 싶은) 사람

외출 중에 잠시 만지고 싶은 정도라면, 공식 Remote Control로 충분합니다. 이 글은 그 너머의 이야기 ── 에이전트를 상주시켜 함께 생활하는 방식으로 사용할 때 무엇이 부족해지는지, 그리고 그 과정에서 필요해진 도구들에 대해 양쪽 모두를 사용하고 있는 입장에서 작성합니다.

Claude Code를 스마트폰에서 조작하는 PWA 클라이언트를 직접 제작하여, 수개월 동안 매일 운용하고 있습니다.

어느 날의 장면

전철 안에서 잠금 화면에 알림이 옵니다.

"이 설계, A안과 B안 중 어느 것으로 할까요?"

집에 있는 머신에서 실행 중인 에이전트로부터 온 질문입니다. 알림을 열고 "A로. 단, 이관 스크립트는 남겨줘"라고만 답합니다. 몇 정거장 뒤에 다시 알림 ── "PR을 생성했습니다". 집에 도착할 즈음에는, diff를 살펴보고 merge 할지 말지를 결정하기만 하면 되는 상태가 되어 있습니다.

에이전트가 상주하는 개발에서는, **인간의 업무는 "조작"이 아니라 "판단"**이 됩니다. 판단은 수십 자 내외로 끝날 수 있으므로, 전달만 된다면 장소를 가리지 않습니다. 스마트폰은 단말기라기보다 조종석이며, 이 글에서 다루는 것은 그 조종석을 어떻게 준비할 것인가에 대한 이야기입니다.

스크린샷: 채팅 화면 (markdown 테이블 · 코드 블록의 인라인 렌더링)

공식 Remote Control라는 정답

2026년 2월, Anthropic이 Remote Control을 출시했습니다. claude remote-control

을 한 번 실행하면, claude.ai/code나 Claude 모바일 앱에서 **로컬에서 실행 중인 세션 (Local Session)**을 그대로 조작할 수 있습니다.

솔직히, 매우 잘 만들어져 있습니다. 실행은 로컬 상태 그대로(클라우드로 옮겨가지 않음), MCP 서버나 프로젝트 설정도 그대로 유지되며, 푸시 알림도 있고, 서버 모드라면 여러 세션도 다룰 수 있습니다. 셋업(Setup)은 실질적으로 제로에 가깝습니다.

"외출 중에 Claude Code를 만지고 싶다"는 목적뿐이라면, 이것으로 완결됩니다. 문제는 그 너머로 나아갔을 때입니다.

그럼에도 남는 영역 ── 비교표

"그 너머"에서 무엇이 부족해지는가. 공식 문서에 명시된 제한 사항과 실제 운용에서 느껴지는 차이점을 나열합니다 (2026년 7월 시점 · Claude Code v2.1.x / Remote Control은 research preview 단계이므로 향후 변경될 가능성이 있습니다).

Remote Control (공식)	claude-pwa-client (자작)
셋업 (Setup)	◎ claude remote-control 한 번으로 완료
세션의 영속성 (Session Persistence)	△ 로컬 프로세스 종료 시 종료 · 네트워크 도달 불가 시 약 10분 후 프로세스 전체 종료 (docs 명시)
경로 (Path)	Anthropic API를 경유하여 라우팅
인증의 자유도	claude.ai OAuth 한정 (API key · Bedrock/Vertex · LLM gateway 불가)
원격 사용 가능 명령어	대화형 피커(Picker) 계열 (/resume /plugin 등)은 로컬 한정
알림 (Notification)	푸시 있음 (On/Off 2개 토글 · "이벤트별 설정은 없습니다")
파일 열람	@ 경로 자동 완성
사용량 시각화	/usage를 텍스트로 실행
대화 포크 (Conversation Fork)	─ (필자 확인 시점 기준 없음)
멀티 계정	claude.ai 로그인 단위
sub-agent / Workflow 내용	─
...

이 중에서 저에게 결정적인 요인이 된 것은 두 가지였습니다.

결정적 요인 ①: 세션이 죽지 않는다

공식 docs의 제한 사항에 다음과 같이 적혀 있습니다.

로컬 프로세스는 계속 실행 중이어야 합니다. (중략) 머신은 켜져 있지만 약 10분 이상 네트워크에 도달할 수 없는 경우, 세션은 타임아웃되어 프로세스가 종료됩니다.

일반적인 사용 방식이라면 크게 신경 쓰이지 않을 제약일 것입니다. 하지만 제 환경에서는 며칠씩 계속 살아있는 에이전트(Agent) 세션이 항상 여러 개 돌아가고 있는데, 회선이 10분 끊겼다는 이유만으로 프로세스 자체가 죽어버리는 설계는 이러한 운영 방식에서 받아들이기 어려웠습니다. tmux + 실제 PTY로 구동하는 자작 backend에서는 네트워크와 클라이언트 모두 "나중에 다시 연결하는 것"이며, 세션의 생사에는 관여하지 않습니다.

결정적 요인 ②: 에이전트 측에서 말을 걸어온다

자작 클라이언트에서는 파일 감시(Monitor)나 예약 기상(ScheduleWakeup)을 통해 에이전트가 자발적으로 시작한 턴도 즉시 스마트폰으로 전달됩니다. "사람이 태스크를 던지고 결과를 기다리는" 것뿐만 아니라, "에이전트가 발견한 문제를 먼저 보고해 오는" 방향의 알림을 세션 단위의 입도로 제어할 수 있습니다. 잠금 화면에 "이 설계, A와 B 중 어느 것으로 할까요?"라는 메시지가 도착하면 한마디로 답하는 식의 상호작용이 일상이 됩니다. 에이전트와 함께 생활하기 위해서는 이러한 양방향성이 필요합니다.

구조 (및 규약에 관한 이야기)

구성 방식은 단순합니다.

iPhone/Android (PWA)
⇅ Tailscale (사설망 · 외부 공개 없음)
호스트 머신 (backend: FastAPI)
...

• backend는 공식 claude

CLI를 실제 PTY + tmux의 서브프로세스로 실행할 뿐입니다. 인증과 추론 모두 공식 바이너리 자체가 수행합니다.
OAuth 토큰 추출이나 별도의 클라이언트로부터의 API 호출은 일절 하지 않습니다. 2026년 1월에 일부 서드파티 툴이 약관 위반으로 차단된 것은 "토큰을 추출하여 자체 클라이언트로 API를 호출하는" 패턴이었으며, 본 도구는 이에 해당하지 않는 설계입니다 (legal-and-compliance 참조).
self-hosted · 단일 사용자(single-user)를 전제로 합니다. 자신의 머신에서 자신의 구독(subscription)을 자신이 사용하는 구성이며, backend를 제삼자에게 공개하여 여러 명에게 서비스를 제공하는 방식은 Anthropic의 약관(consumer 인증을 "on behalf of their users"로 라우팅하는 행위 금지)에 저촉되므로 해서는 안 됩니다.

스마트폰과의 연결은 Tailscale로 닫혀 있기 때문에, 대화와 파일 미리보기 모두 제삼자의 서버를 경유하지 않습니다 (추론을 위한 일반적인 Anthropic API 통신은 제외).

스크린샷: AskUserQuestion이 잠금 화면에 도달함

셋업 (Setup)

리포지토리의 docs에 일체가 있습니다. 요구 사항은 호스트 머신(macOS / Linux / Windows는 WSL2) + Tailscale + Node/Python입니다. 솔직히 Remote Control의 "한 방"과 비교하면 셋업은 번거롭습니다 (그렇기에 위의 조건에 해당하지 않는 분들에게는 권장하지 않습니다).

요약 ── Remote Control로 부족해진 분들에게

다음 중 하나라도 해당한다면, 이 클라이언트는 바로 그 용도로 만들어졌습니다.

• 세션을 며칠 동안 계속 유지하는 운영을 하고 있다 (long-lived agents) ── 네트워크 단절로 프로세스가 종료되는 설계는 받아들일 수 없다
• 에이전트 측으로부터의 자발적인 알림을 받고 싶다
• API key / LLM gateway 구성으로 사용 중이다
• 조종석 그 자체를 자신의 손으로 확장하고 싶다

"오래 살아남는 에이전트의 기반을 만든다"를 테마로 개발하고 있으며, 이 클라이언트는 그 일부입니다. 다음에는 에이전트에게 commit이나 push까지 맡기기 위한 안전장치에 관한 이야기를 쓸 예정입니다.

질문이나 지적은 X (@synforger) DM으로 부탁드립니다.

Discussion