내 CLI 가져오기: 휴대폰으로 Custom ACP 세션 모니터링하기
ACP 호환 CLI를 직접 컴퓨터에서 실행하면서도 휴대폰으로 진행 확인, 승인, 후속 메시지를 처리하는 워크플로를 만드는 실용 가이드.
- CLI
- 0.2.17
- 프리뷰 ref
- a2c45c8
"기본" 프로바이더를 벗어나는 순간 익숙한 문제에 부딪힙니다.
좋아하는 CLI는 컴퓨터에서 실행할 수 있습니다.
하지만 휴대폰 워크플로가 사라집니다.
이 가이드는 그 휴대폰 워크플로를 되찾는 방법입니다.
- 직접 고른 ACP 호환 CLI를 로컬에서 실행
- 그래도 휴대폰으로 세션 모니터링
- 그래도 승인과 후속 메시지 처리
요약
- 로컬에서 실행할 ACP 호환 CLI를 고릅니다.
- 이를 Custom ACP 백엔드로 정의합니다(명령, 감지, 인증 확인).
- 호스트 컴퓨터에서 동작을 확정합니다:
- 바이너리 경로 확인
- 작업 디렉터리 규칙 확인
- 감지/인증 명령 확인
- 짧은 휴대폰 루프를 사용합니다: 확인 → 승인 → 후속 메시지 하나 → 나가기.
문제
커스텀 통합은 실무적인 이유로 실패합니다.
- 잘못된 바이너리 경로
- 잘못된 작업 디렉터리
- 올바른 컴퓨터에 인증 정보가 없음
그래서 첫 번째 목표는 통합의 동작을 확정하는 것입니다.
일반적인 방법과 트레이드오프
- SSH/tmux: 동작하지만 "휴대폰으로 본격적인 터미널 작업"이 됩니다.
- 원격 데스크톱: 무겁고 번거롭습니다.
- 기다리기: 안전하지만 느립니다.
잘 통하는 건 전용 휴대폰 제어 화면입니다.
- Happier: Custom ACP CLI는 그대로 컴퓨터에서 실행되고, 진행 확인, 승인, 후속 메시지를 위한 휴대폰 UI를 얻습니다. 트레이드오프: 에이전트를 실행하는 컴퓨터가 온라인 상태여야 합니다.
Happier가 처음이라면 (무엇이고 어디서 받는지)
Happier를 처음 본다면: 코딩 세션을 위한 오픈 소스 컴패니언 앱(모바일/웹/데스크톱)입니다.
설정하기:
- GitHub: https://github.com/happier-dev/happier
- 설치/다운로드: https://github.com/happier-dev/happier#how-it-works
- Discord: https://discord.gg/W6Pb8KuHfg
90초 만에 이해하는 ACP (나머지 내용을 위해)
ACP(Agent Client Protocol)는 다음 둘 사이의 프로토콜입니다.
- 클라이언트(앱/IDE/대시보드)
- 에이전트 프로세스(여러분의 CLI)
기본 전송 방식은 stdio이며, 줄바꿈으로 구분된 JSON-RPC 메시지를 씁니다.
실무에서 핵심적인 영향은 다음과 같습니다.
- 에이전트의 stdout이 곧 프로토콜이다
- 로그는 stderr로 보내야 한다
stdout에 로그가 섞이면 클라이언트가 스트림을 파싱할 수 없어서 모든 게 "고장 난" 것처럼 보입니다.
ACP와 MCP (둘 다 등장하는 이유)
- ACP는 클라이언트가 에이전트 세션과 대화하는 방식입니다.
- MCP는 에이전트가 도구 서버(GitHub, 브라우저 자동화 등)와 대화하는 방식입니다.
ACP 세션은 mcpServers 목록과 함께 시작할 수 있어서 다음을 함께 쓸 수 있습니다.
- 커스텀 에이전트 CLI 하나
- 일관된 도구 구성
Custom ACP의 성패를 가르는 규칙 (stdio 계약)
통합을 망치는 흔한 원인:
- stdout에는 ACP 프로토콜 메시지만 있어야 한다
- 로그는 stderr로 보낸다
- 메시지는 줄바꿈으로 구분되므로 하나의 JSON 메시지 안에 줄바꿈을 넣지 않는다
- JSON을 보기 좋게 출력하지 않는다(
indent=2는 동작을 깨뜨립니다)
"내 에이전트가 호환되는지" 빠르게 확인하려면:
- ACP 모드로 실행하고 배너 출력 없이
initialize에 응답하는지 확인
1단계: Custom ACP 백엔드 정의
세세한 설정 작업이라 많은 사람이 여기서 막힙니다.
정의해야 할 것:
- 이름/ID(어떻게 식별할지)
- 명령(어떻게 시작할지)
- 감지 명령("설치되어 있는가"를 안전하게 확인)
- 인증 확인(선택 사항, 안전할 때만)
- 작업 디렉터리 전제(리포지토리 루트를 가정하는지)
시간을 아끼는 규칙: 감지만으로 시작하고 인증 확인은 나중에 추가하세요.
기능 협상 (메서드가 있다고 가정하지 말 것)
ACP는 initialize로 시작합니다.
에이전트는 자신의 기능을 응답합니다.
클라이언트는 에이전트가 지원한다고 밝히지 않은 메서드를 호출하면 안 됩니다.
"재개/로드"를 지원하지 않으면 다음과 같은 증상이 보입니다.
- 재개를 기대했는데 새 세션이 시작됨
- 기록이 없음
그래서 Custom ACP에서는 최소한의 에이전트(새 세션 + 프롬프트)를 먼저 내놓고 생명주기 메서드를 나중에 추가하는 게 일반적입니다.
2단계: 먼저 컴퓨터 한 대에서 동작을 확정
여러 컴퓨터 워크플로를 시도하기 전에 한 대에서 동작하게 만드세요.
"내 터미널에서는 된다"와 "클라이언트가 실행하면 된다"가 갈리는 지점이 여기입니다.
체크리스트:
- 예상한 작업 디렉터리에서 명령을 실행할 수 있는가?
- 셸 초기화 파일(
.zshrc,nvm,asdf)에 의존하는가? - 환경 변수나 시크릿이 필요한가?
- stdout에 배너나 진행 표시줄을 출력하는가?
CLI에 자격 증명이 필요하다면 백엔드 정의에 붙여 넣지 마세요. 환경 변수나 저장된 시크릿 기능을 사용하세요.
실제로 보게 되는 인증 패턴
대부분의 ACP 에이전트는 다음 인증 패턴 중 하나에 해당합니다.
-
환경 변수 인증
- 클라이언트가 환경 변수와 함께 에이전트를 실행
- 단순하고 자동화하기 좋음
-
터미널 로그인 인증
- 터미널에서
<cli> login을 한 번 실행 - 에이전트는 머신별 인증 상태를 사용
- 터미널에서
-
UI에서 OAuth(CLI 중심 도구에서는 드묾)
ACP의 인증 설계는 의도적으로 신중합니다. 에이전트가 클라이언트를 속여 인증용으로 임의의 명령을 실행하게 할 수 없어야 합니다.
3단계: 휴대폰 워크플로
2분 루프
- 세션 열기
- 승인 확인
- 후속 메시지 하나 보내기
- 나가기
복사해서 쓰는 후속 메시지 3가지
- 체크포인트
다음 단계가 끝나면 멈추고 다음을 요약해 줘:
- 변경한 것
- 변경하지 않은 것
- 다음에 하려는 것
- 제약
마이그레이션/인증은 건드리지 마. 필요하다고 생각되면 멈추고 물어봐.
- 근거
계속하기 전에 지금 실행하려는 명령을 그대로 붙여 넣고 이유를 설명해 줘.
클라이언트별 설정 레시피 (복사용)
에이전트가 ACP를 제대로 따르게 되면, 다음 골칫거리는 클라이언트 설정 형식입니다.
자주 마주치는 것:
acp.json을 쓰는 JetBrains 커스텀 에이전트- Zed 설정 JSON
- Neovim CodeCompanion ACP 클라이언트(제약이 명시되어 있음)
하나로 통일된 파일 형식은 없습니다.
규칙: 클라이언트 하나를 골라 거기서 동작하게 만든 다음 늘려 가세요.
디버깅 플레이북 (에이전트를 탓하기 전에)
1) 에이전트의 stdout이 깨끗한지 증명
파싱 오류가 보이면 80%는 stdout에 JSON-RPC가 아닌 무언가가 들어 있기 때문입니다.
모든 로그를 stderr로 보내세요.
2) 메시지 안의 줄바꿈 피하기
JSON 메시지를 보기 좋게 출력하지 마세요. 메시지 하나는 한 줄이어야 합니다.
3) 작업 디렉터리가 예상과 같은지 증명
많은 커스텀 에이전트가 "동작은" 하지만 cwd가 틀려서 엉뚱한 리포지토리를 다룹니다.
문제 해결
감지는 되는데 세션이 시작되지 않음
보통 다음 중 하나입니다.
- 환경 변수 누락
- 잘못된 작업 디렉터리
- CLI가 stdout에 배너/로그를 출력
- CLI가 TTY를 기대함(stdio ACP와 호환되지 않음)
에이전트는 시작되는데 도구가 보이지 않음
대개 MCP 설정 불일치입니다.
- stdio와 http/sse 필드의 차이
- 헤더/환경 변수 누락
인증이 "Unknown"으로 표시됨
인증 확인이 안전하지 않거나 정의되지 않았다면 Unknown은 예상된 결과입니다.
"로그아웃"이 아니라 "모름"으로 받아들이세요.
FAQ
ACP 사양 전체를 구현해야 하나요?
아니요.
"최소 기능" 에이전트가 지원할 것:
- initialize
- session/new
- session/prompt
나머지(로드/재개, 풍부한 도구, 첨부 파일)는 나중에 추가해도 됩니다.
터미널에서는 되는데 IDE/앱에서는 안 되는 이유는?
거의 항상 다음 중 하나입니다.
- PATH/환경 변수 불일치
- 잘못된 작업 디렉터리
- stdout 오염
에이전트가 인증 명령을 제어하게 해도 안전한가요?
ACP는 이를 막도록 명시적으로 설계되어 있습니다. 터미널 인증 흐름은 같은 바이너리를 실행해야 하며, 에이전트가 임의의 명령을 지정할 수 없어야 합니다.
Happier가 처음이라면
Happier는 신뢰하는 컴퓨터에서 세션을 실행하고 휴대폰으로 모니터링하기 위한 컴패니언 앱입니다.
설정하기: