독립된 터미널 창에서 시작한 Claude Code 세션에는 문제가 있습니다. 휴대폰으로 진행 상황을 확인하고 싶을 때, 세션은 실행 중이지만 연결할 수 있는 곳에 있지 않습니다.

Herdr(및 tmux/zellij)는 이 워크플로를 바꿉니다. 에이전트 세션이 유지되는 터미널 창(pane)에서 시작되고, Happier는 휴대폰에서 바로 그 창을 엽니다. Happier는 Claude Code, Codex 등의 에이전트를 크로스 디바이스로 실행하고 오케스트레이션할 수 있는 오픈 소스 앱입니다.

요약

1. Herdr 0.9.2 이상을 설치합니다(macOS/Linux에서는 tmux/zellij도 가능)
2. Happier에서: Settings → Session → Terminal host for new sessions → Herdr(또는 tmux/zellij)
3. Herdr 창에서 happier claude 또는 happier codex를 실행합니다(또는 Happier가 창을 만들게 합니다)
4. 휴대폰에서: 세션이 Herdr 안에 연결된 실시간 상태로 보입니다
5. 나중에: happier attach <session-id>로 같은 창에 들어갑니다

문제

일반 터미널 창에서 에이전트를 시작하면:

• 세션은 실행되지만 다른 터미널에서 접근할 수 없다
• 창을 닫으면 터미널이 유지되지 않는다
• 다른 기기에서 에이전트가 무엇을 하는지 쉽게 확인할 수 없다

목표는 다음과 같은 에이전트 세션입니다:

• 유지되는 터미널 멀티플렉서에서 시작
• 휴대폰에서 접근 가능(SSH로 접속해 어떤 세션인지 추측하는 것만이 아니라)
• 노트북 절전/연결 끊김에도 살아남음

일반적인 방법과 트레이드오프

• 일반 터미널 창: 닫거나 노트북이 절전 모드에 들어가기 전까지는 동작합니다. 다시 연결할 방법이 없습니다.
• 수동 tmux: 낫지만 먼저 tmux를 시작하고, 세션 이름을 정하고, 휴대폰에서 어떤 tmux 세션이 어떤 것인지 알아내야 합니다.
• SSH로 접속해 맞는 창 찾기: 동작하지만 번거롭습니다. 결국 창 번호를 추측하게 됩니다.

Happier와 Herdr(또는 tmux/zellij) 는 다음 방식으로 이를 해결합니다:

• 선택한 터미널 호스트에서 세션을 자동으로 시작
• 모바일에서 세션 이름으로 표시
• 정확히 같은 창에 연결 가능

Happier가 처음이라면

Happier는 Claude Code, Codex, OpenCode 같은 AI 코딩 에이전트를 위한 오픈 소스 컴패니언 앱(모바일/웹/데스크톱)입니다.

여기서의 워크플로: Happier가 Herdr(또는 tmux/zellij) 안에서 Claude Code나 Codex를 시작하고, 에이전트의 터미널 화면을 그대로 유지한 채 휴대폰에서 같은 세션에 접근합니다.

설정하기:

• 휴대폰에서 Happier 사용하는 방법
• GitHub: https://github.com/happier-dev/happier
• 설치: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

사전 요구 사항

Herdr의 경우

• Herdr 0.9.2 이상(안정 버전 필요)
• macOS와 Linux에서 사용 가능
• 네이티브 Windows는 지원하지 않음(대신 WSL에서 tmux 사용)

Herdr 버전 확인:

herdr --version

오래된 버전이나 개발 빌드라면 안정 버전 0.9.2 이상으로 업그레이드하세요.

tmux 또는 zellij의 경우

• macOS 또는 Linux에 tmux 또는 zellij 설치
• tmux/zellij는 최소 버전 제한 없음
• Windows의 WSL에서도 동작

Happier CLI

에이전트를 실행할 머신에 Happier CLI를 설치합니다:

• CLI 설치 가이드 (영어)

단계별: 새 세션의 터미널 호스트 설정

