choavis-personal-agent
v1.5.31
Published
Slack ↔ Claude Code bridge agent
Readme
왜 Choavis인가?
Claude Code는 강력하지만, 터미널 앞에 앉아 있어야 합니다.
Choavis Personal Agent는 그 제약을 없앱니다. Slack 메시지 하나로 로컬 머신의 Claude Code를 제어하세요. 지하철에서, 카페에서, 침대에서 — 스마트폰만 있으면 됩니다.
나: "AuthController에 JWT 리프레시 토큰 로직 추가해줘"
나: "테스트 돌려보고 실패하면 고쳐줘"
나: "커밋하고 PR 만들어줘"Claude Code CLI가 할 수 있는 건 전부 Slack에서 가능합니다. CLAUDE.md, sub agent, MCP, skill — 터미널과 동일한 환경이 그대로 동작합니다.
🚀 빠른 시작
데스크톱 앱 (권장)
- DMG를 열고 앱을
/Applications로 드래그 - 앱 실행 → 설정 위자드가 Slack 앱 생성을 안내
- 토큰 입력하면 끝
첫 실행 시 자동으로
~/.choavis-personal-agent/.env가 생성됩니다.
CLI
npx -y choavis-personal-agent@latest onboard # 대화형 설정
npx -y choavis-personal-agent@latest start # 실행- Claude Code CLI 설치
- Slack 앱 설정 (위자드가 안내합니다)
- Node.js ≥ 20
✨ 핵심 기능
실시간 스트리밍
Claude가 작업하는 동안 Slack 메시지가 실시간으로 업데이트됩니다. 도구 호출, 코드 작성, 파일 수정 과정을 라이브로 확인하세요.
스레드 = 세션
각 Slack 스레드가 독립적인 Claude Code 세션입니다. 여러 작업을 동시에 진행하고, 스레드별로 컨텍스트가 완벽하게 격리됩니다.
멀티 프로젝트
여러 저장소를 등록하고 프로젝트: 이름으로 즉시 전환. API, 프론트엔드, 인프라를 하나의 Slack 채널에서 관리하세요.
영구 메모리
기억해: 우리 팀은 conventional commit 사용해 — 한번 알려주면 이후 모든 대화에 자동 반영됩니다.
데스크톱 대시보드
Electron 앱으로 에이전트 상태를 한눈에 모니터링. 세션 관리, MCP 현황, 메모리 목록을 실시간으로 확인하세요.
MCP 연동
Jira, Confluence 등 외부 서비스를 MCP로 연결. 자체 API 클라이언트 없이 확장 가능한 아키텍처.
| 기능 | 설명 |
|---|---|
| 실시간 스트리밍 | Claude 작업 과정을 Slack에서 라이브 확인 |
| 스레드 세션 | 각 Slack 스레드 = 독립 Claude Code 세션 |
| 멀티 프로젝트 | 여러 저장소를 등록하고 프로젝트: 이름으로 전환 |
| 13개 내장 커맨드 | 중지, 재개, 압축, 모델 전환, 세션 제어, 메모리 관리 등 |
| 사용량 추적 | 사용자별 토큰 소비량 및 비용을 일/주/월 단위로 집계 |
| 영구 메모리 | 기억해:로 저장한 메모가 이후 모든 대화에 자동 주입 |
| 프로젝트 메모리 | .choavis/MEMORY.md를 자동 주입하고 Slack에서 갱신 |
| 자동 컨텍스트 압축 | 컨텍스트 창이 가득 차면 자동으로 압축 후 계속 |
| Atlassian 연동 | Jira + Confluence를 Slack에서 바로 사용 (MCP 기반) |
| 설정 위자드 | 첫 실행 시 Slack 앱 생성 안내와 토큰 입력으로 자동 설정 |
| GUI 대시보드 | Electron 앱으로 에이전트 상태 모니터링 및 제어 |
| Skills 시스템 | 마크다운 기반 자연어 워크플로우 정의 |
| 환경 진단 | doctor 커맨드로 CLI, 환경변수, MCP 상태 자동 점검 |
| 자동 업데이트 | GitHub Releases 기반 데스크톱 앱 자동 업데이트 |
💬 이런 걸 할 수 있습니다
나: "이 함수 리팩토링해줘. 테스트도 작성하고" → 코드 수정 + 테스트 생성
나: "PR #42 리뷰해줘. 보안 취약점 위주로" → 코드 리뷰
나: "이번 스프린트 진행 중인 Jira 이슈 보여줘" → Jira 연동
나: "스프린트 리뷰 리포트 작성해줘" → 자동 리포트
나: "Downloads 폴더에 있는 PDF 날짜별로 정리해줘" → 파일 관리
나: "Docker Compose로 로컬 환경 올려줘" → 인프라더 많은 활용 사례는 유즈케이스 가이드를 참고하세요.
🏗️ 아키텍처
┌─────────────┐ Socket Mode ┌──────────────────────┐ SDK ┌────────────┐
│ Slack App │ ◄──────────────────► │ Choavis Agent │ ◄──────────► │ Claude Code │
│ (클라우드) │ 실시간 양방향 │ (로컬 Node.js) │ subprocess │ (CLI/SDK) │
└─────────────┘ │ │ └────────────┘
│ ┌── Dashboard ────┐ │
│ │ Electron + React │ │
│ └─────────────────┘ │
└──────────────────────┘- Slack → UI 역할. Socket Mode로 방화벽 뒤에서도 동작
- Choavis Agent → 로컬에서 실행. Slack 메시지를 받아 Claude Code SDK에 전달
- Claude Code → 실제 작업 수행. 파일 수정, Git, 터미널 명령 등
모든 코드와 데이터는 로컬 머신에서만 처리됩니다. 외부 서버로 전송되지 않습니다.
📖 문서
| 문서 | 설명 | |---|---| | 활용 사례 | 코딩, 리뷰, DevOps, 데이터 분석 등 상세 유즈케이스 | | 커맨드 레퍼런스 | 13개 내장 커맨드 전체 목록 | | 설정 가이드 | 환경변수, 멀티 프로젝트, MCP 연동 | | Slack 앱 설정 | Slack 앱 생성 및 토큰 발급 가이드 | | GUI 대시보드 | Electron 데스크톱 앱 사용법 | | 아키텍처 | 시스템 구조 및 데이터 흐름 |
🛠️ 개발
git clone https://github.com/musinsa/choavis-personal-agent.git
cd choavis-personal-agent
pnpm install
cp .env.example .env
pnpm run dev # 개발 모드 (agent + frontend)
pnpm run build # 프로덕션 빌드
pnpm test # 테스트 실행src/
├── index.ts # 엔트리포인트
├── agent/ # Claude Code SDK 연동
│ ├── runner.ts # SDK query() 호출
│ ├── memory.ts # 영구 메모리
│ └── project-memory.ts # 프로젝트 메모리
├── slack/ # Slack 연동 (Bolt.js)
│ ├── handlers.ts # 메시지 수신/응답
│ └── formatter.ts # mrkdwn 변환
├── cli/ # CLI 커맨드
│ ├── doctor.ts # 환경 진단
│ └── mcp.ts # MCP 관리
└── api/ # 대시보드 API 서버
electron/ # Electron 메인 프로세스
frontend/ # React 대시보드
skills/ # 마크다운 기반 스킬