CLI & SDK

에이전트가 일하다 판단이 필요한 지점에 닿으면 당신 폰에 묻는다. 버튼을 누르거나 답을 입력하면 그 답이 살아 있는 세션으로 돌아가고, 에이전트는 하던 일을 계속한다.

@zeph-to/cli는 그 왕복의 터미널 쪽이다:

ZephHook SDK — 네이티브 fetch, 런타임 의존성 없음. 푸시 전송·조회·해제.
zeph CLI — 8개 에이전트를 한 명령으로 설정하고, 푸시를 보내며, 폰이 Claude Code / Codex / Cursor / Gemini 세션을 조종하게 해주는 상주 listener를 띄운다.

빠른 시작

CLI를 전역 설치하고 setup을 실행한다:

npm install -g @zeph-to/cli
zeph install

새 머신에서 zeph install은 브라우저 로그인을 연다 — 웹앱이 API 키와 hook을 한 쌍으로 발급하고 CLI가 ~/.zeph/config.json에 기록한다. 복사·붙여넣기가 없다. 그다음 감지된 모든 에이전트에 rules·hooks·MCP를 설치한다.

다시 실행해도 안전하다: 저장된 로그인은 손대지 않고 재사용하므로, 재실행은 에이전트 연동만 갱신한다. 계정을 바꾸려면 zeph install --relogin이 새 로그인을 강제한다.

npx 대신 전역 설치를 쓰는 이유

폰으로 세션을 조종하는 zeph cc는 zeph가 PATH에 있어야 하고, 이때 설치되는 에이전트 hook은 $(command -v zeph || npx …) 형태로 풀린다. 전역 바이너리는 모든 알림마다 발생하는 npx 콜드 스타트를 건너뛴다.

폰 조종 없이 알림만 쓸 거라면 npx @zeph-to/cli install이 전역 바이너리를 건너뛰는 가벼운 대안이다.

설치 변형

# 브라우저 없는 헤드리스 머신: 다른 머신의 ~/.zeph/config.json에서 값을 옮겨 붙인다
zeph install --key ak_... --hook hook_...

# 대화형 에이전트 선택기를 건너뛴다
zeph install --only claude,cursor

# 계정 전환 — 저장된 로그인을 덮고 새 브라우저 로그인을 강제한다
zeph install --relogin

# 자격증명만 갱신하고 에이전트는 재설치하지 않는다. 이미 `zeph install`을 한 번
# 돌렸다고 가정하며, 이것만으로는 MCP가 에이전트에 연결되지 않는다
zeph login

첫 푸시 보내기

zeph notify --title "Deploy done" --body "v2.1.0 shipped"

설치 이후 무슨 일이 일어나나

hook은 설정된 각 에이전트의 모든 세션에서 발동한다. zeph cc는 폰 조종 브리지이지 알림 스위치가 아니다.

Claude Code에서 턴마다 나가는 일상 푸시는 꺼진 채로 시작한다 — quiet가 기본값이다. /zeph-normal이 프로젝트 단위로 켜고, /zeph-loud는 매 턴 푸시하며, /zeph-mute는 프로젝트를 통째로 침묵시키고, /zeph-status가 현재 무엇이 적용 중인지 보여준다. 자세한 것은 Mute와 push mode에 있다.

~/.zeph/config.json이 단일 정본이다 — CLI·MCP 서버·플러그인 hook·listener가 전부 이 파일을 읽는다. 일반적인 설정에는 ZEPH_API_KEY 같은 환경변수가 필요 없다. 그것들은 두 번째 계정이나 CI를 위한 오버라이드로 존재한다.

지원 에이전트

zeph install이 아래를 자동으로 감지하고 설정한다:

에이전트	설치되는 것
Claude Code	플러그인 (hooks + MCP 서버)
Cursor	MCP 서버 + stop hook + rules
Windsurf	MCP 서버 + response hook + rules
Gemini CLI	MCP 서버 + AfterAgent hook
Codex CLI	Stop hook + rules
Copilot CLI	Session end hook + rules
Cline	rules 파일 (`~/.cline/rules/zeph.md`)
Aider	conventions 파일 + `~/.aider.conf.yml`의 `read:` 지시자

zeph listener를 통한 원격 조종은 더 좁은 집합을 다룬다 — tmux 안에서 조종할 수 있는 Claude Code·Codex·Cursor·Gemini 넷이다. 래퍼가 각각을 이름 붙은 tmux 세션에서 띄워줄 뿐이고 설정도 하나만 빼면 같다: Cursor에는 remote-origin hook이 없어서 zeph cursor 세션은 스스로 sticky REMOTE 모드에 들어가지 않는다. 원격 조종 참고.

요구사항

Node.js 18 이상 (네이티브 fetch를 쓴다).
tmux — zeph cc / codex / cursor / gemini와 zeph listener에 필요하다.
ZephHook SDK는 런타임 의존성이 없다. CLI는 대화형 zeph install 선택기를 위해 @inquirer/prompts를, listener의 WebSocket 구독을 위해 ws를 쓴다.