1) Happier 설정 열기

Happier 앱(모바일, 웹, 데스크톱)에서:

1. Settings로 이동
2. Session 선택
3. Terminal host for new sessions 찾기

2) 터미널 호스트 선택

다음 중 하나를 선택합니다:

• No terminal host: 세션이 헤드리스로 시작(기본값)
• tmux: tmux를 터미널 호스트로 사용
• zellij: zellij를 터미널 호스트로 사용
• Herdr: Herdr를 터미널 호스트로 사용(CLI 0.2.16 이상 필요)

이 가이드에서는 Herdr를 선택합니다(tmux를 선호하면 tmux).

왜 중요한가:

• No terminal host로 설정하면 Happier 세션은 명시적으로 연결할 때까지 백그라운드에서 실행됩니다
• 터미널 호스트로 설정하면 지원되는 세션이 즉시 그 터미널에 나타납니다
• 세션은 터미널과 Happier 앱 양쪽에서 계속 연결할 수 있습니다

3) 설정은 머신별로 적용

Happier는 이 설정을 계정에 저장하지만 머신별로 적용합니다.

머신이 여러 대라면:

• 각각 다른 터미널 호스트를 쓸 수 있다
• 또는 계정 기본값을 로컬에서 재정의할 수 있다

4) 설정이 저장되었는지 확인

UI에 선택한 호스트(예: Herdr)가 표시되어야 합니다.

Herdr에서 Claude Code 세션 시작

방법 A: Herdr 창 안에서 시작

이미 Herdr 창에 있다면:

happier claude

Happier는 현재 Herdr 창을 Claude Code의 터미널 화면으로 재사용합니다.

방법 B: Happier가 새 창을 만들게 하기

Herdr 밖에서 happier claude를 실행하면 Happier가 새 Herdr 창을 만들고 거기서 Claude Code를 시작합니다.

보이는 화면

Claude Code의 터미널 화면(TUI)이 Herdr 창에 나타납니다:

• 터미널 안의 프롬프트와 응답
• 인라인 승인 요청
• 세션은 실시간이며 연결된 상태

Herdr에서 Codex 세션 시작

Codex도 워크플로는 같습니다:

happier codex

Codex 문서 (영어)에 따르면:

• Codex는 macOS와 Linux에서 네이티브 App Server 경로를 사용
• Herdr(또는 다른 터미널 호스트)를 선택하면 Happier가 그 호스트에서 Codex TUI를 시작
• 터미널 호스트가 없으면 Codex는 연결할 때까지 서버 기반 헤드리스로 실행

휴대폰에서 보고 연결하기

Happier 앱에서

1. 휴대폰에서 Happier 앱 열기
2. 세션 목록에 실행 중인 Claude Code 또는 Codex 세션이 표시됨
3. 세션을 탭해서 열기

일어나는 일:

• 앱에 세션의 트랜스크립트와 컨트롤이 표시됨
• 세션이 Herdr 안에 있으면 연결해서 터미널 화면을 볼 수 있음
• 승인 요청은 앱과 터미널 양쪽에 표시됨

Herdr 창에 연결

터미널(로컬 또는 SSH)에서:

happier attach <session-id>

Claude Code나 Codex가 실행 중인 같은 Herdr 창으로 들어갑니다.

다음도 사용할 수 있습니다:

happier herdr

터미널에서 Herdr를 열고, Herdr 조작으로 세션 창으로 이동할 수 있습니다.

이 방식이 동작하는 이유

Herdr(및 tmux/zellij)는 연결이 끊겨도 터미널 세션을 살려 둡니다.

Happier는 이를 다음과 같이 활용합니다:

1. 이름이 붙은 Herdr 창에서 에이전트 세션 시작
2. 어떤 세션이 어떤 창에 있는지 추적
3. 모바일에서 세션을 이름으로 표시
4. happier attach로 그 창에 바로 이동 가능

결과적으로 에이전트 세션을 한 번 시작하면 다음 어디서든 접근할 수 있습니다:

