@gotcos/glasses-server 6.1.0

package/.cos-profile.example.json

@@ -0,0 +1,7 @@
+{
+  "owner_name": "Your Name",
+  "owner_speaker_label": "Me",
+  "vocabulary": ["NameOne", "NameTwo", "YourCompany", "ProductName"],
+  "whisper_corrections": "{\"Soundalike\": \"YourName\"}",
+  "negative_rules": []
+}

package/.env.example

@@ -0,0 +1,44 @@
+# ── COS Glasses Server — configuration ──────────────────────────────────
+# Lives at ~/.cos-glasses/.env (created on first run). Everything here is
+# OPTIONAL — the server boots and chats with zero config as long as the
+# Claude Code CLI is installed and logged in.
+
+# ── PHONE ACCESS ────────────────────────────────────────────────────────
+# The glasses app (on your iPhone) reaches this server over your network or
+# mesh. The launcher sets 0.0.0.0 for you; set 127.0.0.1 to restrict to the
+# local machine only. (The IP allowlist always blocks public internet traffic.)
+BIND_HOST=0.0.0.0
+
+# HTTP port the server listens on. HTTPS auto-enables on 3143 if you add
+# cert.pem + key.pem under server/certs/ (optional; iOS WebView prefers HTTPS).
+# PORT=3141
+
+# ── AUTH ────────────────────────────────────────────────────────────────
+# A token is REQUIRED on every /api call. Leave UNSET and the server prints an
+# auto-generated one at boot — paste it into the phone app. Set a fixed value
+# here for a stable token across restarts.
+# COS_API_TOKEN=pick-any-long-random-string
+
+# ── THE LLM (chat) ──────────────────────────────────────────────────────
+# Chat runs through your LOCAL agent CLI — NOT an API key:
+#   Opus / Sonnet / Haiku  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
+#   Codex High             ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
+# Install at least one. Pick the default model the glasses use:
+# COS_G2_DEFAULT_MODEL=sonnet     # opus | sonnet | haiku | codex-high
+#
+# Codex options (only used for the codex-high model):
+#   COS_CODEX_MODEL pins a specific codex model id; blank = use your codex CLI default.
+#   COS_CODEX_REASONING_EFFORT is low | medium | high (default high).
+# COS_CODEX_MODEL=
+# COS_CODEX_REASONING_EFFORT=high
+
+# ── VOICE (optional) ────────────────────────────────────────────────────
+# Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the
+# model auto-downloads on first run). If whisper.cpp is absent, voice falls
+# back to the OpenAI API (~$0.006/min), which needs this key.
+# OPENAI_API_KEY=sk-...
+
+# ── FULL COS PIPELINE (optional — leave unset for standalone) ────────────
+# Power users running the COS Starter Kit can point the glasses at their
+# pipeline to inherit live tasks/calendar/people context. Omit for standalone.
+# COS_SCRIPTS_DIR=/path/to/your/cos/operations/scripts

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 6.1.0
+
+- **Codex backend.** Chat now routes to your local **Codex CLI** (`codex-high`) in
+  addition to Claude Code — pick either per query, or set `COS_G2_DEFAULT_MODEL`.
+- The Codex model is **not** hardcoded — it uses your codex CLI's own default model
+  unless you pin one with `COS_CODEX_MODEL` (+ optional `COS_CODEX_REASONING_EFFORT`).
+- Codex run/session state persists under `~/.cos-glasses/data`.
+
+## 6.0.0
+
+The server now ships **inside** this package — `npx @gotcos/glasses-server` runs
+it directly, with no second repository to clone.
+
+- **Bundled server.** Previous versions cloned a separate app repo at runtime;
+  the standalone server is now part of the package tarball.
+- **Standalone-first.** Glasses + your local Claude Code CLI. No API key is
+  pasted into the phone for chat.
+- **Local voice.** Transcription runs on whisper.cpp (free); OpenAI API is an
+  optional fallback.
+- **Phone reachability.** Defaults `BIND_HOST=0.0.0.0` so the glasses' phone app
+  can reach the server over your mesh/LAN. The IP allowlist blocks public traffic.
+- **Persistent config** at `~/.cos-glasses/.env`.
+- Requires Node.js 20.11+.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 COS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# COS Glasses Server
+
+Self-hosted AI heads-up display for **Even G2 smart glasses**. Runs on your Mac,
+talks to your local **Claude Code** CLI, and pushes answers, voice
+transcription, and notes to the lens. Your data never leaves your machine, and no
+API key is pasted into the phone for chat.
+
+## Quick start
+
+```bash
+npx @gotcos/glasses-server
+```
+
+The launcher checks Node, finds your CLI, downloads the local voice model, writes
+`~/.cos-glasses/.env`, and starts the server on `0.0.0.0:3141`. On boot it prints
+an **API token** — paste that into the COS Glasses app.
+
+## Requirements
+
+- **Node.js 20.11+** — https://nodejs.org
+- **Claude Code CLI** (Opus/Sonnet/Haiku) — https://claude.ai/download, then `claude login`
+  _or_ **Codex CLI** (Codex High) — https://developers.openai.com/codex/, then `codex login`
+- **Even G2 glasses** + the **COS Glasses** app from the Even Hub
+- _Optional:_ `brew install whisper-cpp` for free local voice (otherwise OpenAI API)
+- _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
+
+> No `ANTHROPIC_API_KEY` is needed — chat runs through your installed CLI, billed
+> to your existing Claude or Codex subscription. Pick either per query, or set a
+> default with `COS_G2_DEFAULT_MODEL` (`opus`|`sonnet`|`haiku`|`codex-high`).
+> Codex runs **sandboxed read-only** by default (`COS_CODEX_SANDBOX` to adjust).
+
+## Connect your phone (the one gotcha)
+
+The glasses app runs on your iPhone and must reach this server on your Mac.
+
+1. The launcher binds `0.0.0.0` (all interfaces) for you.
+2. **Same WiFi (simplest):** find your Mac's LAN IP (System Settings > Wi-Fi > Details), and in the COS Glasses app enter `http://192.168.x.x:3141`.
+3. **From anywhere:** install **Tailscale** on the Mac + iPhone (same account), note the Mac's `100.x` address, and enter `http://100.x.x.x:3141`.
+4. Either way, paste the **API token** the server printed at boot.
+
+To restrict the server to localhost only, set `BIND_HOST=127.0.0.1` in `~/.cos-glasses/.env`.
+The built-in IP allowlist blocks public-internet traffic regardless.
+
+## What it does
+
+- Ask anything, get a streamed answer on the lens (`/api/query`, `/v1/chat/completions`)
+- Live voice capture + transcription during meetings
+- Local whisper.cpp transcription (free) with OpenAI fallback (optional)
+- Tasks / calendar / people context **if** you run the
+  [COS Starter Kit](https://www.gotcos.com) (`COS_SCRIPTS_DIR`); otherwise it is
+  glasses + AI only
+
+## Configuration
+
+Config lives at `~/.cos-glasses/.env` (created on first run). Every key is
+optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
+`COS_API_TOKEN` (auto if unset), `OPENAI_API_KEY` (cloud voice fallback),
+`COS_SCRIPTS_DIR` (full pipeline). Your name + transcription vocabulary live in
+`~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
+
+## Run from source
+
+```bash
+git clone https://github.com/ukaoma/cos-glasses-server.git
+cd cos-glasses-server
+npm install
+BIND_HOST=0.0.0.0 npm run start:server
+```
+
+## Troubleshooting
+
+- *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
+- *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
+- *Voice getting billed?* — install `whisper-cpp` for free local transcription.
+
+## License
+
+MIT. Learn more at [gotcos.com](https://www.gotcos.com).

package/bin/cli.cjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+// COS Glasses Server launcher.
+// Runs the bundled server for Even G2 smart glasses. The server ships INSIDE this
+// package — there is no clone. Config persists at ~/.cos-glasses/.
+
+const { execSync, spawn } = require('child_process')
+const { existsSync, mkdirSync, statSync, readFileSync, copyFileSync, unlinkSync, renameSync } = require('fs')
+const { join, resolve } = require('path')
+const { homedir } = require('os')
+
+// bin/cli.cjs -> package root is one level up. The server lives at <root>/server.
+const PKG_ROOT = resolve(__dirname, '..')
+const CONFIG_DIR = join(homedir(), '.cos-glasses')
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`
+const red = (s) => `\x1b[31m${s}\x1b[0m`
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log('')
+  console.log(bold('  COS Glasses Server'))
+  console.log('')
+  console.log('  Usage:')
+  console.log('    npx @gotcos/glasses-server')
+  console.log('')
+  console.log('  Requirements:')
+  console.log('    - Node.js 20.11+')
+  console.log('    - Claude Code CLI (Opus / Sonnet / Haiku) or Codex CLI (Codex High)')
+  console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
+  console.log('')
+  console.log('  No API key is needed for chat — it runs through your installed CLI.')
+  console.log('  Config persists at ~/.cos-glasses/.env')
+  console.log('')
+  console.log('  Setup guide: https://www.gotcos.com')
+  console.log('')
+  process.exit(0)
+}
+
+console.log('')
+console.log(bold('  COS Glasses Server'))
+console.log(dim('  AI heads-up display for Even G2 smart glasses'))
+console.log('')
+
+// Step 1: Node version. The server uses import.meta.dirname (Node 20.11+ / 21.2+).
+const [nodeMajor, nodeMinor] = process.versions.node.split('.').map((n) => parseInt(n, 10))
+if (nodeMajor < 20 || (nodeMajor === 20 && nodeMinor < 11)) {
+  console.log(red('  ✗ Node.js 20.11+ required') + ` (you have ${process.versions.node})`)
+  console.log('    Update: https://nodejs.org')
+  process.exit(1)
+}
+console.log(green('  ✓') + ` Node.js ${process.versions.node}`)
+
+// Step 2: agent CLI detection — at least one of Claude Code / Codex is required
+function getCliVersion(command) {
+  try {
+    return execSync(`${command} --version 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim()
+  } catch {
+    return null
+  }
+}
+function normalizeCodexVersion(raw) {
+  if (!raw) return 'available'
+  const line = raw.split('\n').map((s) => s.trim()).find((s) => /^codex(?:-cli)?\s+/i.test(s)) || raw.split('\n')[0].trim()
+  return line.replace(/^codex(?:-cli)?\s*/i, '') || line
+}
+const claudeVersion = getCliVersion('claude')
+const codexVersion = getCliVersion('codex')
+if (claudeVersion) {
+  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Sonnet / Haiku)'))
+} else {
+  console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Sonnet/Haiku unavailable'))
+  console.log('    Install: ' + bold('https://claude.ai/download'))
+}
+if (codexVersion) {
+  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(Codex High)'))
+} else {
+  console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— Codex High unavailable'))
+}
+if (!claudeVersion && !codexVersion) {
+  console.log('')
+  console.log(red('  ✗ No supported agent CLI found'))
+  console.log('    Install Claude Code: ' + bold('https://claude.ai/download'))
+  console.log('    or Codex CLI:        ' + bold('https://developers.openai.com/codex/') + ' then ' + bold('codex login'))
+  console.log('')
+  process.exit(1)
+}
+
+// Step 3: dependencies — only when run from a git clone without node_modules.
+// `npx` already installed the package's deps alongside it.
+if (!existsSync(join(PKG_ROOT, 'node_modules'))) {
+  console.log('')
+  console.log(`  ${yellow('⟳')} Installing dependencies...`)
+  try {
+    execSync('npm install', { cwd: PKG_ROOT, stdio: 'pipe', timeout: 300000 })
+    console.log(green('  ✓') + ' Dependencies installed')
+  } catch (err) {
+    console.log(red('  ✗ npm install failed'))
+    console.log(`    ${err.stderr?.toString().slice(0, 200) || err.message}`)
+    process.exit(1)
+  }
+}
+
+// Step 4: persistent config at ~/.cos-glasses/ (survives npx cache churn)
+mkdirSync(CONFIG_DIR, { recursive: true })
+const ENV_FILE = join(CONFIG_DIR, '.env')
+const ENV_EXAMPLE = join(PKG_ROOT, '.env.example')
+if (!existsSync(ENV_FILE) && existsSync(ENV_EXAMPLE)) {
+  copyFileSync(ENV_EXAMPLE, ENV_FILE)
+  console.log(green('  ✓') + ` Created config at ${dim(ENV_FILE)}`)
+}
+if (existsSync(ENV_FILE)) {
+  try {
+    for (const line of readFileSync(ENV_FILE, 'utf-8').split('\n')) {
+      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)=(.*)$/)
+      if (m && !process.env[m[1]]) process.env[m[1]] = m[2].trim()
+    }
+  } catch { /* config is optional */ }
+}
+// Persistent profile (identity + transcription vocabulary)
+const PROFILE_FILE = join(CONFIG_DIR, '.cos-profile.json')
+const PROFILE_EXAMPLE = join(PKG_ROOT, '.cos-profile.example.json')
+if (!existsSync(PROFILE_FILE) && existsSync(PROFILE_EXAMPLE)) {
+  copyFileSync(PROFILE_EXAMPLE, PROFILE_FILE)
+}
+if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
+
+// Step 5: local Whisper detection + model download (free voice; OpenAI fallback otherwise)
+const WHISPER_KNOWN_PATHS = ['/opt/homebrew/bin/whisper-cli', '/usr/local/bin/whisper-cli']
+const WHISPER_MODEL_DIR = join(homedir(), '.local/share/whisper-models')
+const WHISPER_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-large-v3-turbo.bin')
+const WHISPER_MODEL_PARTIAL = WHISPER_MODEL_PATH + '.partial'
+const WHISPER_MODEL_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin'
+const WHISPER_MODEL_MIN_BYTES = 800_000_000
+function findWhisperCli() {
+  for (const p of WHISPER_KNOWN_PATHS) { if (existsSync(p)) return p }
+  try {
+    const found = execSync('command -v whisper-cli 2>/dev/null', { shell: '/bin/sh', stdio: 'pipe', timeout: 2000 }).toString().trim()
+    return found || null
+  } catch {
+    return null
+  }
+}
+function isValidWhisperModel(p) {
+  if (!existsSync(p)) return false
+  try { return statSync(p).size >= WHISPER_MODEL_MIN_BYTES } catch { return false }
+}
+const whisperCliPath = findWhisperCli()
+const hasValidModel = isValidWhisperModel(WHISPER_MODEL_PATH)
+if (whisperCliPath && hasValidModel) {
+  console.log(green('  ✓') + ' whisper.cpp + model ready ' + dim('— voice = local (FREE)'))
+} else if (whisperCliPath && !hasValidModel) {
+  if (existsSync(WHISPER_MODEL_PATH)) { try { unlinkSync(WHISPER_MODEL_PATH) } catch {} }
+  if (existsSync(WHISPER_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {} }
+  console.log(yellow('  ⚠') + ' whisper.cpp installed but model missing')
+  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB). Ctrl-C to skip (uses OpenAI API instead).'))
+  console.log('    ' + dim('Skip permanently: SKIP_WHISPER_DOWNLOAD=1 npx @gotcos/glasses-server'))
+  if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
+    console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — voice will use OpenAI API')
+  } else {
+    try {
+      mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
+      execSync(`curl -fL --progress-bar "${WHISPER_MODEL_URL}" -o "${WHISPER_MODEL_PARTIAL}"`, { stdio: 'inherit', timeout: 900000 })
+      const stats = statSync(WHISPER_MODEL_PARTIAL)
+      if (stats.size < WHISPER_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
+      renameSync(WHISPER_MODEL_PARTIAL, WHISPER_MODEL_PATH)
+      console.log(green('  ✓') + ' Model downloaded ' + dim('— voice = local (FREE)'))
+    } catch (err) {
+      try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {}
+      console.log(red('  ✗') + ' Model download failed ' + dim('— voice will use OpenAI API'))
+      console.log('    ' + dim('Error: ' + (err.message || err).toString().slice(0, 120)))
+    }
+  }
+} else {
+  console.log(yellow('  ⚠') + ' whisper.cpp not installed ' + dim('— voice will use OpenAI API ($0.006/min)'))
+  console.log('    Free local voice: ' + bold('brew install whisper-cpp') + dim('  (no Homebrew? https://brew.sh)'))
+}
+
+// Step 6: phone reachability — the glasses' phone app must reach this server.
+if (!process.env.BIND_HOST) {
+  process.env.BIND_HOST = '0.0.0.0'
+  console.log(yellow('  ⚠') + ' BIND_HOST not set — defaulting to 0.0.0.0 so your phone can reach the server')
+}
+
+// Step 7: start the bundled server
+console.log('')
+console.log(dim('  Starting server...'))
+console.log('')
+const serverProc = spawn(
+  process.execPath,
+  ['--import', 'tsx/esm', 'server/index.ts'],
+  { cwd: PKG_ROOT, stdio: 'inherit', env: { ...process.env } }
+)
+serverProc.on('error', (err) => {
+  console.error(red(`  Server failed to start: ${err.message}`))
+  if (err.message.includes('tsx')) console.error('  Try: cd ' + PKG_ROOT + ' && npm install')
+  process.exit(1)
+})
+serverProc.on('exit', (code) => process.exit(code ?? 0))
+process.on('SIGINT', () => serverProc.kill('SIGINT'))
+process.on('SIGTERM', () => serverProc.kill('SIGTERM'))

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@gotcos/glasses-server",
+  "version": "6.1.0",
+  "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
+  "type": "module",
+  "bin": {
+    "glasses-server": "bin/cli.cjs"
+  },
+  "scripts": {
+    "start": "node bin/cli.cjs",
+    "start:server": "node --import tsx/esm server/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["even-g2", "smart-glasses", "claude-code", "codex", "ai", "cos", "heads-up-display", "whisper"],
+  "files": [
+    "bin/cli.cjs",
+    "server/**/*.ts",
+    "server/**/*.js",
+    "shared/**/*.ts",
+    ".env.example",
+    ".cos-profile.example.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "author": "COS Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ukaoma/cos-glasses-server.git"
+  },
+  "homepage": "https://www.gotcos.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "dependencies": {
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "tsx": "^4.21.0"
+  },
+  "optionalDependencies": {
+    "sherpa-onnx-node": "^1.12.29"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.3"
+  }
+}

package/server/env.ts

@@ -0,0 +1,26 @@
+// .env loader — MUST be imported first in index.ts so process.env is populated
+// before python-bridge.ts reads COS_SCRIPTS_DIR.
+//
+// Loads the persistent launcher config (~/.cos-glasses/.env) first, then a
+// repo-local .env for from-source/dev runs. Existing process.env values always
+// win (the launcher pre-injects them), so this is a safe last-resort loader.
+
+import { readFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { homedir } from 'node:os'
+
+function loadEnvFile(path: string): void {
+  try {
+    const content = readFileSync(path, 'utf-8')
+    for (const line of content.split('\n')) {
+      // Allow digits in keys (e.g. COS_G2_DEFAULT_MODEL) and empty values.
+      const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)=(.*)$/)
+      if (match && !process.env[match[1]]) {
+        process.env[match[1]] = match[2].trim()
+      }
+    }
+  } catch { /* .env is optional — env vars can be set externally */ }
+}
+
+loadEnvFile(join(homedir(), '.cos-glasses', '.env'))
+loadEnvFile(resolve(import.meta.dirname, '../.env'))