Choavis Agent

Slack에서 Claude Code를 제어하는 로컬 에이전트.

Choavis Agent는 로컬 Claude Code CLI를 Slack과 연결합니다. 터미널 앞에 앉아 있지 않아도 Slack 메시지 하나로 로컬 머신에서 개발 작업을 수행할 수 있습니다.

Claude Code CLI가 할 수 있는 건 전부 Slack에서 가능합니다. 터미널로 할 수 있는 모든 것을 Slack으로 제어할 수 있습니다.

빠른 시작

사전 준비: Node.js 20+, Claude Code CLI

# 대화형 설정 (Slack 앱 생성 안내 + .env 생성)
npx -y choavis-agent@latest onboard

# 실행
npx -y choavis-agent@latest start

Slack 앱 설정이 처음이라면? → Slack 앱 설정 가이드

GUI 대시보드 (Electron)

Choavis Agent Dashboard는 에이전트 상태를 한눈에 모니터링하고 제어할 수 있는 Electron 데스크톱 앱입니다.

주요 기능:

• 실시간 WebSocket 연결로 세션/이벤트 모니터링
• Agent 재시작/중지 제어 버튼
• Slack 스레드 링크로 대화 바로가기
• 허용 사용자 표시 (Slack 실명)

# 빌드 후 실행
pnpm run build && pnpm run start

자세한 내용은 GUI 대시보드 가이드를 참고하세요.

동작 원리

Choavis Agent는 Claude Code를 subprocess로 실행하고, Slack을 UI로 연결하는 브릿지입니다. Slack 스레드 하나가 Claude Code 세션 하나에 대응하며, 각 스레드는 독립적인 컨텍스트를 유지합니다.

활용 예시

언제 어디서나 코딩

지하철, 카페, 침대 — 스마트폰에 Slack만 있으면 됩니다.

나: "AuthController에 JWT 리프레시 토큰 로직 추가해줘"
나: "테스트 돌려보고 실패하면 고쳐줘"
나: "커밋하고 PR 만들어줘"

Claude Code를 subprocess로 호출하기 때문에 프로젝트에 정의된 CLAUDE.md, sub agent, skill을 그대로 활용합니다. 터미널에서 직접 claude를 실행하는 것과 동일한 환경입니다.

여러 프로젝트를 동시에

$project 커맨드로 프로젝트를 전환하면서 작업할 수 있습니다.

나: "$project api"
나: "주문 API에 페이지네이션 추가해줘"

나: "$project frontend"
나: "주문 목록 페이지에 무한 스크롤 적용해줘"

개발 외 작업

터미널로 할 수 있는 건 뭐든 가능합니다.

나: "Downloads 폴더에 있는 PDF 파일들 날짜별로 정리해줘"
나: "지난주 회의록 초안 작성해줘, 프로젝트 커밋 로그 참고해서"
나: "afplay로 ~/Music에 있는 mp3 틀어줘"

기능

| 기능 | 설명 | |---|---| | 실시간 스트리밍 | Claude가 작업하는 동안 Slack 메시지가 실시간으로 업데이트 | | 스레드 = 세션 | 각 Slack 스레드가 독립적인 Claude Code 세션을 유지 | | 멀티 프로젝트 | 여러 저장소를 등록하고 $project 커맨드로 전환 | | 14개 내장 커맨드 | 중지, 재개, 압축, 모델 전환, 권한 모드 등 | | 도구 승인 | plan/acceptEdits 모드에서 Slack 버튼으로 도구 사용 승인/거부 | | 사용량 추적 | 사용자별 토큰 소비량 및 비용을 일/주/월 단위로 집계 | | 영구 메모리 | $memory로 저장한 메모가 이후 모든 대화에 자동 주입 | | 자동 컨텍스트 압축 | 컨텍스트 창이 가득 차면 자동으로 압축 후 계속 | | Atlassian 연동 | Jira 이슈 관리 + Confluence 위키 검색/편집을 Slack에서 바로 사용 |

