aos — AI-powered Git Helper

git을 몰라도, AI가 충돌을 해결해주는 Git 도우미입니다.

🚀 5분 만에 시작하기 (첫 설정)

pip install aos-git           # 설치
cd 내프로젝트 && aos init       # 프로젝트 초기화 (hooks + 알림 수신자)
aos setup                      # AI + SMTP 설정 (내 PC에서 1회)
aos doctor                     # 모든 항목 ✓ 인지 확인

🔥 이것만 알면 됩니다 (5개 명령어)

📋 일상 작업 흐름

# 1. 새 브랜치에서 시작
aos checkout -b feature/데이터정제

# 2. 코드 수정 후
aos add                           # 변경사항 스테이징
aos commit -m "데이터 정제 로직 추가"  # 커밋
aos push                         # 원격에 반영 → 팀원에게 이메일 알림

# 3. 상대방 변경사항을 받으면
aos sync                          # 최신 main을 내 브랜치에 반영 (충돌 시 AI 해결)
aos push

⚡ 충돌 해결

[aos merge feature/팀원작업]  →  충돌 발생  →  [aos resolve]  →  AI가 충돌 해결  →  커밋 완료
                                                    ↓
                                      해결 안 되면 →  git merge --abort (포기)

aos merge feature/팀원작업      # 충돌 시 AI가 자동으로 해결
# 또는
aos pull                        # 원격 변경사항 가져오기 (충돌 시 AI 해결)
# 또는
aos sync                        # main 기준 브랜치 동기화 (충돌 시 AI 해결)

aos resolve                     # 남아 있는 충돌 마커를 다시 AI로 해결

👑 관리자 워크플로우

# 1. 팀원 작업 병합
aos checkout main
aos merge feature/팀원작업      # 충돌 시 AI 자동 해결
aos push                        # main 업데이트 + 팀원 이메일 발송

# 2. 새 버전 릴리스
aos release patch               # 0.8.5 → 0.8.6 (자동 PyPI 배포)

📦 설치

pip install aos-git

최초 설정 (1회)

aos init           # git hooks + 알림 수신자/관리자 설정 (프로젝트마다 1회)
aos setup          # AI + SMTP + 토큰 (내 PC에서 1회)

aos init은 프로젝트마다 1번, aos setup은 내 PC에서 1번만 하면 됩니다.

업데이트 (이미 사용 중인 사람)

pip install --upgrade aos-git
aos doctor           # 환경 정상 확인
aos init --hooks-only    # 새 pre-push hook으로 교체

🩺 문제 해결

aos doctor                  # 한 방에 진단 (메일 안 올 때 첫 단계)
aos doctor --send-test      # SMTP 실제 테스트 메일 발송

자주 보는 ✗ 와 해결

📖 전체 명령어 레퍼런스

❓ FAQ

처음 사용자

Q: aos init과 aos setup은 뭐가 다릅니까? aos init은 프로젝트별로 실행 (hooks + 알림 수신자), aos setup은 내 PC에서 1회만 실행 (AI + SMTP).

Q: SMTP 비밀번호는 어디에 저장되나요? ~/.aos/config.toml에 로컬에서만 저장됩니다. 프로젝트에는 host/port/sender만 저장되고 비밀번호는 공유되지 않습니다.

Q: --hooks-only는 언제 쓰나요? pip install --upgrade 후 새 hook 버전으로 교체할 때, 또는 다른 PC에서 clone 후 hook만 재설치할 때.

Q: aos sync와 aos pull은 뭐가 다릅니까? aos pull은 현재 브랜치에 origin의 같은 이름 브랜치를 가져오고, aos sync는 main(기준 브랜치)의 변경분을 내 작업 브랜치에 반영합니다.

Q: aos install과 aos claude install은 뭐가 다릅니까? aos install은 aos CLI 전역 skill을 설치하고, aos claude install은 프로젝트별로 Claude Code 연동을 설정합니다.

메일 알림 안 와요

Q: push는 성공했는데 메일이 안 왔어요. pre-push hook 출력에 [pre-push][WARN]이 있었는지 확인하세요. aos doctor로 SMTP 연결 상태를 진단하세요. 대부분 SMTP 비밀번호 미설정이 원인입니다.

Q: "SMTP 비밀번호 미설정"이라고 떠요. aos setup --notify로 SMTP 비밀번호(앱 비밀번호)를 다시 입력하세요. 비밀번호는 ~/.aos/config.toml에만 저장되고 재설치 시 사라집니다.

Claude Code 연동

Q: Claude Code와 aos를 함께 쓸 수 있나요?

aos install              # 전역 skill 설치 (1회)
aos claude install      # 프로젝트별 연동 (저장소마다 1회)