# JARVIS

> A voice assistant for Claude Code on macOS that brainstorms projects with you, drives builds, and alerts you out loud when a Claude Code session needs attention.

JARVIS (Just A Rather Very Intelligent System) is an open-source voice layer that sits on top of Claude Code, letting macOS users talk to their development environment in natural language. Built by Ethan Rogers and released under a personal-use license, it runs entirely on your existing Claude subscription — no separate Anthropic API key is required or even possible. The project reached v2.0.0 in September 2026 and has accumulated over 760 GitHub stars.

## What It Is

JARVIS is a voice-driven AI development assistant styled as a British butler. It wraps Claude Code's CLI (`claude -p`) with a conversational interface: you speak, it brainstorms, it writes a design document to disk, then it drives a real Claude Code session through a plan → review → execute pipeline. It also watches every Claude Code session running on your machine and tells you out loud — or via macOS notification — when one is blocked waiting for human input. The frontend is a Three.js particle orb rendered in Chrome; the backend is a FastAPI Python server communicating over WebSocket.

## Architecture and Key Components

JARVIS is built around a single long-lived `claude -p` brain process that receives your speech via Chrome's Web Speech API, processes it, and streams replies back sentence-by-sentence so the first words are spoken while the rest is still being written. Key layers include:

- **Voice path**: Chrome Web Speech API → WebSocket → FastAPI (`server.py`) → brain (`brain.py`) → Fish Audio TTS → speaker
- **Build pipeline**: `builds.py` writes a spec to `docs/superpowers/specs/`, spawns a `claude -p` run, and tracks progress via plan checkboxes
- **Session watcher**: `session_watch.py` monitors every Claude Code conversation on the machine; `session_steer.py` can post messages into a running session
- **Storage**: SQLite for runs and usage; plain Markdown files for long-term memory
- **Dashboard**: Six-tab web UI (Runs, Sessions, Memory, Specs, Projects, Usage) built in vanilla TypeScript with no framework

The environment management in `claude_env.py` deliberately strips all `ANTHROPIC_*` and `CLAUDE_CODE_*` variables from every spawned child process to prevent accidental API key billing.

## Platform Constraints and Requirements

JARVIS is explicitly macOS-only. Terminal control, window listing, screenshots, and notifications all go through AppleScript, and there is no Linux or Windows path. Google Chrome is required (not optional) because the microphone relies on the Web Speech API (`SpeechRecognition` / `webkitSpeechRecognition`), which Firefox has never implemented. Additional requirements include Claude Code CLI (v2.1.224 or newer), Python 3.11+, Node.js 18+, and a Fish Audio API key for text-to-speech — there is no fallback voice if the Fish Audio key is absent.

## Security Model and Trust Decisions

The README documents five deliberate trust trade-offs. Every spawned run passes `--dangerously-skip-permissions` because there is no TTY to answer permission prompts, giving each run full filesystem privileges in the target directory. A taint gate blocks all acting tools for any turn that reads from a web page, file, screenshot, or external MCP server — but this stops action, not persuasion, since planted suggestions remain in the brain's context until you speak again on a clean turn. Loopback (`127.0.0.1`) is trusted by default; `--host 0.0.0.0` widens trust to the LAN with a printed warning.

## MCP Integration and Extensibility

JARVIS ships with no external connections by default. Any MCP server can be added by dropping its `mcpServers` block into `data/jarvis/connections.json`; JARVIS runs with `--strict-mcp-config` so nothing from `~/.claude.json` or Claude Desktop reaches it unless explicitly configured. The README notes that each loaded MCP tool costs approximately 250 tokens of brain context per turn. Key customization seams are deliberately exposed: personality lives in `jarvis_home/CLAUDE.md`, voice synthesis is isolated in `tts.py` (one HTTP call, ~60 lines), and the Three.js orb is self-contained in `frontend/src/orb.ts`.

## Update: JARVIS 2.0

Version 2.0.0, published September 10, 2026, is the current release. The release is titled "JARVIS 2.0: runs on your Claude subscription," signaling a shift away from any separate API key model to running entirely on the user's Claude Max or Pro subscription. The project has an active test suite of approximately 1,640 tests and an open issues count of 17 as of the last update. The README explicitly invites contributions for non-macOS system integration, alternative TTS engines, and a mobile client.

## Features
- Voice-driven brainstorming and project design via conversation
- Writes design specs to disk as Markdown before starting any build
- Drives Claude Code sessions through plan → review → execute pipeline
- Watches all Claude Code sessions on the machine and alerts when one needs input
- macOS notifications when no browser tab is open
- Long-term memory as plain Markdown files
- SQLite run history with full event streams and token usage
- Six-tab dashboard: Runs, Sessions, Memory, Specs, Projects, Usage
- MCP server integration via connections.json
- Taint gate blocks acting tools after reading untrusted content
- ANTHROPIC_* environment variable scrubbing to prevent accidental API billing
- Three.js particle orb voice UI
- Subscription usage gauges (5-hour and 7-day windows)
- Customizable personality via CLAUDE.md
- Swappable TTS engine via tts.py

## Integrations
Claude Code CLI, Fish Audio (TTS), Chrome Web Speech API, AppleScript, MCP servers (any, via connections.json), Notion MCP server (example), SQLite, FastAPI, Vite, Three.js, Playwright

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source, Free tier available

## Version
v2.0.0

## Links
- Website: https://github.com/ethanplusai/jarvis
- Documentation: https://github.com/ethanplusai/jarvis
- Repository: https://github.com/ethanplusai/jarvis
- EveryDev.ai: https://www.everydev.ai/tools/jarvis-claude-code-voice