Protocol CLI

구독 기반 개발자용 코딩 에이전트. 아무 코드베이스에서 파일을 읽고/쓰고/쉘을 돌리며 작업한다 (Claude Code 스타일). Protocol 백엔드(Firebase + Azure Functions + Vertex)로 인증·LLM·저장·결제가 일원화돼 있다.

통합 아키텍처 전체 그림은 ../docs/CLI.md 참고.

특징

• 단일 LLM 경로 — 모든 호출이 Protocol /api/chat(Azure Functions → Vertex AI Gemini)로. 클라는 티어 토큰(orchestrator/heavy/default/light)만 알고, 실제 모델명·과금은 서버가 강제 (모델명 난독화).
• Graph Engine — YAML DAG 워크플로우 (llm/tool/human/router/parallel/loop 노드).
• Built-in Tools — read, write, edit, bash, grep, glob, WebFetch, WebSearch, Agent, Diff, Debate, Plan, Ask, Skill.
• Sub-Agent — Explore / Plan / Verification / general-purpose (툴·티어 제한).
• Git-style 플래너 — 기획서를 단계별로 작성, 각 단계는 승인 게이트. 불변 커밋 로그의 fold로 상태 투영. Firestore에 저장 → 웹/모바일에서 승인.
• 클라우드 동기화 — 채팅 세션·기획서가 Firestore(users/{uid}/...)에 저장돼 기기 간 이어하기.
• MCP / Plugin — 외부 MCP 서버 연결, 커스텀 툴/커맨드 확장.

설치

npm install -g @nexera-system/protocol   # (퍼블리시 후) — 현재는 로컬 npm link

로컬 개발:

npm install
npm run build
npm link   # 'protocol' 커맨드 전역 등록

빠른 시작

protocol login        # 브라우저로 Protocol 구글 계정 로그인 (기본)
protocol              # 코딩 에이전트 시작 (= protocol chat, 인터랙티브)
protocol billing status   # 티어/사용량 확인
protocol runner       # 노트북에 켜두면 승인된 작업을 실행 (모바일 연동)
protocol serve -p 3000    # 브라우저/모바일 접근용 웹 서버

주요 명령

| 명령 | 설명 | |------|------| | protocol login | Google 루프백 로그인(기본). --email/--password는 QA 폴백 | | protocol logout / whoami | 로그아웃 / 현재 계정 | | protocol / protocol chat | 인터랙티브 코딩 세션 (기본 명령) | | protocol runner [--interval N] | 승인된 plan step을 이 환경(cwd)에서 실행 | | protocol execute-step --plan <id> --step <id> | 단일 승인 step 실행 (러너/샌드박스용) | | protocol serve [-p 3000] | 웹 서버 | | protocol sessions | 클라우드 동기화 세션 목록 (대화 기록 — 기기 간 이어쓰기) | | protocol attach [이름] | 떼었다 붙는 세션. 터미널을 닫아도 계속 돈다. ⌃B d 로 떼기, --list 로 목록 | | protocol billing status\|upgrade\|portal | 구독/사용량 | | protocol config get\|set <k> <v> | 설정 |

단축키

터미널 안에서 창을 다루는 키. tmux 를 쓰던 손에 맞췄고, 기존 단축키(⌃N/⌃X/⌃←→)도 그대로 남아 있다.

| 키 | 하는 일 | |----|---------| | ⌃B c | 새 에이전트 탭 | | ⌃B n / ⌃B p | 다음 / 이전 탭 | | ⌃B 1~9 | 번호로 이동 (에이전트 목록의 번호) | | ⌃B x | 현재 탭 닫기 (main 은 못 닫음 — 세션 종료는 /exit) | | ⌃B z | 현재 탭 일시정지/해제 | | ⌃B w / ⌃B s | 에이전트 대시보드 / 현황 | | ⌃B d | 세션에서 떼기 (protocol attach 로 띄운 세션일 때) | | ⌃B ? | 단축키 도움말 |

탭을 전환하지 않아도 에이전트 대시보드(⌃B w)에 각 탭의 미션과 마지막 한 줄이 보인다. 전환은 파고들 때만 쓰는 것이지 주 동선이 아니다.

설정

~/.protocol-cli/config.yaml — 로그인 시 대부분 자동 설정됨.

api:
  endpoint: "https://protocolai.tech"   # Protocol 백엔드
  firebaseApiKey: "..."         # 공개 Firebase Web API 키 (login이 자동 저장)
auth:
  sessionPath: "~/.protocol-cli/session.json"
tools:
  enabled: ["read", "write", "edit", "bash", "grep", "glob"]
  permissions:
    bash: "ask"
    write: "ask"
    edit: "ask"

LLM 키 불필요 — Vertex/GCP 키는 서버(Azure Functions)만 갖는다. 클라이언트는 Firebase idToken으로만 인증하고 모델은 서버가 고른다.

개발

npm run typecheck   # 타입 체크
npm run build       # dist/ 빌드
npm test            # vitest

현황

Protocol/Firebase 통합 완료 (인증·LLM·저장·결제). 기능별 상태는 IMPLEMENTATION_STATUS.md, 통합 상세는 ../docs/CLI.md.