원문 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 프로세스도 띄우지 않는다.
  • 라이선스는 개인·비상업 무료이고 상업 이용은 유료 라이선스다. 엄밀한 의미의 오픈소스 라이선스는 아니다.

관련