원문 ethanplusai/jarvis 저장소 메타(2026-10-10
gh api확인): 개인·비상업 무료, 상업 이용은 별도 라이선스(GitHub 표기 NOASSERTION). 주 언어 Python, 2026-03-26 생성, Stars 약 850, 최신 릴리스v2.0.0(2026-09-10).
한 줄 요약
이미 쓰고 있는 Claude Code 위에 영국식 집사 목소리를 얹은 비서다. 말로 프로젝트를 함께 구상하고, 합의한 설계를 파일로 남긴 뒤, 실제 Claude Code 세션을 띄워 계획→검토→실행으로 끌고 간다. 그동안 머신의 모든 Claude Code 세션을 지켜보다가 사람 입력을 기다리며 멈춘 세션이 생기면 소리 내어 알려준다.
하는 일
- 말로 브레인스토밍: 한 번에 질문 하나, 접근법 두세 개를 제시하고, 합의 전에는 아무것도 시작하지 않는다.
- 설계를 파일로 남김: 합의 내용을 빌드 대상 프로젝트 안
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md에 쓴다. 번호 매긴 섹션 단위로 읽어 주고 음성으로 승인받는다. - 빌드 실행: 빌드는 실제
claude -p세션이다. 단계별 계획을 쓰고, 스펙과 대조해 검토하고, TDD로 작업을 하나씩 실행하며 계획서 체크박스를 채운다. “어디까지 했어?”에는 이 체크박스를 읽어 답한다. - 세션 감시: 자기가 띄운 것만이 아니라 머신의 모든 Claude Code 세션을 본다. 세션에 메시지를 넣거나, Terminal.app에서 도는 세션의 권한 프롬프트에 키 하나로 답할 수 있다.
- 알림 우선순위: 사람이 필요한 세션은 즉시 말하고, 그냥 끝난 세션은 다음 쉬는 틈에 한 문장으로 묶는다. 브라우저 탭이 닫혀 있으면 macOS 알림으로 보낸다.
- 기억: 장기 기억은 사실 하나당 마크다운 파일 하나인 폴더와, 두뇌가 항상 보는 인덱스다. 텍스트 편집기로 직접 고칠 수 있다.
- 기록: JARVIS가 띄운 모든 Claude Code 프로세스는 SQLite의 run 한 행(프롬프트·상태·토큰·전체 이벤트 스트림)이 되고, 대시보드(Runs·Sessions·Memory·Specs·Projects·Usage 6개 탭)에서 본다.
비용 구조
두뇌는 사용자 Claude 구독으로 도는 Claude Code 프로세스라 Anthropic API 비용이 없다. 띄우는 모든 자식 프로세스는 claude_env.child_env()를 거쳐 ANTHROPIC_*·CLAUDE_CODE_* 환경 변수를 지운 채 실행된다. README는 이유를 이렇게 든다. CLI가 상속받은 ANTHROPIC_API_KEY를 로그인보다 조용히 우선하고, claude auth status는 계속 loggedIn: true를 보고하면서 과금만 키로 옮겨 간다는 것이다. 그래서 대시보드의 핵심 수치도 달러가 아니라 구독의 5시간·7일 창 잔량이다.
돈이 드는 건 음성을 내는 Fish Audio 하나다. FISH_API_KEY가 없으면 대체 음성 없이 침묵하고 답이 브라우저에 텍스트로만 뜬다. TTS는 tts.py 한 파일이라 교체가 쉽다.
구조
마이크 → Chrome Web Speech API → WebSocket → FastAPI(server.py)
→ 두뇌(brain.py): 장수명 `claude -p` 프로세스 하나(기본 Sonnet)
├ speech.py → Fish Audio → 스피커
├ MCP 도구(jarvis_mcp.py → POST /internal/tool) → RunExecutor → SQLite
└ session_watch.py(머신의 모든 Claude Code 세션)
- 두뇌는 턴마다 새로 띄우지 않는 영속 프로세스다. 답을 문장 단위로 잘라 스트리밍하므로 뒷부분을 쓰는 중에 앞 문장이 이미 발화된다.
- run의 두 불변식: 모든 run은 반드시 종료 상태(
succeeded·failed·timed_out·cancelled)에 도달한다. 상태 전이는 알림보다 DB 기록이 먼저이고, WebSocket은 캐시 무효화 힌트일 뿐 진실의 원천이 아니다. - MCP 연결은 직접 선택: 기본 연결은 없다.
data/jarvis/connections.json에mcpServers블록을 넣는다.--strict-mcp-config로 실행하므로~/.claude.json이나 Claude Desktop의 서버는 따라오지 않는다. 도구 하나당 매 턴 약 250토큰을 쓴다고 실측치를 밝힌다. 예전 버전의 Apple 캘린더·메일·메모 연동은 첫 실행부터 권한 프롬프트 3개를 띄운다는 이유로 뺐다. - 성격은
jarvis_home/CLAUDE.md, 음성은tts.py, 도구는server.py의TOOL_HANDLERS와brain.py허용 목록, 외형은 대시보드 테마 CSS 4개와 Three.js 파티클 구체(orb.ts)로 분리돼 있어 갈아 끼우기 쉽다.
의도적으로 감수한 신뢰 결정 5가지
README가 “버그가 아니라 설계상 트레이드오프”라며 실행 전에 알라고 적어 둔 항목이다.
| 결정 | 내용 |
|---|---|
| 디렉터리 이름이 발화에 섞임 | 세션을 이름으로 부르려고 디렉터리명·대화 제목에서 최대 약 60자를 읽어 말한다. 허용 문자에 <·>·"·=가 없어 구조를 가진 가짜 지시는 못 넣고, 단어만 넣을 수 있다. |
| 오염 게이트는 행동만 막음 | 웹·파일·다른 세션·화면·MCP에서 읽은 턴은 그 턴 동안 모든 실행 도구를 거부한다. 다만 심어진 제안 문장은 컨텍스트에 남는다. 보장은 “사용자가 깨끗한 턴에 자기 말로 다시 요청해야 한다”까지다. |
| 모든 run은 전권 실행 | TTY가 없어 권한 프롬프트에 답할 수 없으므로 기본으로 --dangerously-skip-permissions를 붙인다. 지우는 건 환경 변수뿐이고 파일시스템 접근은 막지 않는다. |
| 루프백은 신뢰 | 기본 바인드는 127.0.0.1이다. localhost:5173–5180 Origin을 보내는 로컬 프로세스는 브라우저 탭과 같은 권한(run 시작 포함)을 얻는다. Origin이 없는 클라이언트는 0600 권한의 tool-token을 제시해야 한다. |
| 오디오 ack 유실 시 청취 저하 | 탭이 죽으면 짧은 대답(“yes”)이 자기 목소리 에코로 오인돼 최대 45초간 버려질 수 있다. |
요구 사항과 한계
- macOS 전용(터미널 제어·창 목록·스크린샷·알림이 모두 AppleScript)이고 Chrome 필수(Web Speech API, 서버 측 음성 인식 대체 경로 없음)다.
- Claude Code 2.1.224 이상 로그인, Python 3.11+, Node.js 18+, Fish Audio 키가 필요하다.
cert.pem/key.pem이 없으면 백엔드가 HTTP로 떠서 Vite 프록시가 연결하지 못하고 API 호출이 500으로 실패한다. 자체 서명 인증서를 먼저 만들어야 한다.- Chrome 마이크 권한은 포트까지 포함한 Origin 단위다. Vite가 5174로 뜨면 권한이 따라오지 않고 재요청도 없이 조용히 거부된다.
- 테스트 약 1,640개는 네트워크·화면을 건드리지 않고, 실제
claude프로세스도 띄우지 않는다. - 라이선스는 개인·비상업 무료이고 상업 이용은 유료 라이선스다. 엄밀한 의미의 오픈소스 라이선스는 아니다.
관련
- 2026-08-22-free-on-github-my-jarvis-ai-assistant — 이름은 같지만 다른 프로젝트(jaredrhod). Claude Code 위에 음성·메모리·손 제스처 시각화를 얹은 비슷한 발상
- 2026-03-22-openjarvis — 역시 JARVIS를 표방하지만 로컬 우선 개인 에이전트 프레임워크
- 2026-04-16-lazyagent-coding-agent-tui · 2026-04-10-ccmonitor-claude-code-tui-dashboard — 여러 Claude Code 세션 관찰을 TUI로 푸는 접근
- moc-claude-code