kira-glasses-bridge 1.0.0

package/README.md

@@ -0,0 +1,34 @@
+# kira-glasses-bridge
+
+Connects your Mac to **Kira**, the assistant for Even Realities G2 glasses. With the bridge running, Kira can list and talk to your Claude Code sessions, browse and open files and folders, create notes and READMEs, launch apps ("open this in VS Code"), and move things to the Trash, all confined to your home folder.
+
+## Setup
+
+1. In the Kira portal, open **Connections → Claude Code → Set up** and copy the command it shows.
+2. Paste it into Terminal:
+
+   ```bash
+   npx kira-glasses-bridge --token <your token>
+   ```
+
+That saves the token to `~/.kira/bridge.json` and installs a background service that starts at login and reconnects on its own. The portal card flips to **Online**.
+
+Needs Node.js 20 or newer, which Claude Code already requires.
+
+## Commands
+
+```
+kira-bridge status       is it installed and running?
+kira-bridge logs         follow the log (~/.kira/bridge.log)
+kira-bridge run          run in the foreground instead of as a service
+kira-bridge uninstall    remove the background service
+```
+
+Add `--no-service` to the setup command to skip the service and just run in the foreground.
+
+## What it can and cannot do
+
+- Connects **outbound only**, over a WebSocket to the Kira API. Nothing listens on your Mac.
+- File access is confined to your home folder. Deleting moves to the Trash.
+- Runs Claude Code with `claude -p --resume <session>`; edits are auto-accepted, no shell commands.
+- Remove the bridge from the portal at any time; the token stops working immediately.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "kira-glasses-bridge",
+  "version": "1.0.0",
+  "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
+  "type": "module",
+  "bin": { "kira-bridge": "./src/cli.mjs" },
+  "files": ["src", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "start": "node src/cli.mjs run"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": ["even-realities", "g2", "smart-glasses", "claude-code", "kira"],
+  "license": "MIT",
+  "homepage": "https://hackchild.xyz/kira"
+}

package/src/apps.mjs