• 원래 터미널
• happier attach로 연 새 터미널
• Happier 앱을 통한 휴대폰
• Herdr 네이티브 창 이동

문제 해결

증상: Happier가 터미널 호스트 설정이 필요하다고 함

가능한 원인:

• Herdr가 설치되어 있지 않거나 버전이 0.9.2보다 오래됨
• Herdr 서버가 실행 중이 아님

해결:

1. Herdr 설치 확인: herdr --version
2. 버전이 0.9.2 이상인지 확인
3. Herdr가 실행 중이 아니면 시작: herdr
4. 세션 시작 다시 시도

증상: 세션은 시작되지만 Herdr 안이 아님

가능한 원인:

• 세션 시작 후 터미널 호스트 설정을 바꿈
• 오래된 Happier CLI(0.2.16 이전)를 사용 중

해결:

1. CLI 버전 확인: happier --version
2. 필요하면 CLI 0.2.16 이상으로 업그레이드
3. Settings → Session → Terminal host for new sessions에서 설정 확인
4. 세션을 멈추고 새로 시작

증상: 세션 창에 연결할 수 없음

가능한 원인:

• 세션의 Herdr 창을 수동으로 닫음
• Herdr 서버가 재시작되면서 창이 복원되지 않음

해결:

1. 세션이 아직 실행 중인지 확인: happier sessions
2. 세션은 살아 있는데 창이 없다면 에이전트 프로세스는 계속 실행 중
3. Happier 앱(트랜스크립트/승인)으로 계속 제어 가능
4. 연결하면 새 뷰가 만들어지므로 원래 창이 필요하지 않음

증상: Claude 세션이 여러 개라 어떤 창이 어떤 것인지 모르겠음

가능한 원인:

• 세션 목록을 먼저 확인하지 않고 세션을 시작함

해결:

1. happier sessions로 모든 활성 세션을 ID와 함께 나열
2. happier attach <session-id>로 특정 세션의 창으로 이동
3. 또는 Happier 앱을 열고 세션을 탭해서 세부 정보 확인

자주 묻는 질문

tmux와 zellij에서도 되나요?

네. 같은 워크플로가 적용됩니다:

• Terminal host for new sessions를 tmux 또는 zellij로 설정
• happier claude 또는 happier codex 실행
• 세션이 tmux 창이나 zellij 창에 나타남
• happier attach도 같은 방식으로 동작

꼭 Herdr를 써야 하나요?

아니요. 다음 중에서 고를 수 있습니다:

• No terminal host(연결할 때까지 헤드리스)
• tmux
• zellij
• Herdr

워크플로에 맞는 것을 고르세요.

터미널 호스트를 바꿀 수 있나요?

네. Settings → Session → Terminal host for new sessions에서 바꿉니다.

설정은 새 세션에 적용됩니다. 기존 세션은 원래 호스트를 계속 사용합니다.

노트북이 절전 모드에 들어가면 어떻게 되나요?

머신에 접근할 수 있는 한 세션과 Herdr 창은 유지됩니다.

다시 연결하면:

• Herdr가 창을 살려 둠
• 에이전트 프로세스가 계속 실행됨
• happier attach가 이전처럼 동작

머신이 완전히 오프라인이면 머신이 다시 연결될 때까지 Happier 릴레이와의 연락이 끊깁니다.

터미널 호스트가 성능에 영향을 주나요?

아니요. 터미널 호스트는 에이전트의 터미널 화면이 표시되는 곳일 뿐입니다. 에이전트 프로세스와 성능에는 영향이 없습니다.

관련 가이드

• 휴대폰에서 Happier 사용하는 방법
• Happier vs Claude Code Remote Control
• 노트북이 절전 모드여도 Claude Code, Codex, OpenCode를 계속 실행하는 방법(Wi-Fi 끊김, 덮개 닫기, 재개)
• 휴대폰으로 Claude Code 모니터링하는 방법
• Claude Code 터미널 깜빡임 해결 방법