JARVIS

Just A Rather Very Intelligent System — a voice for Claude Code.

JARVIS is a British butler who sits on top of the Claude Code you already pay for. You talk to him. He brainstorms a project with you out loud, one question at a time; when you have settled on something he writes the design down as a file in your project; then he starts a real Claude Code session on it and drives it through plan → review → execute. While it runs he watches every Claude Code session on your machine, and when one of them is stuck waiting on a human he tells you which one, out loud, without you having to look.

"Will do, sir."

What you actually look at while you talk to him: frontend/src/orb.ts, rendered live. The audio driving the pulse is synthetic — a speech-shaped envelope fitted to a measurement of the real analyser, not a recording of his voice — but every pixel is that file running. Regenerate with scripts/make_orb_loop.py.

The whole dashboard, clicked through. Fictional sample data throughout — the projects, prompts, people and figures in every screenshot on this page are invented.

What it costs

No AI API usage, and none is possible. JARVIS's brain is a Claude Code process running on your Claude subscription — the same login you use in the terminal. There is no Anthropic API key anywhere on the voice path, and there is no way to accidentally put one there:

# claude_env.py
SCRUBBED_ENV_PREFIXES = ("CLAUDE_CODE_", "ANTHROPIC_")
SCRUBBED_ENV_KEYS = {"CLAUDECODE"}

Every Claude Code process JARVIS spawns — the brain and every build — is launched through claude_env.child_env(), which strips every ANTHROPIC_* variable out of the environment first. This is deliberate and it is not a nicety: the CLI silently prefers an inherited ANTHROPIC_API_KEY over your login, and claude auth status goes on reporting loggedIn: true while billing quietly moves onto the key. So JARVIS removes the key rather than trusting itself not to pass it. Leave one in your .env if you like — the startup check will warn you it is there, and the brain will still never see it.

So the number that matters is not a dollar figure — it is how much of your subscription's two windows is gone. Fictional sample data.

The one thing you pay for is Fish Audio, which gives JARVIS his voice. Be aware there is no fallback: tts.py returns nothing without FISH_API_KEY, so JARVIS goes silent and his replies appear as text in the browser instead. If you would rather use a different TTS, that is a small, well-isolated file to replace — see Make it yours below.

What he does

• Brainstorms out loud. The conversation is the design phase. He asks one question at a time, offers two or three approaches, and does not start anything until you have agreed on one.
• Writes the design down. What you agreed goes on disk as docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md inside the project being built — before a single process is spawned. You can read it back by numbered section and approve it by voice, or open it on the dashboard.
• Drives the build. A build is a real claude -p session handed a brief that tells it to write a phased plan, review that plan against the spec, then execute it task by task under test-driven development, ticking the plan's checkboxes as it goes. "How far has it got" is answered by reading those checkboxes, not by guessing.
• Watches every Claude Code session on the machine — not just his own. Ask "which of my sessions are waiting on me?" and he checks live. He can post a message into one, and answer a permission prompt for one running in Terminal.app by pressing a single key.
• Interrupts you when it matters. A session that needs a human gets said out loud immediately; a session that merely finished gets batched into one sentence at the next pause. If nobody has the browser tab open, it becomes a macOS notification instead.
• Remembers. Long-term memory is a folder of plain Markdown files, one fact per file, with an index the brain always sees. You can read and edit it in any text editor.
• Records everything. Every Claude Code process JARVIS starts is a run: a row in SQLite with its prompt, project, status, token usage and the full event stream. Watch them live at /dashboard.

The Runs view. Every Claude Code process JARVIS starts is a row here, with the prompt that started it. Fictional sample data.

The dashboard has six tabs — Runs, Sessions, Memory, Specs, Projects and Usage. Usage shows what your subscription's five-hour and seven-day windows have left, and who spent it.

Sessions, with a blocked one open beside the list. The reason a session is stuck is the CLI's own words, not a guess. Fictional sample data.

Requirements

• macOS. Terminal control, window listing, screenshots and notifications all go through AppleScript. There is no Linux or Windows path today.
• Google Chrome. Not a preference — a constraint. The microphone uses the Web Speech API (SpeechRecognition / webkitSpeechRecognition, see frontend/src/voice.ts), which Firefox has never implemented. There is no server-side transcription to fall back on.
• Claude Code, installed and logged in. npm install -g @anthropic-ai/claude-code (2.1.224 or newer), then run claude once and log in. This is what JARVIS runs on.
• Python 3.11+ and Node.js 18+.
• A Fish Audio API key. Required; there is no fallback voice.

Setup

git clone <your fork of this repo> jarvis
cd jarvis

cp .env.example .env

pip install -r requirements.txt
python -m playwright install chromium    # for read_page / look_at_page

cd frontend && npm install && cd ..

Fill in the .env. .env.example documents the lot; the short version is one required key and three optional ones:

FISH_API_KEY=...            # required, no fallback
# JARVIS_BRAIN_MODEL=sonnet # optional: the brain's model
# FISH_VOICE_ID=...         # optional: a different voice
# USER_NAME=Tony            # optional: what he calls you

Generate the certificates. These are not optional:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'

server.py serves HTTPS whenever cert.pem and key.pem sit beside it, and frontend/vite.config.ts proxies /api and /ws to https://localhost:8340. Without the pair the backend serves plain HTTP, the dev server's proxy cannot reach it, and every API and WebSocket call through the front end fails with a 500 while the page itself still loads — a confusing way to spend an evening. Generate them once and forget about them.

Then, in two terminals:

python server.py --host 127.0.0.1        # terminal 1
cd frontend && npm run dev               # terminal 2

Open Chrome at http://localhost:5173, click the page once to allow audio, and speak. The dashboard is at http://localhost:5173/dashboard.html.

Who can reach it. --host defaults to 127.0.0.1 — this machine only. Everything JARVIS serves acts with your full authority: POST /api/runs spawns claude --dangerously-skip-permissions, /api/sessions reads every Claude Code conversation you have. A strict Origin check stands in front of every WebS