@@ -0,0 +1,124 @@
+// Launch applications on this Mac. Uses macOS `open`, so nothing runs in a
+// shell and no arguments are interpreted: `open -a <App> [path]`.
+//
+// Apps are matched by name against what is installed under /Applications,
+// ~/Applications and /System/Applications. Everyday aliases ("vscode",
+// "code", "chrome", "terminal") map onto the real bundle names. Paths handed
+// to an app are confined to the home folder like the file tools.
+import { execFile } from 'node:child_process'
+import { readdir } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { resolveUserPath } from './files.mjs'
+
+const run = promisify(execFile)
+const APP_DIRS = ['/Applications', join(homedir(), 'Applications'), '/System/Applications', '/System/Applications/Utilities']
+
+const ALIASES = {
+  vscode: 'Visual Studio Code',
+  'vs code': 'Visual Studio Code',
+  code: 'Visual Studio Code',
+  'visual studio': 'Visual Studio Code',
+  chrome: 'Google Chrome',
+  browser: 'Google Chrome',
+  terminal: 'Terminal',
+  iterm: 'iTerm',
+  finder: 'Finder',
+  notes: 'Notes',
+  music: 'Music',
+  mail: 'Mail',
+  messages: 'Messages',
+  calendar: 'Calendar',
+  photos: 'Photos',
+  preview: 'Preview',
+  textedit: 'TextEdit',
+  xcode: 'Xcode',
+  'android studio': 'Android Studio',
+  postman: 'Postman',
+  spotify: 'Spotify',
+  slack: 'Slack',
+  discord: 'Discord',
+  telegram: 'Telegram',
+  whatsapp: 'WhatsApp',
+  docker: 'Docker',
+  claude: 'Claude',
+  chatgpt: 'ChatGPT Classic',
+  '1password': '1Password',
+  github: 'GitHub Desktop',
+  'github desktop': 'GitHub Desktop',
+  pycharm: 'PyCharm',
+  unity: 'Unity Hub',
+  safari: 'Safari',
+}
+
+let cache = null
+export async function installedApps() {
+  if (cache && Date.now() - cache.at < 60_000) return cache.apps
+  const names = new Set()
+  for (const dir of APP_DIRS) {
+    try {
+      for (const f of await readdir(dir)) if (f.endsWith('.app')) names.add(f.slice(0, -4))
+    } catch {
+      /* dir may not exist */
+    }
+  }
+  const apps = [...names].sort((a, b) => a.localeCompare(b))
+  cache = { at: Date.now(), apps }
+  return apps
+}
+
+function norm(s) {
+  return String(s ?? '').toLowerCase().replace(/[^a-z0-9+ ]/g, '').replace(/\s+/g, ' ').trim()
+}
+
+/** Resolve a spoken app name to an installed bundle name, or null. */
+export async function resolveApp(name) {
+  const apps = await installedApps()
+  const q = norm(name)
+  if (!q) return null
+  const alias = ALIASES[q]
+  if (alias && apps.includes(alias)) return alias
+  const exact = apps.find(a => norm(a) === q)
+  if (exact) return exact
+  const starts = apps.filter(a => norm(a).startsWith(q))
+  if (starts.length === 1) return starts[0]
+  const contains = apps.filter(a => norm(a).includes(q))
+  if (contains.length === 1) return contains[0]
+  if (alias) return alias // not installed; caller reports it
+  return null
+}
+
+/**
+ * Open an app, optionally with a file or folder (or a URL for browsers).
+ * With no app, open the path in its default application.
+ */
+export async function openApp({ app, path, url }) {
+  const args = []
+  let appName = null
+  if (app) {
+    appName = await resolveApp(app)
+    if (!appName) {
+      const apps = await installedApps()
+      const near = apps.filter(a => norm(a).includes(norm(app).split(' ')[0] ?? '')).slice(0, 5)
+      return { error: `I could not find an app called "${app}" on this Mac.${near.length ? ` Did you mean: ${near.join(', ')}?` : ''}` }
+    }
+    args.push('-a', appName)
+  }
+  let target = null
+  if (url) {
+    if (!/^https?:\/\//i.test(String(url))) return { error: 'only http(s) URLs can be opened' }
+    target = String(url)
+  } else if (path) {
+    target = resolveUserPath(String(path)) // throws if outside home
+  }
+  if (!appName && !target) return { error: 'say which app to open, or which file or folder' }
+  if (target) args.push(target)
+  try {
+    await run('/usr/bin/open', args, { timeout: 15_000 })
+  } catch (err) {
+    const msg = String(err.stderr || err.message || '').trim()
+    return { error: `open failed: ${msg || 'unknown error'}` }
+  }
+  return { opened: true, app: appName, target: target ? (url ? target : target.replace(homedir(), '~')) : null }
+}

package/src/claude-run.mjs

@@ -0,0 +1,55 @@
+// Runs Claude Code headless: `claude -p --resume <id> --output-format json`.
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Find the claude binary. The bridge may be started from a shell whose PATH
+ * lacks ~/.local/bin (launchd, a minimal terminal, a different shell), so
+ * check the usual install locations before giving up.
+ */
+export function findClaude() {
+  if (process.env.KIRA_CLAUDE_BIN && existsSync(process.env.KIRA_CLAUDE_BIN)) return process.env.KIRA_CLAUDE_BIN
+  const candidates = [
+    join(homedir(), '.local', 'bin', 'claude'),
+    join(homedir(), '.claude', 'local', 'claude'),
+    '/opt/homebrew/bin/claude',
+    '/usr/local/bin/claude',
+  ]
+  for (const c of candidates) if (existsSync(c)) return c
+  return 'claude' // rely on PATH
+}
+
+const MAX_MS = 15 * 60 * 1000
+
+export function runClaude({ prompt, sessionId, cwd }) {
+  return new Promise(resolve => {
+    const args = ['-p', '--output-format', 'json', '--permission-mode', 'acceptEdits']
+    if (sessionId) args.push('--resume', sessionId)
+    args.push(prompt)
+    const child = spawn(findClaude(), args, { cwd: cwd || process.env.HOME, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM')
+      resolve({ error: `Claude did not finish within ${MAX_MS / 60000} minutes` })
+    }, MAX_MS)
+    child.stdout.on('data', d => (out += d))
+    child.stderr.on('data', d => (err += d))
+    child.on('error', e => {
+      clearTimeout(timer)
+      const hint = e.code === 'ENOENT' ? 'Claude Code is not installed or not on the bridge\'s PATH. Install it, or set KIRA_CLAUDE_BIN=/path/to/claude when starting the bridge.' : e.message
+      resolve({ error: `could not start claude: ${hint}` })
+    })
+    child.on('close', code => {
+      clearTimeout(timer)
+      try {
+        const j = JSON.parse(out)
+        resolve({ session_id: j.session_id, result: j.result, is_error: !!j.is_error, cost_usd: j.total_cost_usd, duration_ms: j.duration_ms, num_turns: j.num_turns })
+      } catch {
+        resolve({ error: `claude exited with code ${code}: ${(err || out).slice(0, 500)}` })
+      }
+    })
+  })
+}

package/src/claude-sessions.mjs

@@ -0,0 +1,149 @@
+// Reads Claude Code's own session transcripts under ~/.claude/projects.
+// Each session is a .jsonl file; the entries we care about are user and
+// assistant messages, the ai-title entries, and cwd.
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+
+const PROJECTS = join(homedir(), '.claude', 'projects')
+const ACTIVE_WINDOW_MS = 3 * 60 * 1000
+
+async function sessionFiles() {
+  const out = []
+  let dirs = []
+  try {
+    dirs = await readdir(PROJECTS)
+  } catch {
+    return out
+  }
+  for (const d of dirs) {
+    let files = []
+    try {
+      files = await readdir(join(PROJECTS, d))
+    } catch {
+      continue
+    }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue
+      const path = join(PROJECTS, d, f)
+      try {
+        const st = await stat(path)
+        if (st.size > 0) out.push({ path, mtime: st.mtimeMs, size: st.size })
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return out.sort((a, b) => b.mtime - a.mtime)
+}
+
+function textOf(message) {
+  const c = message?.content
+  if (typeof c === 'string') return c
+  if (Array.isArray(c)) return c.filter(b => b?.type === 'text').map(b => b.text).join('\n')
+  return ''
+}
+
+/** Parse a transcript; only the last `tailBytes` are read for speed. */
+async function summarize(file, tailBytes = 400_000) {
+  const st = await stat(file.path)
+  const buf = await readFile(file.path)
+  const slice = buf.length > tailBytes ? buf.subarray(buf.length - tailBytes) : buf
+  const lines = slice.toString('utf8').split('\n')
+  if (buf.length > tailBytes) lines.shift() // drop a partial first line
+  let sessionId = file.path.split('/').pop().replace(/\.jsonl$/, '')
+  let cwd = null
+  let title = null
+  const turns = []
+  for (const line of lines) {
+    if (!line) continue
+    let d
+    try {
+      d = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (d.sessionId) sessionId = d.sessionId
+    if (d.cwd) cwd = d.cwd
+    if (d.type === 'ai-title' && typeof d.aiTitle === 'string') title = d.aiTitle
+    if ((d.type === 'user' || d.type === 'assistant') && d.message) {
+      const text = textOf(d.message).trim()
+      if (!text || text.startsWith('<') ) continue // skip tool results / system blocks
+      turns.push({ role: d.type === 'user' ? 'user' : 'claude', text, at: d.timestamp ?? null })
+    }
+  }
+  return { sessionId, cwd, title, turns, lastActiveAt: new Date(st.mtimeMs).toISOString(), active: Date.now() - st.mtimeMs < ACTIVE_WINDOW_MS }
+}
+
+export async function listSessions(max = 10) {
+  const files = (await sessionFiles()).slice(0, Math.min(Math.max(Number(max) || 10, 1), 20))
+  const sessions = []
+  for (const f of files) {
+    try {
+      const s = await summarize(f, 120_000)
+      const lastUser = [...s.turns].reverse().find(t => t.role === 'user')
+      const lastClaude = [...s.turns].reverse().find(t => t.role === 'claude')
+      sessions.push({
+        session_id: s.sessionId,
+        title: s.title ?? (lastUser ? lastUser.text.slice(0, 60) : '(untitled)'),
+        project: s.cwd ? s.cwd.split('/').slice(-2).join('/') : null,
+        cwd: s.cwd,
+        active: s.active,
+        last_active_at: s.lastActiveAt,
+        last_user_message: lastUser ? lastUser.text.slice(0, 200) : null,
+        last_claude_message: lastClaude ? lastClaude.text.slice(0, 200) : null,
+      })
+    } catch {
+      /* unreadable transcript */
+    }
+  }
+  return { count: sessions.length, sessions }
+}
+
+export async function readSession(sessionId, turns = 6) {
+  const files = await sessionFiles()
+  const file = files.find(f => f.path.endsWith(`/${sessionId}.jsonl`))
+  if (!file) return { error: `No session ${sessionId} on this machine` }
+  const s = await summarize(file)
+  const n = Math.min(Math.max(Number(turns) || 6, 1), 30)
+  return { session_id: s.sessionId, title: s.title, cwd: s.cwd, active: s.active, last_active_at: s.lastActiveAt, turns: s.turns.slice(-n).map(t => ({ ...t, text: t.text.slice(0, 2000) })) }
+}
+
+/**
+ * Project folders Claude Code has been used in, newest first. One cheap read
+ * per project: the head of its newest transcript carries the cwd.
+ */
+export async function listProjects(max = 20) {
+  const n = Math.min(Math.max(Number(max) || 20, 1), 50)
+  let dirs = []
+  try {
+    dirs = await readdir(PROJECTS)
+  } catch {
+    return { count: 0, projects: [] }
+  }
+  const projects = []
+  for (const d of dirs) {
+    const dir = join(PROJECTS, d)
+    let files = []
+    try {
+      files = (await readdir(dir)).filter(f => f.endsWith('.jsonl'))
+    } catch {
+      continue
+    }
+    let newest = null
+    for (const f of files) {
+      const st = await stat(join(dir, f)).catch(() => null)
+      if (st && st.size > 0 && (!newest || st.mtimeMs > newest.mtime)) newest = { path: join(dir, f), mtime: st.mtimeMs }
+    }
+    if (!newest) continue
+    const head = (await readFile(newest.path)).subarray(0, 65536).toString('utf8')
+    const m = /"cwd":"((?:[^"\\]|\\.)*)"/.exec(head)
+    if (!m) continue
+    const cwd = JSON.parse(`"${m[1]}"`)
+    const exists = await stat(cwd).then(st => st.isDirectory()).catch(() => false)
+    if (!exists) continue
+    projects.push({ cwd, name: basename(cwd), parent: basename(join(cwd, '..')), sessions: files.length, last_active_at: new Date(newest.mtime).toISOString(), _mtime: newest.mtime })
+  }
+  projects.sort((a, b) => b._mtime - a._mtime)
+  return { count: Math.min(projects.length, n), projects: projects.slice(0, n).map(({ _mtime, ...p }) => p) }
+}

package/src/cli.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// kira-bridge: connect this Mac to Kira on your glasses.
+//
+//   npx kira-glasses-bridge --token <token>     save the token and install the background service
+//   kira-bridge run                              run in the foreground (what the service runs)
+//   kira-bridge install | uninstall | status | logs
+import { createRequire } from 'node:module'
+import { spawnSync } from 'node:child_process'
+import { resolve as resolveConfig, writeConfig, readConfig, configExists, LOG_PATH, DEFAULT_URL } from './config.mjs'
+import { install, uninstall, status } from './service.mjs'
+import { startBridge } from './index.mjs'
+
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json')
+
+const args = process.argv.slice(2)
+const flags = {}
+const positional = []
+for (let i = 0; i < args.length; i++) {
+  const a = args[i]
+  if (a === '--token' || a === '--url' || a === '--claude-bin') {
+    flags[a === '--claude-bin' ? 'claudeBin' : a.slice(2)] = args[++i]
+  } else if (a === '--no-service') flags.noService = true
+  else if (a === '-v' || a === '--version') {
+    console.log(version)
+    process.exit(0)
+  } else if (a === '-h' || a === '--help') positional.push('help')
+  else positional.push(a)
+}
+const cmd = positional[0] ?? (flags.token ? 'setup' : configExists() ? 'run' : 'help')
+
+const help = `kira-bridge ${version}
+
+Connect this Mac to Kira (Even G2 glasses): Claude Code sessions, files,
+folders and apps, by voice.
+
+  npx kira-glasses-bridge --token <token>   first-time setup: saves the token
+                                            and installs a background service
+                                            (add --no-service to skip that)
+  kira-bridge run                           run in the foreground
+  kira-bridge status                        is the service installed and running?
+  kira-bridge logs                          follow the service log
+  kira-bridge install | uninstall           manage the background service
+
+Get a token from the Kira portal: Connections -> Claude Code -> Set up.
+Settings are kept in ~/.kira/bridge.json.`
+
+async function main() {
+  switch (cmd) {
+    case 'help':
+      console.log(help)
+      return
+    case 'setup': {
+      const cfg = { ...readConfig(), token: flags.token, url: flags.url || readConfig().url || DEFAULT_URL }
+      if (flags.claudeBin) cfg.claudeBin = flags.claudeBin
+      writeConfig(cfg)
+      console.log('Saved your token to ~/.kira/bridge.json')
+      if (flags.noService || process.platform !== 'darwin') {
+        console.log('Starting in the foreground. Press Ctrl-C to stop.\n')
+        return startBridge(resolveConfig(flags))
+      }
+      const r = install()
+      console.log(`Installed the background service (${r.plist}).`)
+      console.log('It starts at login and reconnects on its own. Check it with: kira-bridge status')
+      await waitForOnline(8000)
+      return
+    }
+    case 'run':
+      return startBridge(resolveConfig(flags))
+    case 'install': {
+      if (!resolveConfig(flags).token) throw new Error('no token saved yet; run: npx kira-glasses-bridge --token <token>')
+      const r = install()
+      console.log(`Installed and started (${r.plist}). Log: ${r.log}`)
+      return
+    }
+    case 'uninstall':
+      console.log(uninstall() ? 'Removed the background service.' : 'No background service was installed.')
+      return
+    case 'status': {
+      const s = status()
+      const c = resolveConfig(flags)
+      console.log(`token:   ${c.token ? 'saved' : 'missing'}`)
+      console.log(`server:  ${c.url}`)
+      if (!s.installed) console.log('service: not installed (run `kira-bridge install`, or `kira-bridge run` for the foreground)')
+      else console.log(`service: ${s.running ? 'running' : 'installed but not running'}\nlog:     ${s.log}${s.lastLog ? '\n\n' + s.lastLog : ''}`)
+      return
+    }
+    case 'logs':
+      spawnSync('tail', ['-n', '50', '-f', LOG_PATH], { stdio: 'inherit' })
+      return
+    default:
+      throw new Error(`unknown command "${cmd}"\n\n${help}`)
+  }
+}
+
+async function waitForOnline(ms) {
+  const { readFileSync } = await import('node:fs')
+  const start = Date.now()
+  while (Date.now() - start < ms) {
+    await new Promise(r => setTimeout(r, 500))
+    try {
+      const tail = readFileSync(LOG_PATH, 'utf8').slice(-2000)
+      if (/registered as bridge/.test(tail)) {
+        console.log('\nConnected. The Claude Code card in the portal should now show Online.')
+        return
+      }
+      if (/token rejected/.test(tail)) throw new Error('the server rejected this token; make a new one in the portal')
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+    }
+  }
+  console.log('\nThe service is starting; check `kira-bridge status` in a moment.')
+}
+
+main().catch(err => {
+  console.error(`kira-bridge: ${err.message}`)
+  process.exit(1)
+})

package/src/config.mjs

@@ -0,0 +1,38 @@
+// Bridge settings live in ~/.kira/bridge.json so the daemon can start without
+// environment variables (launchd gives it none). The token is written 0600.
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const KIRA_DIR = join(homedir(), '.kira')
+export const CONFIG_PATH = join(KIRA_DIR, 'bridge.json')
+export const LOG_PATH = join(KIRA_DIR, 'bridge.log')
+export const DEFAULT_URL = 'wss://kira.hackchild.xyz/api/bridge/ws'
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+export function writeConfig(cfg) {
+  mkdirSync(KIRA_DIR, { recursive: true, mode: 0o700 })
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(CONFIG_PATH, 0o600)
+}
+
+/** Effective settings: flags > env > saved config > defaults. */
+export function resolve(flags = {}) {
+  const saved = readConfig()
+  return {
+    url: flags.url || process.env.KIRA_BRIDGE_URL || saved.url || DEFAULT_URL,
+    token: flags.token || process.env.KIRA_BRIDGE_TOKEN || saved.token || '',
+    claudeBin: flags.claudeBin || process.env.KIRA_CLAUDE_BIN || saved.claudeBin || '',
+  }
+}
+
+export function configExists() {
+  return existsSync(CONFIG_PATH)
+}

package/src/files.mjs

@@ -0,0 +1,143 @@
+// Read-only file browser for this Mac. Paths are confined to the home
+// folder; hidden entries and node_modules are skipped so lists stay short.
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, extname, join, relative, resolve } from 'node:path'
+
+const HOME = homedir()
+const MAX_ENTRIES = 200
+const TEXT_LIMIT = 12000
+const READ_LIMIT = 2 * 1024 * 1024
+const SKIP = new Set(['node_modules', '.git', 'Library', '.Trash'])
+
+/** Common starting points, shown as the top level on the glasses. */
+export const ROOTS = ['Desktop', 'Documents', 'Downloads', 'Developer']
+
+/** Expand ~ and confine to the home folder. Throws on escape. */
+export function resolveUserPath(p) {
+  const raw = String(p ?? '').trim()
+  let full = raw === '' || raw === '~' ? HOME : raw.startsWith('~/') ? join(HOME, raw.slice(2)) : raw.startsWith('/') ? raw : join(HOME, raw)
+  full = resolve(full)
+  const rel = relative(HOME, full)
+  if (rel.startsWith('..') || resolve(full) !== full) throw new Error('only files under your home folder can be browsed')
+  return full
+}
+
+function display(full) {
+  const rel = relative(HOME, full)
+  return rel === '' ? '~' : `~/${rel}`
+}
+
+export async function listFiles({ path, max }) {
+  const full = resolveUserPath(path)
+  const st = await stat(full).catch(() => null)
+  if (!st) return { error: `${display(full)} does not exist` }
+  if (!st.isDirectory()) return { error: `${display(full)} is a file; use read_file` }
+  const names = await readdir(full)
+  const limit = Math.min(Math.max(Number(max) || MAX_ENTRIES, 1), MAX_ENTRIES)
+  const entries = []
+  for (const name of names) {
+    if (name.startsWith('.') || SKIP.has(name)) continue
+    const child = join(full, name)
+    const cs = await stat(child).catch(() => null)
+    if (!cs) continue
+    entries.push({ name, path: display(child), type: cs.isDirectory() ? 'dir' : 'file', size: cs.isDirectory() ? undefined : cs.size, modified: cs.mtime.toISOString() })
+  }
+  entries.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) : a.type === 'dir' ? -1 : 1))
+  return { path: display(full), count: entries.length, truncated: entries.length > limit, entries: entries.slice(0, limit) }
+}
+
+const TEXT_EXT = new Set(['.txt', '.md', '.markdown', '.json', '.yml', '.yaml', '.toml', '.csv', '.tsv', '.log', '.env', '.xml', '.html', '.css', '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.rb', '.go', '.rs', '.swift', '.kt', '.java', '.c', '.h', '.cpp', '.m', '.sh', '.zsh', '.sql', '.ini', '.cfg', '.conf', '.plist', '.gitignore'])
+const OFFICE_EXT = { '.docx': 'a Word document', '.doc': 'a Word document', '.pdf': 'a PDF', '.xlsx': 'a spreadsheet', '.pptx': 'a presentation', '.pages': 'a Pages document', '.numbers': 'a Numbers spreadsheet', '.key': 'a Keynote deck' }
+
+export async function readUserFile({ path }) {
+  const full = resolveUserPath(path)
+  const st = await stat(full).catch(() => null)
+  if (!st) return { error: `${display(full)} does not exist` }
+  if (st.isDirectory()) return { error: `${display(full)} is a folder; use list_files` }
+  const ext = extname(full).toLowerCase()
+  if (OFFICE_EXT[ext]) return { path: display(full), size: st.size, error: `${basename(full)} is ${OFFICE_EXT[ext]}; only plain text files can be read for now` }
+  if (st.size > READ_LIMIT) return { path: display(full), size: st.size, error: `${basename(full)} is ${Math.round(st.size / 1024 / 1024)} MB, too large to read here` }
+  const buf = await readFile(full)
+  const sample = buf.subarray(0, 4000)
+  const binary = !TEXT_EXT.has(ext) && (sample.includes(0) || sample.filter(b => b < 9 || (b > 13 && b < 32)).length > sample.length / 50)
+  if (binary) return { path: display(full), size: st.size, binary: true, error: `${basename(full)} looks like a binary file` }
+  const text = buf.toString('utf8')
+  const lines = text.split('\n').length
+  const truncated = text.length > TEXT_LIMIT
+  return { path: display(full), name: basename(full), size: st.size, lines, modified: st.mtime.toISOString(), truncated, text: truncated ? `${text.slice(0, TEXT_LIMIT)}\n… (${lines} lines, showing the first part)` : text }
+}
+
+/**
+ * Create a folder under the home directory (parents included). The one
+ * write the file browser allows, so Kira can start projects. Refuses to
+ * touch anything outside ~ and never overwrites an existing file.
+ */
+export async function createFolder({ path }) {
+  const full = resolveUserPath(String(path ?? ''))
+  if (full === HOME) throw new Error('give the new folder a name')
+  const { mkdir, stat } = await import('node:fs/promises')
+  try {
+    const st = await stat(full)
+    if (st.isDirectory()) return { path: display(full), created: false, note: 'already exists' }
+    throw new Error(`${display(full)} exists and is a file`)
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+  await mkdir(full, { recursive: true })
+  return { path: display(full), created: true }
+}
+
+/**
+ * Write a plain-text file under the home directory. Creates parent folders.
+ * Refuses to overwrite unless `overwrite` is true, so a slip of the tongue
+ * cannot clobber something.
+ */
+export async function writeUserFile({ path, content, overwrite }) {
+  const full = resolveUserPath(String(path ?? ''))
+  if (full === HOME) throw new Error('give the file a name')
+  const { mkdir, stat, writeFile } = await import('node:fs/promises')
+  const { dirname } = await import('node:path')
+  try {
+    const st = await stat(full)
+    if (st.isDirectory()) throw new Error(`${display(full)} is a folder`)
+    if (!overwrite) return { path: display(full), written: false, error: `${display(full)} already exists. Say "overwrite it" to replace it.` }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+  await mkdir(dirname(full), { recursive: true })
+  const text = String(content ?? '')
+  await writeFile(full, text, 'utf8')
+  return { path: display(full), written: true, bytes: Buffer.byteLength(text, 'utf8') }
+}
+
+/**
+ * "Delete" a file or folder by moving it to the Trash (via Finder), so a
+ * misheard name is recoverable. Confined to the home folder; refuses the
+ * home folder itself and its top-level folders (Desktop, Developer, ...).
+ */
+export async function trashPath({ path }) {
+  const full = resolveUserPath(String(path ?? ''))
+  const rel = relative(HOME, full)
+  if (!rel || !rel.includes('/')) throw new Error(`refusing to delete ${display(full)}: only things inside a top-level folder can be deleted`)
+  const { stat } = await import('node:fs/promises')
+  let st
+  try {
+    st = await stat(full)
+  } catch (err) {
+    if (err.code === 'ENOENT') return { error: `${display(full)} does not exist` }
+    throw err
+  }
+  const { execFile } = await import('node:child_process')
+  const { promisify } = await import('node:util')
+  const run = promisify(execFile)
+  // Finder handles the move and the "Put Back" bookkeeping. The path is passed
+  // as an argument, never interpolated into the script.
+  const script = 'on run argv\n tell application "Finder" to delete (POSIX file (item 1 of argv) as alias)\nend run'
+  try {
+    await run('/usr/bin/osascript', ['-e', script, full], { timeout: 20_000 })
+  } catch (err) {
+    return { error: `could not move to Trash: ${String(err.stderr || err.message).trim()}` }
+  }
+  return { trashed: true, path: display(full), kind: st.isDirectory() ? 'folder' : 'file', note: 'Moved to the Trash; it can be put back from there.' }
+}

package/src/index.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Kira bridge. Connects outbound to the Kira API and runs tools on this
+// machine on the user's behalf. Env: KIRA_BRIDGE_URL, KIRA_BRIDGE_TOKEN.
+import WebSocket from 'ws'
+import { listProjects, listSessions, readSession } from './claude-sessions.mjs'
+import { runClaude, findClaude } from './claude-run.mjs'
+import { openApp, installedApps } from './apps.mjs'
+import { listFiles, readUserFile, createFolder, writeUserFile, trashPath } from './files.mjs'
+
+import { createRequire } from 'node:module'
+const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
+
+let URL_ = ''
+let TOKEN = ''
+
+/** Start the bridge with resolved settings. Runs until the process exits. */
+export function startBridge(config) {
+  URL_ = config.url
+  TOKEN = config.token
+  if (config.claudeBin) process.env.KIRA_CLAUDE_BIN = config.claudeBin
+  if (!URL_ || !TOKEN) {
+    console.error('No token. Run: npx kira-glasses-bridge --token <token>  (from the Kira portal → Connections → Claude Code)')
+    process.exit(1)
+  }
+  log(`kira-bridge ${BRIDGE_VERSION} · claude binary: ${findClaude()}`)
+  connect()
+}
+
+const tools = {
+  async list_files(args) {
+    return listFiles(args)
+  },
+  async read_file(args) {
+    return readUserFile(args)
+  },
+  async create_folder(args) {
+    return createFolder(args)
+  },
+  async write_file(args) {
+    return writeUserFile(args)
+  },
+  async open_app(args) {
+    return openApp(args)
+  },
+  async delete_path(args) {
+    return trashPath(args)
+  },
+  async list_apps() {
+    return { apps: await installedApps() }
+  },
+  async list_claude_projects(args) {
+    return listProjects(args.max)
+  },
+  async list_claude_sessions(args) {
+    return listSessions(args.max)
+  },
+  async read_claude_session(args) {
+    return readSession(String(args.session_id ?? ''), args.turns)
+  },
+  // Acknowledge now, report the result as a job when Claude finishes.
+  async ask_claude(args, ws) {
+    const jobId = String(args.job_id ?? '')
+    const prompt = String(args.prompt ?? '')
+    if (!prompt) return { error: 'prompt is required' }
+    log(`ask_claude job=${jobId.slice(0, 8)} session=${args.session_id ?? 'new'}: ${prompt.slice(0, 80)}`)
+    void runClaude({ prompt, sessionId: args.session_id, cwd: args.cwd }).then(result => {
+      log(`job ${jobId.slice(0, 8)} ${result.error ? 'error' : 'done'}`)
+      send(ws, { type: 'job', jobId, status: result.error ? 'error' : 'done', result, error: result.error })
+    })
+    return { started: true }
+  },
+}
+
+let backoff = 1000
+function connect() {
+  const ws = new WebSocket(`${URL_}?token=${encodeURIComponent(TOKEN)}`)
+  let ping
+  ws.on('open', () => {
+    backoff = 1000
+    log(`connected to ${URL_}`)
+    ping = setInterval(() => send(ws, { type: 'ping' }), 30_000)
+  })
+  ws.on('message', async raw => {
+    let msg
+    try {
+      msg = JSON.parse(raw.toString())
+    } catch {
+      return
+    }
+    if (msg.type === 'hello') {
+      // Tell the API which tools this bridge build implements, so a stale
+      // bridge is reported as such instead of "unknown tool".
+      send(ws, { type: 'capabilities', tools: Object.keys(tools), version: BRIDGE_VERSION, platform: process.platform })
+      return log(`registered as bridge ${msg.bridgeId} (${Object.keys(tools).length} tools)`)
+    }
+    if (msg.type !== 'call') return
+    const fn = tools[msg.tool]
+    if (!fn) return send(ws, { type: 'error', id: msg.id, error: `unknown tool ${msg.tool}` })
+    try {
+      send(ws, { type: 'result', id: msg.id, result: await fn(msg.args ?? {}, ws) })
+    } catch (err) {
+      send(ws, { type: 'error', id: msg.id, error: err.message })
+    }
+  })
+  ws.on('close', (code, reason) => {
+    clearInterval(ping)
+    if (code === 4001) {
+      log('token rejected; create a new one in the portal')
+      process.exit(1)
+    }
+    log(`disconnected (${code} ${reason}); retrying in ${backoff / 1000}s`)
+    setTimeout(connect, backoff)
+    backoff = Math.min(backoff * 2, 30_000)
+  })
+  ws.on('error', err => log(`socket error: ${err.message}`))
+}
+
+function send(ws, obj) {
+  if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj))
+}
+function log(m) {
+  console.log(`[kira-bridge ${new Date().toLocaleTimeString()}] ${m}`)
+}
+

