A local-first, voice-driven desktop assistant with a face.
Say its name. A 30,000-point particle sphere wakes, listens, thinks, and answers out loud — with speech, transcription, and wake-word detection all running on your own machine.
ChinOS is a desktop assistant you talk to. There is no text box and no chat log — just a sphere that reacts to the conversation:
| State | The sphere |
|---|---|
| Idle | Slow violet drift |
| Listening | Tightens and turns blue |
| Thinking | Warms to gold |
| Speaking | Pulses white in time with the voice |
The audio pipeline is entirely local. Your microphone stream never leaves the machine: silero-VAD finds where speech starts and stops, faster-whisper transcribes it, and Kokoro speaks the reply in a British voice. Only the transcript itself goes to Claude for reasoning.
- Talk, naturally. Say "Chinos" alone, or ride the question in on the same breath — "Chinos, what's the weather?". After every reply the mic stays open for about eight seconds, so follow-ups need no wake word.
- Answer from your own notes. Point it at a folder of markdown (an Obsidian vault works unchanged) and ask about what's in it. Read-only, opt-in, off by default.
- Show you your notes as a galaxy. Say "show my brain" and the vault
renders as a rotating 3D graph — one star per note, one edge per
[[link]]. "Back to the sphere" dismisses it. - Read your day. "Do I have anything tomorrow?" queries Apple Calendar and Reminders through a small compiled EventKit helper.
- Drive a real browser. "Open example.com and read me the headline" runs in an actual Chrome window via chrome-devtools-mcp, then Chinos summarizes what it found aloud.
- Switch models mid-conversation. "Use Opus" / "switch to Sonnet" / "back to Haiku" — confirmed out loud. Haiku is the default.
Replies stream sentence-by-sentence into the voice, so Chinos starts talking before the full answer has finished generating.
Download the latest .zip from
Releases, unzip
it, and put ChinOS.app somewhere you can write to — your home folder is
easier than /Applications for the setup step below.
macOS will refuse to open it the first time, because the build is unsigned. Right-click the app, choose Open, then Open again in the dialog.
The download does not include the voice models. They are roughly 800 MB and machine-specific, so the app ships without them: launch it as-is and you get the sphere, but it will not hear or speak. To enable voice, create the Python environment inside the bundle once:
cd /path/to/ChinOS.app/Contents/Resources/sidecar
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txtThen relaunch. If that feels like a lot, build from source
instead — scripts/setup-sidecar.sh does the same thing in one command, and
it is the better-supported path today.
- macOS (Apple Silicon recommended — the voice models run on CPU)
- Node 20+
- Python 3.12
- Xcode command-line tools, for the calendar helper
git clone https://github.com/MattModeCode/ChinOS.git
cd ChinOS
npm install
bash scripts/setup-sidecar.sh # once: Python venv + ~800 MB of models
bash scripts/build-schedule-helper.sh # once: EventKit calendar helper
npm startA black window opens with the idling sphere. macOS prompts for microphone access on first launch — grant it, then say "Chinos".
The Claude backend signs in with this machine's Claude Code login, so no API
key is required. To bill through an Anthropic Console key instead, copy
.env.example to .env and set ANTHROPIC_API_KEY.
Everything optional lives in .env (copy from .env.example). ChinOS runs
with none of it set.
| Variable | Effect when set | When unset |
|---|---|---|
CHINOS_VAULT_DIR |
Chinos can list and read markdown notes under this folder, and the galaxy view renders them | The note tools are never registered; the galaxy has nothing to draw |
CHINOS_PROJECTS_DIR |
Chinos can answer code questions about projects here that have a graphify-out/graph.json |
The code-graph tool is never registered |
ANTHROPIC_API_KEY |
Bills through the Anthropic Console | Uses your Claude Code login |
Both knowledge paths are opt-in and read-only. Nothing is registered unless you point a variable at a folder, neither tool has a write path, and requested paths are rejected if they resolve outside the configured root.
Speech rate lives in sidecar/chinos_sidecar/config.py as SPEECH_SPEED
(default 1.3). Raise it for a brisker voice; past about 1.4 consonants
start to clip.
| Permission | Asked for | If you deny it |
|---|---|---|
| Microphone | At startup — required | System Settings → Privacy & Security → Microphone, then relaunch. A silent mic logs rms=0.0 on the sidecar's first frame. |
| Calendar / Reminders | On the first spoken schedule question | Chinos says so out loud; re-enable under Privacy & Security |
mic ─▶ silero-VAD ─▶ faster-whisper ─▶ "chinos"? ─▶ Claude Agent SDK ─▶ Kokoro TTS ─▶ speakers
endpointing transcript wake match tools + persona 24 kHz │
▼
amplitude events ─▶ the sphere pulses
src/main/— Electron main: window, sidecar spawn with crash restart (doubling backoff), NDJSON relay in both directions, transcript routing.src/main/backend/— Claude Agent SDK wrapper (session resume, streamed sentences), the persona, and the four tool servers (notes, code graph, schedule, browser). Each is registered only when its dependency exists.src/main/vault-graph.ts— parses[[links]]into a graph and runs a seeded force layout, so the renderer only ever draws.src/renderer/— Three.js particle sphere (vertex-shader simplex displacement, UnrealBloom) and the galaxy scene.sidecar/chinos_sidecar/— the Python voice loop. stdout is protocol, stderr is logs, and every tunable is inconfig.py.
The wake word is matched from the whisper transcript rather than a dedicated wake model, so only the literal name triggers it.
npm run typecheck # tsc
npm test # vitest
npm run lint # eslint
cd sidecar && .venv/bin/python -m pytest # sidecar tests
# debug the microphone alone
sidecar/.venv/bin/python -m chinos_sidecar --mic-checkBuild a distributable:
npm run make # out/make/zip/darwin/...Built on Electron, Three.js, the Claude Agent SDK, faster-whisper, silero-VAD, and Kokoro-82M.
MIT © 2026 Crowvic