동작 원리

Zeph은 서로 맞물리는 세 계층이다. hook은 모델이 협조하든 말든 발동하고, MCP 도구는 모델이 의도적으로 당신에게 닿을 수단을 준다.

zeph-to/plugin (Claude Code 플러그인)
  ├─ hooks/zeph-setup.js   → SessionStart: 행동 규칙 주입
  ├─ hooks/zeph-stop.sh    → Stop: 완료 자동 푸시
  ├─ hooks/zeph-ask.sh     → PreToolUse: 질문 푸시
  ├─ hooks/zeph-remote.sh  → UserPromptSubmit: 폰에서 온 메시지 → REMOTE 모드
  ├─ .mcp.json             → MCP 서버 등록
  └─ 기반:
      ├─ @zeph-to/cli         → hook + notify/list/dismiss + tmux 원격 조종
      └─ @zeph-to/mcp-server  → zeph_ask / zeph_prompt / zeph_input / clipboard / file …

계층	패키지	역할	신뢰도
Hook	`@zeph-to/cli`	Claude 이벤트에 자동 발동	100%, AI 협조 불필요
MCP 서버	`@zeph-to/mcp-server`	AI가 호출하는 도구: ask·prompt·input 등	모델이 규칙을 따르는지에 달림
플러그인	`zeph-to/plugin`	hook·MCP·규칙을 묶음	한 번 설치

세션 흐름과 Ask Loop

SessionStart hook
  ├─ ~/.zeph/config.json 읽기
  ├─ HOOK_ID 있음 → ask/prompt/input 규칙 주입
  └─ HOOK_ID 없음 → notify 전용 규칙 주입

작업 중…
  ├─ 선택·입력 필요   → zeph_ask → 모바일에서 버튼 또는 텍스트 응답 → 계속
  ├─ 복잡한 질문      → AskUserQuestion → Ask hook 푸시 → 터미널에서 응답
  │                      └─ tmux + `zeph listener`면 폰의 터미널 미러로도
  │                         답할 수 있다 (↑/↓, Enter)
  ├─ 작업 완료        → zeph_ask "Done. Next?" → 선택 또는 입력 → 실행 → 반복
  │                      └─ "Done" 누르면 세션 종료
  └─ 폴백: AI가 zeph_ask를 건너뜀 → Stop hook이 단방향 푸시 전송

Hook ID가 설정돼 있으면 Claude는 실제 작업 뒤 마지막 행동으로 zeph_ask를 쓴다. 당신의 답은 직접 지시로 취급돼 재확인 없이 실행되고, 그다음 Claude가 다시 묻는다.

이 루프는 폰에서 시작될 수도 있다. 앱의 에이전트 채팅으로 메시지를 보내면 zeph listener가 자기가 주입한 내용을 정확히 기록한다. 플러그인의 UserPromptSubmit hook이 그 일치를 검증하고, Claude는 당신이 원격이라는 것을 알게 된다.

알림 매트릭스

무엇이 어디서 발동하고 중복될 수 있는지:

이벤트	출처	신뢰도	중복
작업 완료	Stop hook	100%	없음 — AI가 이미 `zeph_ask`를 보냈으면 건너뜀
질문 발생	Ask hook	100%	없음
판단·입력 필요	`zeph_ask`	~80%, AI가 호출해야 함	없음
판단만	`zeph_prompt`	~80%	없음
텍스트 입력만	`zeph_input`	~80%	없음
수동 푸시	`zeph_notify`	요청 시	없음

폰에서 세션 조종하기

zeph cc로 Claude를 띄우면 폰의 Active Agents 선택기가 도는 세션에 직접 입력할 수 있다 — zeph_ask 창이 닫힌 뒤에도. 소파에서 리팩토링을 시작하고, 점심 먹으며 후속 질문에 답하고, 돌아오면 끝난 브랜치가 있다.

zeph cc          # 폰이 닿을 수 있는 이름 붙은 tmux 세션의 claude
zeph codex       # Codex도 동일
zeph cursor      # Cursor 터미널 TUI인 cursor-agent도 동일
zeph gemini      # Gemini도 동일

한 단계 설정과 전체 구조는 CLI & SDK → 원격 조종에 있다.

자율 모드

Claude에게 시간 예산을 주고 자리를 비운다:

/zeph-auto 2h fix the flaky tests

Claude는 탐색 → 계획 → 구현 → 검증 → 커밋을 예산이 소진될 때까지 반복하며, 검증된 단위마다 작업 브랜치에 커밋한다.

질문은 기본값이 명시된 zeph_ask 버튼으로 폰에 도착한다 — 답하면 방향을 잡고, 무시하면 타임아웃 후 안전한 기본값으로 진행한다. push·deploy·delete 같은 비가역 작업은 타임아웃으로 실행되지 않고 명시적으로 누를 때까지 기다린다.

실행이 끝나면 무엇이 커밋되고 건너뛰어졌고 자동 기본값으로 처리됐는지 리포트가 나오며, 연장·검토· 종료 버튼이 함께 온다.

기간은 2h·90m·1h30m 또는 분 단위 숫자를 받고 기본값은 1h다. /zeph-status가 실행 중 남은 예산을 보여준다.

동작 원리

세션 흐름과 Ask Loop

알림 매트릭스

폰에서 세션 조종하기

자율 모드

이 페이지에서