참고: 기능 매트릭스에 따르면 Git 쓰기 작업(commit, push, pull)은 실험적 기능입니다. 읽기 전용 작업(diff, log, status)은 안정적입니다. 쓰기 작업은 동작이 바뀔 수 있다는 점을 이해하고 사용하세요.

딱 노트북 앞에 없을 때 "깔끔한 커밋 하나만 하면 끝"인 상황이 되는 일은 흔합니다.

보통은 작은 일입니다. 에이전트 세션이 끝났고, 곁가지 수정이 몇 개 있고, 왜 그 파일들을 바꿨는지 잊기 전에 깔끔한 기준점을 확정해 두고 싶은 거죠.

휴대폰에서의 목표는 복잡한 Git 작업이 아닙니다. 짧은 루프입니다.

diff 리뷰 → 의도한 것만 스테이징 → 좋은 메시지 작성 → 커밋 → (필요하면) push

이 루프를 원격 데스크톱 없이, 휴대폰을 작은 터미널로 만들지 않고 돌리는 것이 목표입니다.

요약 (워크플로)

짧게 정리하면:

1. 조건에 맞는 방법을 고릅니다.
   • 터미널 완전 제어 (SSH/tmux)
   • PR로만 리뷰 (GitHub)
   • 저장소가 있는 곳에서 바로 동작하는 휴대폰 친화적 UI
2. Happier를 쓴다면 저장소가 있는 머신에 설정하고 휴대폰을 연결합니다. 시작: 휴대폰에서 Happier 사용하는 방법
3. 휴대폰에서 세션을 열고 Source control을 확인합니다.
4. 스테이징하기 전에 Review에서 diff를 읽습니다.
5. 함께 묶이는 것만 스테이징합니다.
6. 커밋 메시지를 씁니다 (초안을 생성한 뒤 수정해도 됩니다).
7. 커밋합니다.
8. 저장소 상태가 깨끗할 때만 push합니다 (충돌 없음, upstream보다 뒤처지지 않음, detached 아님).

"휴대폰에서 커밋한다"는 게 실제로 무슨 뜻인지

커밋은 저장소 작업 트리가 있는 곳(노트북, 서버, 개발 머신)에서 이루어져야 합니다. 그래서 질문은 "휴대폰에서 git이 돌아가나?"가 아니라 다음과 같습니다.

• 휴대폰에서 저장소를 리뷰하고 제어할 수 있는가
• 실제 git 작업은 워크스페이스를 소유한 머신에서 실행되는가

Happier는 이 워크플로를 중심으로 설계되었습니다. "리뷰 / 스테이징 / 커밋" 루프는 휴대폰에서 돌리고, 저장소와 Git은 워크스페이스를 소유한 머신에 그대로 둡니다.

이 방법이 맞는 경우와 맞지 않는 경우

맞는 경우:

내가 관리하는 머신(노트북, 서버, 개발 머신)에 저장소가 있고, diff 리뷰, 스테이징, 커밋을 위한 신중한 화면이 필요할 때입니다. 또한 Git 쓰기 작업이 기능 토글 뒤에 있다는 점(실험적으로 표시될 수 있음)을 받아들일 수 있을 때입니다.

맞지 않는 경우:

히스토리 수정(rebase, reset, cherry-pick)이 필요하거나, 충돌 해결 중이거나, 저장소를 소유한 머신에 아예 연결할 수 없을 때입니다. 이럴 때는 진짜 터미널로 돌아가세요.

흔한 방법과 트레이드오프

흔한 선택지:

• SSH + tmux: 동작하지만, 휴대폰에서는 diff 리뷰와 스테이징을 서두르기 쉽습니다.
• 원격 데스크톱: 가끔 있는 긴급 상황에는 괜찮지만, 모바일에서는 무겁고 잘못 누르기 쉽습니다.
• GitHub 모바일: 작업이 이미 PR에 있으면 좋지만, 머신에 커밋되지 않은 상태에는 도움이 되지 않습니다.

더 잘 맞는 건 "휴대폰용 GitHub Desktop"에 가까운 것으로, 저장소가 있는 곳에서 그대로 동작하는(클라우드의 두 번째 사본이 아닌) 것입니다.

• Happier: Claude Code, Codex 등 에이전트를 크로스 디바이스로 실행하고 오케스트레이션하는 오픈 소스 앱입니다. 저장소와 Git은 내 머신에 둔 채, 휴대폰에서 diff를 리뷰하고 의도한 것만 스테이징해 커밋할 수 있습니다. 트레이드오프: 머신이나 데몬에 연결할 수 있어야 합니다.

Happier가 처음이라면 (무엇이고 어디서 받는지)

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

여기서의 워크플로는 세션(그리고 저장소와 Git)은 워크스페이스를 소유한 머신(노트북, 서버, 개발 머신)에 두고, Happier로 휴대폰에서 diff 리뷰, 스테이징, 커밋을 하는 것입니다.

이 가이드에서는 마지막 단계인 "리뷰 + 스테이징 + 커밋"을 원격 데스크톱 없이 모바일에서 할 수 있다는 뜻입니다.

설정 시작하기:

