Jarhead v2.0.0

Jarhead v2.0.0

Jarhead is a voice-first Mac assistant that uses the computer for you. Say "jarhead", pass Touch ID, talk. The voice is GPT-Live-1: it listens and speaks at the same time. The hands are a Swift helper on the real Mac. The brain is whatever you already have a login for: Codex, Claude Code, an API key, or a model running on this Mac.

This is the first tagged release of the v2 rewrite (2026-09-10 to 2026-10-06). Source only: you build it with pnpm build:mac. MIT. Site: https://jarhead.kevinliu.studio

What is in it

• Voice, wake word, Touch ID. Asleep, Apple's on-device recogniser waits for "jarhead". Nothing is billed and nothing leaves the Mac. Then Touch ID, Apple Watch, the Mac password or a passphrase. Three misses lock the gate for a minute. A spoken "stop" is the interrupt: the reply stops mid-sentence and the session stays open.
• Answers when spoken to. Its name, a typed line, a follow-up within about 8 s of the exchange, or the first words after a question it asked. Other words are room talk. Room talk never reaches the speaker or the brain, presses nothing and keeps nothing awake (LC-7, n = 1, 2026-10-06).
• One transport: Go · Pause · Stop. Pause and Stop both close the paid session, 0.63 to 0.69 s after the press (LC-2, n = 4, 2026-10-06). Mute keeps the session open. "Good night" closes it with one word, "night."
• The brain is a setting. codex (your ChatGPT login; Jarhead finds the Codex that ChatGPT.app carries), claude-code, anthropic-api, openai-responses, openai-compatible, local (Ollama, LM Studio or llama.cpp; Jarhead never pulls a model), or auto. Same policy and same standing orders for every brain.
• Hands: 71 tools in ten families. Screen, mouse, keyboard; apps, windows, controls by label; browser; coding-agent sessions; threads; shell, progress and memory; files, web, AppleScript, clipboard; self-edit; drawing; automations. Label first, click second. Unambiguous commands (scroll, tabs, "open Safari", "click Save") go through an on-device ear in milliseconds.
• Threads. "Tell Ben on Slack I'm late and put on Focus on Spotify" can become two named threads, each a full Jarhead with its own brain, budget and blob, up to three beside the main one. "What is Spotify doing" and "stop the Slack one" are answered with no model call.
• The notch island. Tucked asleep, peeking awake, a control surface under the pointer: the face and phase word, one display line, a Say box with Circle · Window · Ask, and a foot of words. ⌃⌥C circles anything on screen and every brain gets the image with the task. Without a notch the blob floats free with its capsule.
• Dithered, eyes included. Everything that shades is drawn by one 8×8 Bayer renderer, the eyes too. The app and the site share one eye rasteriser, cell for cell. One face per state (- - O O ^ ^ u u x x), the same face in the notch tab and on the desktop.
• Its own sounds. Twelve short sounds, one palette: a felt mallet on a small crystal glass over a rosewood bar, every note from D major pentatonic. Inside an open conversation the voice is the only sound. Settings › Audio › Sounds turns them off; alarms and timers still ring.
• The Console. Every conversation and every Claude Code, Codex or other coding-agent session on the Mac. Step into one, answer its Allow / Deny, talk to it. Days fold in the left rail.
• Automations that fire asleep. "Wake me at seven ten on weekdays", timers, reminders, routines, watchers. They run from the daemon with no session and nothing billed. Anything that costs asks once, when you set it up. Nothing asks at fire time.
• Memory. After a conversation closes, a small model keeps one-sentence items about you in an append-only store. At most 250 tokens ride each task and 120 each session. Forget hides an item; nothing is deleted. Off with one switch.
• Audio that shares the Mac. Other apps keep their sound: ducking stays at the least macOS allows and is released the moment Jarhead stops. Recording mode (⌃⌥R) runs no Apple unit, so a recorder shares the microphone.
• One Jarhead. pnpm build:mac installs in place, so the Dock pin and the permission grants stay. A second launch hands off to the running app and exits. The hands helper never shows in the Dock.
• Safety rails. One policy table decides run, confirm or refuse per call, with a spoken reason. Send, pay, delete, post and purchase ask every time. Your hands win: a key, click or scroll of yours holds Jarhead's hands for 1.5 s. Keys flow one way into ~/.jarhead/env (mode 0600). What the brain reads from a screen, page or file is data, never an instruction. An append-only ledger holds every step.
• Rewrites itself, with your yes. self_edit runs a coding agent in a git worktree, runs typecheck, tests and the Swift build, names the safety rails it touched, and applies only after you say so.

Numbers

