ConfHub CLI (confhub)

AI 에이전트(Claude, Gemini, Codex, Cursor, Copilot) 설정을 팀 전체에 중앙 관리하는 CLI 프레임워크.

개념 구조

~/.confhub (Registry)
├── root/agents/claude/        ── 팀 공통 기본 설정 ──┐
└── apps/api-server/agents/    ── 프로젝트별 설정 ────┴─► confhub resolve ─► resolved/api-server/claude/
                                                                                        │
                                                                              confhub sync push
                                                                                        │
                                                                                        ▼
                                                                          confhub-config (private git repo)
                                                                                        │
                                                                                  git submodule
                                                                                        │
                                                                                        ▼
                                                                         api-server 프로젝트 (.nexus-config/)
                                                                                        │
                                                                          confhub submodule init
                                                                                        │
                                                                                        ▼
                                                                              .claude/ 심볼릭 링크

설치

pipx install agent-confhub-cli

빠른 시작

# Registry 초기화
confhub init

# 앱 등록
confhub app add web-frontend

# Claude 에이전트 설정 추가
confhub agent add claude --app web-frontend

# 설정 병합
confhub resolve web-frontend

# 프로젝트에 심볼릭 링크 연결
confhub link web-frontend --target /workspace/my-project

주요 명령어

지원 에이전트

팀 공유 워크플로우

심볼릭 링크 방식 (개인 머신 로컬 적용)

설정 관리자                        팀원
──────────────────────             ──────────────────────
confhub app add <app>
confhub agent add claude
파일 직접 편집
confhub resolve <app>
confhub sync push       ──────►   confhub sync pull
                                   confhub resolve --all
                                   (심볼릭 링크 프로젝트에 즉시 반영)

# 설정 관리자 - 설정 변경 후 push
confhub sync push --message "feat: Claude 설정 업데이트"

# 팀원 - pull 후 resolve로 로컬 반영
confhub sync pull && confhub resolve --all

Git Submodule 방식 (sparse-checkout으로 앱 설정만 적용)

confhub-config 레포 전체가 아닌 해당 앱의 resolved/<app>/ 만 체크아웃합니다.

설정 관리자                                      팀원
─────────────────────────────────              ──────────────────────────────
confhub app add api-server
confhub agent add claude --app api-server
파일 직접 편집
confhub submodule add api-server \
  --target ./api-server
  (resolve → push → submodule add
   → sparse-checkout 자동 수행)
.nexus-config/ submodule 생성
.claude/ 심볼릭 링크 생성
git push (프로젝트 레포)          ──────►   git clone --recurse-submodules
                                             confhub submodule init api-server
                                             (sparse-checkout + 심볼릭 링크 완료)

설정 관리자 (최초 1회):

# 1. Registry를 private 레포와 연결
confhub sync remote set https://github.com/your-team/confhub-config.git

# 2. 앱 및 에이전트 설정 준비
confhub app add api-server
confhub agent add claude --app api-server
# ~/.confhub/apps/api-server/agents/claude/ 에서 직접 파일 편집

# 3. 프로젝트에 submodule 적용
#    resolve → remote push → git submodule add → sparse-checkout 자동 수행
confhub submodule add api-server --target /workspace/api-server

프로젝트 레포에 생성되는 구조:

api-server/
├── .nexus-config/    ← confhub-config submodule (resolved/api-server/ 만 sparse-checkout)
├── .claude/          ← symlink → .nexus-config/resolved/api-server/claude/.claude/
├── .gemini/          ← symlink → .nexus-config/resolved/api-server/gemini/.gemini/
└── ...

개발자는 .claude/, .gemini/ 등 프로젝트 루트의 심볼릭 링크만 사용하면 됩니다. .nexus-config/ 내부 구조는 신경 쓸 필요 없습니다.

팀원 (레포 클론 후):

# 심볼릭 링크는 레포에 이미 커밋되어 있어 별도 생성 불필요
git clone --recurse-submodules https://github.com/your-team/api-server.git
cd api-server

# sparse-checkout 적용 (resolved/api-server/ 만 체크아웃)
confhub submodule init api-server

설정 업데이트:

파일 직접 편집                confhub submodule add        git push          팀원: git pull
~/.confhub/apps/...    ──►   api-server --target ...  ──►  (프로젝트 레포)  ──►  + submodule update
                              (resolve + push 포함)                               + confhub submodule init

# ~/.confhub/apps/api-server/agents/claude/ 파일 직접 수정 후
confhub submodule add api-server --target /workspace/api-server
# resolve → confhub push → submodule ref + 심볼릭 링크 커밋

# 팀원은 프로젝트에서 반영
git pull && git submodule update
confhub submodule init api-server  # sparse-checkout 재적용

개발

uv sync --extra dev
pytest tests/ -v