• 휴대폰에서 Happier 사용하는 방법
• GitHub: https://github.com/happier-dev/happier
• 설치 / 다운로드: https://github.com/happier-dev/happier#how-it-works
• Discord (커뮤니티 및 지원): https://discord.gg/W6Pb8KuHfg

사전 준비

필요한 것:

• 저장소가 있는 머신에 연결된 Happier 세션.
• 저장소와 파일 접근 (머신 수준의 워크스페이스 API에 연결할 수 있을 때만 이 화면들이 실제 데이터를 보여 줍니다).

Git 쓰기 작업 활성화 (중요)

기본적으로 Happier의 저장소 탐색과 diff 리뷰는 사용할 수 있지만, Git 쓰기 작업(stage/unstage/commit/pull/push 등)은 기능 토글 뒤에 있습니다.

• Settings → Features → Git operations로 이동
• 활성화 (실험적 기능으로 생각하세요)

Git operations를 활성화하지 않아도 같은 워크플로로 변경 사항 리뷰는 할 수 있고, 커밋은 터미널에서 마무리하면 됩니다.

단계별: 휴대폰에서 코드 커밋하기

정확한 UI 배치는 데스크톱과 모바일에서 다릅니다. 휴대폰 크기 화면에서는 데스크톱 사이드바를 작은 화면에 밀어 넣는 것보다 "한 번에 하나"에 집중한 화면이 더 잘 맞습니다.

1) Source control 열기

세션 화면에서:

• Source control 열기 (저장소 상태 화면)

다음이 보여야 합니다.

• 현재 브랜치 요약
• 변경 파일 목록 (A, M, D 같은 상태 포함)
• 가능한 경우 추가 / 삭제 요약

저장소 상태가 전혀 보이지 않으면 문제 해결로 이동하세요.

0.2.12부터는 리뷰에서 커밋에 들어갈 파일을 정확히 고를 수 있고, 워크스페이스의 나머지도 계속 볼 수 있습니다. 에이전트가 건드린 다른 것까지 쓸어 담지 않고 내 수정만 커밋할 수 있습니다.

2) 스테이징 전에 diff 리뷰하기

무엇이든 스테이징하기 전에 빠르게 훑어봅니다.

• Review 화면을 열어 커밋되지 않은 diff를 하나의 연속된 리뷰로 스크롤합니다.
• 다 본 파일은 접습니다.
• 고칠 파일이 있으면 에디터에서 열어 수정한 뒤 Review로 돌아옵니다.

휴대폰에서는 날것의 터미널보다 diff와 리뷰 전용 UI가 위치를 잃지 않기 훨씬 쉽습니다.

3) 의도한 것만 스테이징하기

변경 파일 목록에서 할 수 있는 것:

• 파일 단위로 스테이징 / 스테이징 해제
• (지원되는 경우) 선택한 줄이나 hunk 스테이징

휴대폰에서 커밋할 때는 평소보다 스테이징 규율이 중요합니다. 좋은 기본 규칙:

• 하나의 일관된 변경에 속하는 파일만 스테이징
• 곁가지 포맷 수정, 디버그 로그, 관련 없는 수정은 별도 커밋으로

4) 커밋 메시지 작성 (초안 생성도 가능)

Source control 화면 아래쪽에 Happier의 커밋 입력란이 있습니다.

직접 메시지를 입력하거나 Generate commit message로 초안을 만들 수 있습니다.

중요한 점:

• 생성기는 문구를 제안할 뿐 자동으로 커밋하지 않습니다
• 백엔드와 지시 사항은 Settings → Source Control에서 설정할 수 있습니다

생성기를 쓰더라도 자동 완성처럼 다루세요. 스테이징된 diff를 훑어보고, 실제로 스테이징한 내용에 맞게 메시지를 고치세요.

5) 커밋

스테이징된 변경 사항을 커밋합니다.

Happier가 작업을 막는다면, 보통 저장소가 UI 자동 작업에 안전하지 않은 상태(충돌, detached HEAD 등)이기 때문입니다. 의도된 동작입니다.

6) push (선택): 안전장치 이해하기

휴대폰에서 push하기로 했다면 보수적인 안전장치를 예상하세요. 이 방향은 의도적입니다. 작은 화면에서 히스토리를 수정하게 두기보다 위험한 push를 거부하는 쪽을 택합니다.

마주칠 수 있는 규칙 예시:

• pull은 fast-forward만 가능
• HEAD가 detached면 push/pull/revert 차단
• 로컬이 upstream보다 뒤처지면 push 차단
• 충돌이 있는 동안 push/pull/revert 차단

차단되면 보통 다음 중 하나를 할 때입니다.

• 진짜 터미널에서 저장소 상태 고치기
• 먼저 브랜치 전환 / 정리 / 충돌 해결

AI 코딩 세션(Claude/Codex 등)을 위한 실용적인 워크플로

"휴대폰에서 커밋"이 필요한 이유가 에이전트 세션 때문이라면, 잘 돌아가는 휴대폰 중심 루프는 다음과 같습니다.