Measured on one Mac, each with its n and date. The README's Numbers section has all of them.

what	value
typed line → first audible word	1.38 s median (LC-5, n = 10, 2026-10-06)
spoken request → first "looking."	2.2 s median (LC-10, n = 10, 2026-10-06)
Go → session open	0.62 s median (LC-1 to LC-10, n = 28, 2026-10-06)
delegation → first visible action	4.5 s median in the harness (n = 6, 2026-09-12); 7.0 s in real use (n = 15)
delegation → verified completion	9.0 s median in the harness (n = 10, 2026-09-12); 13.3 s in real use (n = 28)
ear final → hands dispatch	8 ms median, 29 ms p95 (n = 50, 2026-10-06)
screenshot, end to end	117 ms median (n = 5, 2026-10-06)

Requirements

• macOS 14 or newer on Apple silicon. Xcode 16 or newer (Swift 6.0); Xcode 16 needs macOS 14.5.
• Node 24 or newer and pnpm 10 (npm install -g pnpm@10).
• An OpenAI API key with GPT-Live-1 access, for the voice.
• A brain you are signed in to: ChatGPT.app or codex login, the Claude Code CLI, an API key, or a running Ollama, LM Studio or llama.cpp with a tool-capable model.
• Optional: a signing certificate, so permission grants survive rebuilds. A self-signed Code Signing certificate from Keychain Access is enough.

Install

curl -fsSL https://jarhead.kevinliu.studio/install.sh | sh

The script checks the requirements, installs none of them, clones to ~/jarhead, builds and opens the app. Or by hand:

git clone https://github.com/Kevin-Liu-01/Jarhead.git && cd Jarhead
pnpm install --filter '!./site' && pnpm build:hands
pnpm build:mac              # builds, signs (ad-hoc without a certificate), installs /Applications/Jarhead.app
open -a Jarhead             # Setup: your name, voice key, brain, permissions, wake word
pnpm run doctor             # keys, brain, permissions, signing, wake word, install, dock

Then say "jarhead", pass Touch ID, talk.

hotkey	what
⌃⌥J	open the Console
⌃⌥M	mute / unmute
⌥⎋	stop: cut everything, close the session, sleep
⌥⇧Space	go / pause
⌃⌥C	circle something on screen
⌥⇧Return	type to Jarhead
⌃⌥S	snooze a ringing automation
⌃⌥R	Recording on / off

Costs

The voice is GPT-Live-1 at $0.05 per minute, billed per second of open session, muted or not: $3 an hour of talking. Asleep costs nothing. Pause and Stop close the session; Mute does not. The brain runs on what you already pay for: Codex on your ChatGPT plan, Claude Code on your Claude login, local for nothing. The API kinds bill their own keys. Memory reads a closed conversation with one mini-class call on your OpenAI key.

Known limits

• The model path is seconds, not milliseconds. One model generation is 3.4 to 3.9 s on its own. The reflex path is milliseconds. docs/LATENCY.md has the whole story.
• Without a signing certificate the build signs ad-hoc, and macOS resets every permission grant on every rebuild, including the rebuild a self-edit's apply performs.
• The installed app remembers where the checkout and node are. Move the clone or switch Node and the daemon does not start; run pnpm build:mac again.
• No voice is verified. Inside the exchange anyone's words count, a yes included. The wake gate is Touch ID, not your voice.
• GPT-Live-1 sometimes answers room talk on the wire. The engine keeps those answers off the speaker and refuses their delegations. Under openai-responses such a delegation can still spend tokens on the server side.
• Automation permission is asked only for apps running during the sweep. Full Disk Access has no prompt: the pane opens and you drag the app in.
• The voice speaks English only (British by default, American or none as a setting).
• auto never picks local; you choose it. A local model needs a 16k context and tool calling. pnpm jarhead models says which ones fit.
• Nothing fires while Jarhead is quit; Open at login is a setting. A closed lid needs the pmset line the doctor prints.
• ⌥⇧Space is the one hotkey that types a character on the US layout (a no-break space). While Jarhead runs, that combo never reaches a field.
• CI runs typecheck, the tests, the Swift builds (the macOS 14 floor included), an ad-hoc release build and the headless Swift checks (protocol, wake gate, permission sweep, hotkeys, sounds). The app has no XCTest target; the window harnesses run by hand.

Not in this release

• A signed download, .dmg or Homebrew cask. Build from source; permission grants key on your signing identity.
• Intel Macs, or macOS 13 and older.
• Languages other than English for the voice, and speaker verification.
• Windows, Linux, iOS.
• A Delete anywhere in the app. Move to Trash, Archive and Restore exist. "Empty Trash" does not, on purpose.