Jarvis
A voice assistant that fits in one bash file.
Claude as its brain, the shell as its hands,
and a pixel-art Babel fish as its face.
Record → transcribe → think → speak runs on any Linux box: PipeWire, Python 3,
voxtype, Claude Code, Piper. Only his hands and his face need Omarchy.
Documentation · Drive the state machine · Français
SUPER + ALT + J press to speak, press again to answer
« Hey Jarvis » the same, without touching the keyboard
SUPER + ALT + ESCAPE stop whatever is in flight
Say « mets le thème clair » and the theme changes. Ask « pourquoi ma
dernière commande a échoué ? » and he reads your shell history and tells
you. Say « corrige le bug de scroll dans mon projet web » and he dispatches
a background coding session and reports back when it lands.
He answers in the language you spoke. He remembers yesterday. When he cannot
do something he writes down why, and later — while idle — he reads those
notes back and distils them into lessons he keeps.
What is worth stealing here
Even if you never run it, four things in this repository are designed to be
read and taken:
-
A state machine that cannot drift from its documentation. Eight states,
nine events, 38 of the 72 pairs legal — written out in prose above the code
in bin/jarvis-fsm.sh and frozen into a test fixture,
so the table and the paragraph explaining it fail together or not at all.
Drive it in your browser.
-
Cancelling that actually cancels. The state file records what the
machine is doing; a record beside it records which attempt is doing it.
Every stage carries the epoch it started on and goes quiet if that moved.
Each external stage runs in its own process group, because killing the group
is what reaches the subprocesses claude spawned for its own tools — a bare
pid never does, which is why aborting used to do nothing at all.
-
A memory that consolidates itself. Failures are written down as they
happen. When he is idle, a separate session reads them back and distils them
into lessons that become part of his persona. Interruptions go in a
different file on purpose: one line in the failure log was enough to
schedule a session that rewrites his personality, so pressing a key was
manufacturing permanent character changes.
-
A test suite for a voice assistant. More than 250 assertions, entirely offline:
a fake brain, a fake voice, a fake microphone that really dies on a signal.
No quota, no network, no sound, no microphone taken.
Will this run on your machine?
Honestly: partly, unless your machine looks a lot like mine. Jarvis is
three layers, and they fail independently, so it is worth knowing which one
you are getting.
| Layer | What it gives you | What it needs |
|---|
| The voice loop | record → transcribe → think → speak, the whole conversation | Linux, PipeWire, voxtype, Claude Code, Piper, Python 3 — portable |
| The hands | changing your theme, brightness, network, windows, launching apps | Omarchy and Hyprland — its CLI is his hands |
| The body | the fish in the corner, the speech bubble, the typed prompt bar | Quickshell via omarchy-shell |
Layer one runs anywhere with a microphone. Layers two and three are written
against a specific desktop and will not pretend otherwise: every call into
them is || true, so on a plain Linux box Jarvis still listens, thinks and
speaks — he just has nothing to touch and no face to make.
The reference machine is an M2 MacBook Pro running Asahi Linux under
macarchy (Omarchy plus a macOS-shaped layer).
bootstrap.sh fetches an arm64 or amd64 Piper build depending on where
you run it.
You also need a Claude account: the brain is claude -p, invoked once per
exchange. Nothing else in the pipeline leaves the machine.
Install
git clone https://github.com/macarchy/jarvis.git ~/Work/jarvis
cd ~/Work/jarvis
./bootstrap.sh # Piper, its voices, the Whisper model, the wake venv
./install.sh # the CLI symlink, the mascot plugin, the user units
omarchy-jarvis doctor
bootstrap.sh downloads ~300 MB that the repository deliberately does not
carry (see THIRD_PARTY.md); it is resumable and running it
twice fetches nothing. install.sh is idempotent too — re-running it is the
supported way to update after a git pull.
doctor is the answer to "is it working?": every dependency, green or red,
no guessing. Whatever it says is red, docs/troubleshooting.md
explains.
Install claude and voxtype yourself — they have accounts and configuration
of their own and are not Jarvis's to manage.
What leaves your machine
This matters more than the feature list, so it is here and not in an appendix.
The long version is docs/privacy.md.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