package/src/service.mjs

@@ -0,0 +1,108 @@
+// launchd integration: run the bridge at login and keep it alive.
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, writeFileSync, existsSync, unlinkSync, readFileSync, cpSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { KIRA_DIR, LOG_PATH } from './config.mjs'
+
+// The service runs a private copy of the package under ~/.kira/app, so it keeps
+// working after npx's cache is pruned and survives package upgrades cleanly.
+const APP_DIR = join(KIRA_DIR, 'app')
+
+export const LABEL = 'com.kira.bridge'
+const PLIST = join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`)
+
+function nodePath() {
+  return process.execPath
+}
+function packageRoot() {
+  return dirname(new URL('.', import.meta.url).pathname.replace(/\/$/, ''))
+}
+
+/** Copy this package (src + package.json + node_modules/ws) into ~/.kira/app. */
+function stageApp() {
+  const root = packageRoot()
+  rmSync(APP_DIR, { recursive: true, force: true })
+  mkdirSync(APP_DIR, { recursive: true })
+  cpSync(join(root, 'src'), join(APP_DIR, 'src'), { recursive: true })
+  cpSync(join(root, 'package.json'), join(APP_DIR, 'package.json'))
+  // ws is the only dependency; resolve it from wherever npm put it.
+  const wsPkg = dirname(new URL(import.meta.resolve('ws/package.json')).pathname)
+  cpSync(wsPkg, join(APP_DIR, 'node_modules', 'ws'), { recursive: true })
+  return join(APP_DIR, 'src', 'cli.mjs')
+}
+
+export function install() {
+  if (process.platform !== 'darwin') throw new Error('the background service is only supported on macOS for now; run `kira-bridge run` in a terminal instead')
+  mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true })
+  mkdirSync(KIRA_DIR, { recursive: true, mode: 0o700 })
+  const cli = stageApp()
+  // PATH: launchd gives a minimal environment; include the usual tool dirs so
+  // `claude`, `open` and friends resolve.
+  const path = ['/opt/homebrew/bin', '/usr/local/bin', join(homedir(), '.local', 'bin'), '/usr/bin', '/bin', '/usr/sbin', '/sbin'].join(':')
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath()}</string>
+    <string>${cli}</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${LOG_PATH}</string>
+  <key>StandardErrorPath</key><string>${LOG_PATH}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${path}</string>
+    <key>HOME</key><string>${homedir()}</string>
+  </dict>
+</dict>
+</plist>
+`
+  if (existsSync(PLIST)) {
+    try {
+      execFileSync('launchctl', ['bootout', `gui/${process.getuid()}`, PLIST], { stdio: 'ignore' })
+    } catch {
+      /* not loaded */
+    }
+  }
+  writeFileSync(PLIST, plist)
+  execFileSync('launchctl', ['bootstrap', `gui/${process.getuid()}`, PLIST], { stdio: 'inherit' })
+  return { plist: PLIST, log: LOG_PATH }
+}
+
+export function uninstall() {
+  if (!existsSync(PLIST)) return false
+  try {
+    execFileSync('launchctl', ['bootout', `gui/${process.getuid()}`, PLIST], { stdio: 'ignore' })
+  } catch {
+    /* not loaded */
+  }
+  unlinkSync(PLIST)
+  rmSync(APP_DIR, { recursive: true, force: true })
+  return true
+}
+
+export function status() {
+  if (!existsSync(PLIST)) return { installed: false }
+  let running = false
+  try {
+    const out = execFileSync('launchctl', ['print', `gui/${process.getuid()}/${LABEL}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    running = /state = running/.test(out)
+  } catch {
+    running = false
+  }
+  let lastLog = ''
+  try {
+    const lines = readFileSync(LOG_PATH, 'utf8').trim().split('\n')
+    lastLog = lines.slice(-3).join('\n')
+  } catch {
+    /* no log yet */
+  }
+  return { installed: true, running, plist: PLIST, log: LOG_PATH, lastLog }
+}