커맨드

자연어로 요청하되, 에이전트를 직접 제어할 때는 커맨드를 사용합니다.

| 커맨드 | 설명 | |---|---| | $stop | 현재 작업 즉시 중단 | | $new | 세션 초기화 (새 대화 시작) | | $compact | 대화 컨텍스트 수동 압축 | | $resume <id> | 세션 ID로 기존 세션 재연결 | | $model [이름] | 모델 확인/변경 (sonnet, opus, haiku) | | $status | 현재 설정 및 에이전트 상태 | | $sessions | 모든 활성 세션 목록 | | $session-info | 현재 스레드의 세션 정보 | | $usage [범위] | 사용량 대시보드 (me, week, month) | | $project <이름> | 작업 디렉토리 전환 | | $inject <id> <msg> | 특정 세션에 메시지 주입 | | $memory <내용> | 영구 메모리에 메모 저장 | | $permission [모드] | 권한 모드 변경 (bypass, plan, accept) | | $help | 도움말 |

설정

choavis-agent init으로 .env를 생성하거나, 직접 환경변수를 설정합니다.

| 변수 | 필수 | 기본값 | 설명 | |---|---|---|---| | SLACK_BOT_TOKEN | ✅ | — | Bot OAuth Token (xoxb-...) | | SLACK_APP_TOKEN | ✅ | — | App-Level Token (xapp-...) | | ALLOWED_SLACK_USERS | ✅ | — | 허용 사용자 ID (쉼표 구분) | | CLAUDE_MODEL | — | CLI 기본값 | 모델 (sonnet, opus, haiku 또는 전체 ID) | | AGENT_PERMISSION_MODE | — | bypassPermissions | 권한 모드 | | JIRA_URL | — | — | Atlassian Cloud URL (https://your-domain.atlassian.net) | | JIRA_USERNAME | — | — | Atlassian 이메일 (Jira + Confluence 공용) | | JIRA_API_TOKEN | — | — | Atlassian API 토큰 | | AGENT_WORK_DIR | — | 현재 디렉토리 | 기본 작업 디렉토리 | | AGENT_PROJECTS | — | {} | 프로젝트 맵 (JSON). 예: {"api":"/home/user/api"} | | MAX_CONCURRENT_AGENTS | — | 5 | 최대 동시 프로세스 수 |

| 변수 | 기본값 | 설명 | |---|---|---| | CLAUDE_PATH | claude | Claude Code CLI 경로 | | SESSION_DAILY_RESET_HOUR | 4 | 세션 자동 리셋 시각 (0–23) | | SESSION_IDLE_RESET_MINUTES | 120 | 유휴 세션 리셋 시간 (분) | | SESSION_STORE_PATH | data/sessions.json | 세션 데이터 저장 경로 | | USAGE_DATA_DIR | data/usage | 사용량 데이터 디렉토리 | | MEMORY_DATA_DIR | .memory | 메모리 파일 디렉토리 |

도구 승인

AGENT_PERMISSION_MODE가 plan 또는 acceptEdits일 때, Claude Code는 도구 사용 전에 Slack 버튼으로 승인을 요청합니다.

🔧 도구 사용 승인 요청
도구: Bash
내용: git commit -m "fix: null 체크 추가"

[승인]  [항상 허용]  [거부]

• 읽기 전용 도구(Read, Glob, Grep)는 자동 허용
• 2분 내 응답 없으면 자동 거부
• 승인 서버는 127.0.0.1에만 바인딩 — 외부 접근 불가

개발

git clone https://github.com/musinsa/choavis-agent.git
cd choavis-agent
npm install
cp .env.example .env    # 환경변수 설정

npm run dev              # 개발 모드 (tsx)
npm run build            # 빌드
npm test                 # 테스트

기여를 환영합니다. 큰 PR 전에 이슈를 먼저 열어주세요.

라이선스

MIT