1. 에이전트가 바꾼 내용을 Review에서 확인
2. 내장 에디터로 작은 수정 (이름 고치기, 실수로 생긴 파일 삭제)
3. 간결한 메시지로 커밋
4. 에이전트에게 후속 지시 보내기 ("이 깔끔한 기준점에서 계속해 줘")

작지만 유용한 습관 하나: 경로를 직접 설명하는 대신, 입력란의 Link file이나 파일 탐색 도구로 정확한 파일을 다음 프롬프트에 첨부하세요.

첨부 파일과 프로젝트 파일 (엉뚱한 걸 커밋하지 않기)

Happier는 세션 워크플로의 일부로 첨부 파일을 지원합니다. 첨부 파일은 다음에 유용합니다.

• 로그 붙여 넣기
• 일회성 파일 공유
• 모델이 읽을 결과물 보내기

하지만 첨부 파일은 커밋하려는 프로젝트 파일과 다릅니다.

"이건 git에 들어가야 한다"면 임시 첨부 파일이 아니라 Files를 통해 워크스페이스에 넣으세요 (생성 / 업로드 / 편집).

문제 해결

휴대폰에서 Source control이나 diff가 보이지 않음

흔한 원인:

• 저장소를 소유한 머신이나 데몬에 연결할 수 없음.
• 머신과 같은 서버나 릴레이에 연결되어 있지 않음.

세션이 비활성 상태여도 머신이 온라인이면, Happier는 머신 수준의 워크스페이스 API로 저장소와 파일 데이터를 불러올 수 있습니다. 단, 그 머신에 실제로 연결할 수 있어야 합니다.

스테이징이나 커밋 버튼이 없음

Git 쓰기 작업은 토글 뒤에 있습니다.

• Settings → Features → Git operations

Happier에서 push/pull/commit이 안 됨

보통 저장소 안전 규칙이 제 역할을 하는 것입니다. 흔한 차단 원인:

• 충돌이 있음
• detached HEAD
• 브랜치가 upstream보다 뒤처짐

진짜 터미널에서 저장소 상태를 해결한 뒤 휴대폰 워크플로로 돌아오세요.

diff는 리뷰할 수 있는데 커밋이 안 됨

읽기 전용 저장소 데이터는 쓸 수 있지만 쓰기 작업이 비활성화되어 있거나(기능 토글 꺼짐) 저장소 상태 때문에 차단된 경우입니다.

이럴 때 실용적인 워크플로는:

• diff 리뷰와 정리는 휴대폰에서
• 실제 커밋과 push는 노트북으로 돌아와 터미널에서 마무리

자주 묻는 질문

아이폰이나 안드로이드 휴대폰에서도 되나요?

네. 주된 차이는 사용감입니다.

• 휴대폰에서 Happier는 데스크톱의 여러 창 레이아웃 대신 집중된 화면(목록 → 상세)을 씁니다.
• iOS나 Android에서는 diff 리뷰와 스테이징은 모바일에서 하고, 충돌 정리는 나중에 진짜 터미널에서 하는 편이 나을 수 있습니다.

diff는 리뷰되는데 스테이징이나 커밋이 안 되는 이유는?

흔한 이유 두 가지:

1. Git 쓰기 작업이 활성화되지 않음. Settings → Features → Git operations를 켜세요.
2. 저장소가 쓰기 작업을 의도적으로 막는 상태(충돌, detached HEAD 등)임.

push가 차단되는 이유는?

Happier는 의도적으로 보수적으로 설계되었습니다. push는 보통 다음 경우에 차단됩니다.

• HEAD가 detached
• 로컬 브랜치가 upstream보다 뒤처짐
• 충돌이 있음

이럴 때는 휴대폰 워크플로를 "리뷰 + 스테이징 + 커밋"까지로 생각하세요. push는 진짜 터미널에서 저장소 상태를 정리한 뒤에 합니다.

꼭 휴대폰에서 push해야 하나요?

아니요. 다음과 같은 "휴대폰 중심" 워크플로도 충분히 합리적입니다.

• diff 리뷰
• 의도한 것만 스테이징
• 커밋

그리고 push는 노트북으로 돌아왔을 때(또는 터미널에서 간단히 확인할 수 있을 때) 나중에 합니다.

머신이나 데몬에 연결할 수 없다면?

그러면 저장소에서 소스 컨트롤 상태를 불러올 수 없습니다. 선택지는:

• 머신에 다시 연결될 때까지 기다리기
• SSH나 원격 데스크톱으로 돌아가기

Happier가 네트워크나 머신 가용성 문제를 없애 주지는 않습니다. 머신에 연결할 수 있을 때 휴대폰에서 워크플로를 이어 가기 쉽게 해 줄 뿐입니다.

관련 가이드

• 휴대폰에서 Happier 사용하는 방법

다음 단계

• 주된 고민이 코드 리뷰라면 휴대폰에서 diff 리뷰하는 방법부터 시작하세요 (커밋과는 조금 다른 흐름입니다).
• 같은 단계에서 계속 막힌다면 (커밋이나 push 버튼이 없음, 저장소에 연결 불가 등) 나만의 작은 체크리스트로 만들어 두세요. 매번 10분쯤 아낄 수 있습니다.