@hasna/recordings 0.0.3

package/dist/cli/index.js

@@ -0,0 +1,1446 @@
+#!/usr/bin/env bun
+// @bun
+var __require = import.meta.require;
+
+// src/cli/index.ts
+import { Command } from "commander";
+import chalk from "chalk";
+
+// src/lib/config.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var DEFAULT_CONFIG = {
+  openai_api_key: "",
+  enhancement_api_key: "",
+  transcription_model: "gpt-4o-mini-transcribe",
+  enhancement_model: "gpt-4o",
+  language: "en",
+  audio_format: "wav",
+  sample_rate: 16000,
+  record_command: "sox",
+  hotkey: "space",
+  auto_enhance: true,
+  enhance_triggers: [
+    "say it better",
+    "rewrite this",
+    "make it sound",
+    "clean this up",
+    "fix this",
+    "rephrase",
+    "write it properly",
+    "make it professional",
+    "improve this",
+    "polish this"
+  ],
+  db_path: "",
+  audio_dir: "",
+  max_recording_seconds: 300
+};
+function loadConfig(configPath) {
+  const config = { ...DEFAULT_CONFIG };
+  const filePath = configPath || findConfigFile() || join(getDataDir(), "config.json");
+  if (existsSync(filePath)) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const fileConfig = JSON.parse(raw);
+      Object.assign(config, fileConfig);
+    } catch {}
+  }
+  if (process.env.OPENAI_API_KEY) {
+    config.openai_api_key = process.env.OPENAI_API_KEY;
+  }
+  if (process.env.RECORDINGS_API_KEY) {
+    config.openai_api_key = process.env.RECORDINGS_API_KEY;
+  }
+  if (process.env.RECORDINGS_ENHANCEMENT_KEY) {
+    config.enhancement_api_key = process.env.RECORDINGS_ENHANCEMENT_KEY;
+  }
+  if (process.env.RECORDINGS_MODEL) {
+    config.transcription_model = process.env.RECORDINGS_MODEL;
+  }
+  if (process.env.RECORDINGS_ENHANCEMENT_MODEL) {
+    config.enhancement_model = process.env.RECORDINGS_ENHANCEMENT_MODEL;
+  }
+  if (process.env.RECORDINGS_LANGUAGE) {
+    config.language = process.env.RECORDINGS_LANGUAGE;
+  }
+  if (process.env.RECORDINGS_DB_PATH) {
+    config.db_path = process.env.RECORDINGS_DB_PATH;
+  }
+  if (process.env.RECORDINGS_AUDIO_DIR) {
+    config.audio_dir = process.env.RECORDINGS_AUDIO_DIR;
+  }
+  if (process.env.RECORDINGS_MAX_SECONDS) {
+    config.max_recording_seconds = parseInt(process.env.RECORDINGS_MAX_SECONDS, 10);
+  }
+  if (!config.openai_api_key) {
+    config.openai_api_key = loadSecretKey("OPENAI_API_KEY");
+  }
+  if (!config.enhancement_api_key) {
+    config.enhancement_api_key = config.openai_api_key || loadSecretKey("OPENAI_API_KEY");
+  }
+  if (!config.db_path) {
+    config.db_path = join(getDataDir(), "recordings.db");
+  }
+  if (!config.audio_dir) {
+    config.audio_dir = join(getDataDir(), "audio");
+  }
+  return config;
+}
+function findConfigFile() {
+  let dir = process.cwd();
+  const root = "/";
+  while (dir !== root) {
+    const candidate = join(dir, ".recordings", "config.json");
+    if (existsSync(candidate))
+      return candidate;
+    const parent = join(dir, "..");
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+function getDataDir() {
+  let dir = process.cwd();
+  const root = "/";
+  while (dir !== root) {
+    const candidate = join(dir, ".recordings");
+    if (existsSync(candidate))
+      return candidate;
+    const parent = join(dir, "..");
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return join(homedir(), ".recordings");
+}
+function loadSecretKey(keyName) {
+  const secretsPath = join(homedir(), ".secrets");
+  if (!existsSync(secretsPath))
+    return "";
+  try {
+    const content = readFileSync(secretsPath, "utf-8");
+    const match = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*"([^"]+)"`));
+    if (match)
+      return match[1];
+    const match2 = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*'([^']+)'`));
+    if (match2)
+      return match2[1];
+    const match3 = content.match(new RegExp(`${keyName}\\s*=\\s*(.+)`));
+    if (match3)
+      return match3[1].trim().replace(/^["']|["']$/g, "");
+  } catch {}
+  return "";
+}
+function ensureDataDir(config) {
+  const { mkdirSync } = __require("fs");
+  mkdirSync(config.audio_dir, { recursive: true });
+  const dbDir = config.db_path.substring(0, config.db_path.lastIndexOf("/"));
+  if (dbDir)
+    mkdirSync(dbDir, { recursive: true });
+}
+
+// src/db/database.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+var _db = null;
+var MIGRATIONS = [
+  `
+  CREATE TABLE IF NOT EXISTS projects (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    path TEXT UNIQUE NOT NULL,
+    description TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS agents (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    role TEXT DEFAULT 'agent',
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    last_seen_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS recordings (
+    id TEXT PRIMARY KEY,
+    audio_path TEXT,
+    raw_text TEXT NOT NULL,
+    processed_text TEXT,
+    processing_mode TEXT NOT NULL DEFAULT 'raw' CHECK(processing_mode IN ('raw', 'enhanced')),
+    model_used TEXT NOT NULL DEFAULT 'gpt-4o-mini-transcribe',
+    enhancement_model TEXT,
+    duration_ms INTEGER DEFAULT 0,
+    language TEXT,
+    tags TEXT DEFAULT '[]',
+    agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
+    project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+    session_id TEXT,
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS recording_tags (
+    recording_id TEXT NOT NULL REFERENCES recordings(id) ON DELETE CASCADE,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (recording_id, tag)
+  );
+
+  CREATE TABLE IF NOT EXISTS _migrations (
+    id INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_recordings_agent ON recordings(agent_id);
+  CREATE INDEX IF NOT EXISTS idx_recordings_project ON recordings(project_id);
+  CREATE INDEX IF NOT EXISTS idx_recordings_session ON recordings(session_id);
+  CREATE INDEX IF NOT EXISTS idx_recordings_created ON recordings(created_at);
+  CREATE INDEX IF NOT EXISTS idx_recordings_mode ON recordings(processing_mode);
+  CREATE INDEX IF NOT EXISTS idx_recording_tags_tag ON recording_tags(tag);
+  `
+];
+function getDatabase(dbPath) {
+  if (_db)
+    return _db;
+  const path = dbPath || loadConfig().db_path;
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  _db = new Database(path, { create: true });
+  _db.run("PRAGMA journal_mode = WAL");
+  _db.run("PRAGMA busy_timeout = 5000");
+  _db.run("PRAGMA foreign_keys = ON");
+  runMigrations(_db);
+  return _db;
+}
+function runMigrations(db) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  const result = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
+  const currentLevel = result?.max_id ?? -1;
+  for (let i = currentLevel + 1;i < MIGRATIONS.length; i++) {
+    db.run(MIGRATIONS[i]);
+    db.query("INSERT INTO _migrations (id) VALUES (?)").run(i);
+  }
+}
+
+// src/db/recordings.ts
+function parseRow(row) {
+  return {
+    id: row["id"],
+    audio_path: row["audio_path"] || null,
+    raw_text: row["raw_text"],
+    processed_text: row["processed_text"] || null,
+    processing_mode: row["processing_mode"] || "raw",
+    model_used: row["model_used"] || "gpt-4o-mini-transcribe",
+    enhancement_model: row["enhancement_model"] || null,
+    duration_ms: row["duration_ms"] || 0,
+    language: row["language"] || null,
+    tags: JSON.parse(row["tags"] || "[]"),
+    agent_id: row["agent_id"] || null,
+    project_id: row["project_id"] || null,
+    session_id: row["session_id"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"]
+  };
+}
+function createRecording(input, db) {
+  const d = db || getDatabase();
+  const id = crypto.randomUUID();
+  const tagsJson = JSON.stringify(input.tags || []);
+  const metadataJson = JSON.stringify(input.metadata || {});
+  d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-mini-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, metadataJson);
+  if (input.tags && input.tags.length > 0) {
+    const insertTag = d.query("INSERT OR IGNORE INTO recording_tags (recording_id, tag) VALUES (?, ?)");
+    for (const tag of input.tags) {
+      insertTag.run(id, tag);
+    }
+  }
+  return getRecording(id, d);
+}
+function getRecording(id, db) {
+  const d = db || getDatabase();
+  let row = d.query("SELECT * FROM recordings WHERE id = ?").get(id);
+  if (!row) {
+    row = d.query("SELECT * FROM recordings WHERE id LIKE ? || '%'").get(id);
+  }
+  return row ? parseRow(row) : null;
+}
+function listRecordings(filter, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filter?.agent_id) {
+    conditions.push("agent_id = ?");
+    params.push(filter.agent_id);
+  }
+  if (filter?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filter.project_id);
+  }
+  if (filter?.session_id) {
+    conditions.push("session_id = ?");
+    params.push(filter.session_id);
+  }
+  if (filter?.processing_mode) {
+    conditions.push("processing_mode = ?");
+    params.push(filter.processing_mode);
+  }
+  if (filter?.tags && filter.tags.length > 0) {
+    for (const tag of filter.tags) {
+      conditions.push("id IN (SELECT recording_id FROM recording_tags WHERE tag = ?)");
+      params.push(tag);
+    }
+  }
+  if (filter?.search) {
+    conditions.push("(raw_text LIKE ? OR processed_text LIKE ? OR tags LIKE ?)");
+    const q = `%${filter.search}%`;
+    params.push(q, q, q);
+  }
+  if (filter?.since) {
+    conditions.push("created_at >= ?");
+    params.push(filter.since);
+  }
+  if (filter?.until) {
+    conditions.push("created_at <= ?");
+    params.push(filter.until);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = filter?.limit || 50;
+  const offset = filter?.offset || 0;
+  const sql = `SELECT * FROM recordings ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`;
+  params.push(limit, offset);
+  const rows = d.query(sql).all(...params);
+  return rows.map(parseRow);
+}
+function deleteRecording(id, db) {
+  const d = db || getDatabase();
+  const result = d.query("DELETE FROM recordings WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+function searchRecordings(query, filter, db) {
+  return listRecordings({ ...filter, search: query }, db);
+}
+function getRecordingStats(db) {
+  const d = db || getDatabase();
+  const total = d.query("SELECT COUNT(*) as c FROM recordings").get().c;
+  const raw = d.query("SELECT COUNT(*) as c FROM recordings WHERE processing_mode = 'raw'").get().c;
+  const enhanced = d.query("SELECT COUNT(*) as c FROM recordings WHERE processing_mode = 'enhanced'").get().c;
+  const totalDuration = d.query("SELECT COALESCE(SUM(duration_ms), 0) as d FROM recordings").get().d;
+  const modelRows = d.query("SELECT model_used, COUNT(*) as c FROM recordings GROUP BY model_used").all();
+  const byModel = {};
+  for (const row of modelRows) {
+    byModel[row.model_used] = row.c;
+  }
+  return {
+    total,
+    raw,
+    enhanced,
+    total_duration_ms: totalDuration,
+    by_model: byModel
+  };
+}
+
+// src/db/agents.ts
+function parseAgent(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    description: row["description"] || null,
+    role: row["role"] || "agent",
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"],
+    last_seen_at: row["last_seen_at"]
+  };
+}
+function listAgents(db) {
+  const d = db || getDatabase();
+  const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
+  return rows.map(parseAgent);
+}
+
+// src/db/projects.ts
+function parseProject(row) {
+  return {
+    id: row["id"],
+    name: row["name"],
+    path: row["path"],
+    description: row["description"] || null,
+    created_at: row["created_at"],
+    updated_at: row["updated_at"]
+  };
+}
+function listProjects(db) {
+  const d = db || getDatabase();
+  const rows = d.query("SELECT * FROM projects ORDER BY updated_at DESC").all();
+  return rows.map(parseProject);
+}
+
+// src/lib/recorder.ts
+import { spawn } from "child_process";
+import { join as join2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+
+// src/types/index.ts
+class RecordingError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RecordingError";
+  }
+}
+
+class TranscriptionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TranscriptionError";
+  }
+}
+
+class EnhancementError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnhancementError";
+  }
+}
+
+// src/lib/recorder.ts
+var _recordProcess = null;
+var _currentFile = null;
+async function checkRecordingDeps() {
+  try {
+    const proc = Bun.spawn(["which", "sox"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return { available: true, tool: "sox", message: "sox is available" };
+    }
+  } catch {}
+  try {
+    const proc = Bun.spawn(["which", "rec"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return { available: true, tool: "rec", message: "rec is available" };
+    }
+  } catch {}
+  try {
+    const proc = Bun.spawn(["which", "ffmpeg"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      return {
+        available: true,
+        tool: "ffmpeg",
+        message: "ffmpeg is available"
+      };
+    }
+  } catch {}
+  return {
+    available: false,
+    tool: "none",
+    message: "No recording tool found. Install sox: brew install sox (macOS) or apt install sox (Linux)"
+  };
+}
+function startRecording(config) {
+  if (_recordProcess) {
+    throw new RecordingError("Already recording. Stop the current recording first.");
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `recording-${timestamp}.${config.audio_format}`;
+  const filepath = join2(config.audio_dir, filename);
+  const args = buildRecordArgs(filepath, config);
+  _recordProcess = spawn(args[0], args.slice(1), {
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  _currentFile = filepath;
+  _recordProcess.on("error", (err) => {
+    _recordProcess = null;
+    _currentFile = null;
+    throw new RecordingError(`Recording process error: ${err.message}`);
+  });
+  _recordProcess.on("exit", () => {
+    _recordProcess = null;
+  });
+  return filepath;
+}
+function stopRecording() {
+  if (!_recordProcess) {
+    return null;
+  }
+  const filepath = _currentFile;
+  _recordProcess.kill("SIGINT");
+  _recordProcess = null;
+  _currentFile = null;
+  return filepath;
+}
+function buildRecordArgs(filepath, config) {
+  const format = config.audio_format;
+  const rate = config.sample_rate;
+  const maxSeconds = config.max_recording_seconds;
+  return [
+    "rec",
+    "-r",
+    rate.toString(),
+    "-c",
+    "1",
+    "-b",
+    "16",
+    filepath,
+    "trim",
+    "0",
+    maxSeconds.toString()
+  ];
+}
+async function recordDuration(seconds, config) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `recording-${timestamp}.${config.audio_format}`;
+  const filepath = join2(config.audio_dir, filename);
+  const args = [
+    "rec",
+    "-r",
+    config.sample_rate.toString(),
+    "-c",
+    "1",
+    "-b",
+    "16",
+    filepath,
+    "trim",
+    "0",
+    seconds.toString()
+  ];
+  const proc = Bun.spawn(args, {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0 && !existsSync2(filepath)) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new RecordingError(`Recording failed (exit ${exitCode}): ${stderr}`);
+  }
+  return filepath;
+}
+
+// src/lib/transcriber.ts
+import OpenAI from "openai";
+import { createReadStream } from "fs";
+var _client = null;
+function getClient(config) {
+  if (_client)
+    return _client;
+  if (!config.openai_api_key) {
+    throw new TranscriptionError("OpenAI API key not configured. Set OPENAI_API_KEY env var or add to ~/.secrets");
+  }
+  _client = new OpenAI({ apiKey: config.openai_api_key });
+  return _client;
+}
+async function transcribeAudio(audioPath, config) {
+  const client = getClient(config);
+  const startTime = Date.now();
+  try {
+    const transcription = await client.audio.transcriptions.create({
+      file: createReadStream(audioPath),
+      model: config.transcription_model,
+      language: config.language || undefined,
+      response_format: "json"
+    });
+    const durationMs = Date.now() - startTime;
+    return {
+      text: transcription.text,
+      duration_ms: durationMs,
+      model: config.transcription_model,
+      language: transcription.language
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new TranscriptionError(`Transcription failed: ${msg}`);
+  }
+}
+
+// src/lib/enhancer.ts
+import OpenAI2 from "openai";
+var _enhancementClient = null;
+function getEnhancementClient(config) {
+  if (_enhancementClient)
+    return _enhancementClient;
+  const key = config.enhancement_api_key || config.openai_api_key;
+  if (!key) {
+    throw new EnhancementError("API key not configured for enhancement. Set OPENAI_API_KEY or RECORDINGS_ENHANCEMENT_KEY");
+  }
+  _enhancementClient = new OpenAI2({ apiKey: key });
+  return _enhancementClient;
+}
+function needsEnhancement(text, config) {
+  const lower = text.toLowerCase().trim();
+  for (const trigger of config.enhance_triggers) {
+    if (lower.includes(trigger.toLowerCase())) {
+      return {
+        needs: true,
+        reason: `Explicit trigger: "${trigger}"`,
+        instruction: extractInstruction(text, trigger)
+      };
+    }
+  }
+  const instructionPatterns = [
+    /(?:write|draft|compose|create)\s+(?:an?\s+)?(?:email|message|response|reply|letter|note|text|slack|dm)/i,
+    /(?:give|provide|send)\s+(?:them|him|her|it|the\s+agent|the\s+team)\s+(?:full\s+)?instructions/i,
+    /(?:tell|ask)\s+(?:them|him|her|it|the\s+agent)\s+(?:to|that)/i,
+    /(?:make\s+it|make\s+this)\s+(?:sound|look|read)\s+(?:more\s+)?(?:professional|formal|casual|friendly|better)/i,
+    /(?:ok\s+so|okay\s+so|alright\s+so)\s+(?:say|write|tell|put)/i,
+    /(?:i\s+need|i\s+want)\s+(?:the\s+agent|it|them|you)\s+to\s+(?:build|create|implement|design|make)/i
+  ];
+  for (const pattern of instructionPatterns) {
+    if (pattern.test(text)) {
+      return {
+        needs: true,
+        reason: `Instruction pattern detected`,
+        instruction: text
+      };
+    }
+  }
+  return { needs: false, reason: "Direct dictation", instruction: text };
+}
+function extractInstruction(text, trigger) {
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(trigger.toLowerCase());
+  if (idx === -1)
+    return text;
+  const after = text.substring(idx + trigger.length).trim();
+  const before = text.substring(0, idx).trim();
+  if (before.length > after.length && before.length > 10) {
+    return before;
+  }
+  return text;
+}
+async function enhanceText(rawText, instruction, config) {
+  const client = getEnhancementClient(config);
+  try {
+    const response = await client.chat.completions.create({
+      model: config.enhancement_model,
+      messages: [
+        {
+          role: "system",
+          content: `You are a writing assistant. The user has dictated speech that needs to be transformed into polished output.
+
+Rules:
+- Output ONLY the enhanced/rewritten text \u2014 no explanations, no preamble
+- Preserve the user's intent and meaning
+- Fix grammar, structure, and clarity
+- If the user is giving instructions (e.g., "write an email saying..."), produce the actual output (the email), not a description of it
+- If the user says "say it better" or similar, rewrite their preceding text to be clearer and more professional
+- Match the appropriate tone (formal for business, casual for personal)`
+        },
+        {
+          role: "user",
+          content: instruction
+        }
+      ],
+      temperature: 0.3,
+      max_tokens: 4096
+    });
+    const enhanced = response.choices[0]?.message?.content?.trim() || rawText;
+    return {
+      original: rawText,
+      enhanced,
+      model: config.enhancement_model,
+      reasoning: null
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new EnhancementError(`Enhancement failed: ${msg}`);
+  }
+}
+async function processText(rawText, config) {
+  if (!config.auto_enhance) {
+    return { text: rawText, mode: "raw", enhancement_model: null };
+  }
+  const detection = needsEnhancement(rawText, config);
+  if (!detection.needs) {
+    return { text: rawText, mode: "raw", enhancement_model: null };
+  }
+  const result = await enhanceText(rawText, detection.instruction, config);
+  return {
+    text: result.enhanced,
+    mode: "enhanced",
+    enhancement_model: result.model
+  };
+}
+
+// src/cli/index.ts
+var __dirname = "/Users/hasna/Workspace/hasna/opensource/opensourcedev/open-recordings/src/cli";
+var program = new Command;
+program.name("recordings").description("Speech-to-text recording tool \u2014 record, transcribe, and enhance with AI").version("0.0.1").option("--json", "Output as JSON").option("--agent <name>", "Agent name or ID").option("--project <name>", "Project name or ID").option("--session <id>", "Session ID");
+program.command("record").description("Record from microphone, transcribe, and optionally enhance").option("-d, --duration <seconds>", "Record for specific duration").option("--no-enhance", "Skip AI enhancement").option("-t, --tags <tags>", "Comma-separated tags").option("-l, --language <lang>", "Language code (e.g. en, es, fr)").action(async (opts) => {
+  const config = loadConfig();
+  ensureDataDir(config);
+  if (opts.language)
+    config.language = opts.language;
+  if (opts.noEnhance === false)
+    config.auto_enhance = false;
+  const deps = await checkRecordingDeps();
+  if (!deps.available) {
+    console.error(chalk.red(`Error: ${deps.message}`));
+    process.exit(1);
+  }
+  let audioPath;
+  if (opts.duration) {
+    const seconds = parseInt(opts.duration, 10);
+    console.log(chalk.blue(`Recording for ${seconds} seconds...`));
+    audioPath = await recordDuration(seconds, config);
+    console.log(chalk.green("Recording complete."));
+  } else {
+    console.log(chalk.blue("Recording... Press") + chalk.yellow(" Enter ") + chalk.blue("to stop."));
+    audioPath = startRecording(config);
+    await new Promise((resolve) => {
+      process.stdin.setRawMode?.(true);
+      process.stdin.resume();
+      process.stdin.once("data", () => {
+        process.stdin.setRawMode?.(false);
+        process.stdin.pause();
+        resolve();
+      });
+    });
+    stopRecording();
+    console.log(chalk.green("Recording stopped."));
+  }
+  console.log(chalk.blue("Transcribing..."));
+  const transcription = await transcribeAudio(audioPath, config);
+  console.log(chalk.dim(`Raw: ${transcription.text}`));
+  const processed = await processText(transcription.text, config);
+  if (processed.mode === "enhanced") {
+    console.log(chalk.green(`
+Enhanced output:`));
+    console.log(processed.text);
+  } else {
+    console.log(chalk.green(`
+Output:`));
+    console.log(transcription.text);
+  }
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
+  const parentOpts = program.opts();
+  const recording = createRecording({
+    audio_path: audioPath,
+    raw_text: transcription.text,
+    processed_text: processed.mode === "enhanced" ? processed.text : undefined,
+    processing_mode: processed.mode,
+    model_used: transcription.model,
+    enhancement_model: processed.enhancement_model || undefined,
+    duration_ms: transcription.duration_ms,
+    language: transcription.language || undefined,
+    tags,
+    agent_id: parentOpts.agent || undefined,
+    project_id: parentOpts.project || undefined,
+    session_id: parentOpts.session || undefined
+  });
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recording, null, 2));
+  } else {
+    console.log(chalk.dim(`
+Saved as ${recording.id.slice(0, 8)}`));
+  }
+});
+program.command("transcribe <file>").description("Transcribe an existing audio file").option("--no-enhance", "Skip AI enhancement").option("-t, --tags <tags>", "Comma-separated tags").action(async (file, opts) => {
+  const config = loadConfig();
+  ensureDataDir(config);
+  if (opts.noEnhance === false)
+    config.auto_enhance = false;
+  console.log(chalk.blue("Transcribing..."));
+  const transcription = await transcribeAudio(file, config);
+  const processed = await processText(transcription.text, config);
+  const parentOpts = program.opts();
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
+  const recording = createRecording({
+    audio_path: file,
+    raw_text: transcription.text,
+    processed_text: processed.mode === "enhanced" ? processed.text : undefined,
+    processing_mode: processed.mode,
+    model_used: transcription.model,
+    enhancement_model: processed.enhancement_model || undefined,
+    duration_ms: transcription.duration_ms,
+    language: transcription.language || undefined,
+    tags,
+    agent_id: parentOpts.agent || undefined,
+    project_id: parentOpts.project || undefined,
+    session_id: parentOpts.session || undefined
+  });
+  if (processed.mode === "enhanced") {
+    console.log(chalk.green("Enhanced:"));
+    console.log(processed.text);
+  } else {
+    console.log(chalk.green("Transcription:"));
+    console.log(transcription.text);
+  }
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recording, null, 2));
+  } else {
+    console.log(chalk.dim(`Saved as ${recording.id.slice(0, 8)}`));
+  }
+});
+program.command("list").description("List recordings").option("-n, --limit <n>", "Max results", "20").option("--mode <mode>", "Filter by mode: raw or enhanced").option("-t, --tags <tags>", "Filter by tags").option("--since <date>", "After date (ISO)").option("--until <date>", "Before date (ISO)").action((opts) => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const recordings = listRecordings({
+    limit: parseInt(opts.limit, 10),
+    processing_mode: opts.mode,
+    tags: opts.tags ? opts.tags.split(",") : undefined,
+    since: opts.since,
+    until: opts.until,
+    agent_id: parentOpts.agent,
+    project_id: parentOpts.project,
+    session_id: parentOpts.session
+  });
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recordings, null, 2));
+    return;
+  }
+  if (recordings.length === 0) {
+    console.log(chalk.dim("No recordings found."));
+    return;
+  }
+  console.log(chalk.bold(`${recordings.length} recording(s):
+`));
+  for (const r of recordings) {
+    console.log(formatRecordingLine(r));
+  }
+});
+program.command("show <id>").description("Show recording details").action((id) => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const recording = getRecording(id);
+  if (!recording) {
+    console.error(chalk.red(`Recording not found: ${id}`));
+    process.exit(1);
+  }
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recording, null, 2));
+    return;
+  }
+  console.log(formatRecordingDetail(recording));
+});
+program.command("search <query>").description("Search recordings by text content").option("-n, --limit <n>", "Max results", "20").action((query, opts) => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const results = searchRecordings(query, {
+    limit: parseInt(opts.limit, 10),
+    agent_id: parentOpts.agent,
+    project_id: parentOpts.project
+  });
+  if (parentOpts.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (results.length === 0) {
+    console.log(chalk.dim("No results."));
+    return;
+  }
+  console.log(chalk.bold(`${results.length} result(s):
+`));
+  for (const r of results) {
+    console.log(formatRecordingLine(r));
+  }
+});
+program.command("delete <id>").description("Delete a recording").action((id) => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const deleted = deleteRecording(id);
+  if (deleted) {
+    console.log(chalk.green(`Deleted recording ${id}`));
+  } else {
+    console.error(chalk.red(`Recording not found: ${id}`));
+    process.exit(1);
+  }
+});
+program.command("stats").description("Show recording statistics").action(() => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const stats = getRecordingStats();
+  if (parentOpts.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return;
+  }
+  console.log(chalk.bold(`Recording Statistics
+`));
+  console.log(`  Total:      ${stats.total}`);
+  console.log(`  Raw:        ${stats.raw}`);
+  console.log(`  Enhanced:   ${stats.enhanced}`);
+  console.log(`  Duration:   ${(stats.total_duration_ms / 1000).toFixed(1)}s`);
+  if (Object.keys(stats.by_model).length > 0) {
+    console.log(`  By model:`);
+    for (const [model, count] of Object.entries(stats.by_model)) {
+      console.log(`    ${model}: ${count}`);
+    }
+  }
+});
+program.command("agents").description("List registered agents").action(() => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const agents = listAgents();
+  if (parentOpts.json) {
+    console.log(JSON.stringify(agents, null, 2));
+    return;
+  }
+  if (agents.length === 0) {
+    console.log(chalk.dim("No agents registered."));
+    return;
+  }
+  for (const a of agents) {
+    console.log(`${chalk.cyan(a.id)} ${chalk.bold(a.name)} (${a.role}) \u2014 last seen ${a.last_seen_at}`);
+  }
+});
+program.command("projects").description("List registered projects").action(() => {
+  const config = loadConfig();
+  getDatabase(config.db_path);
+  const parentOpts = program.opts();
+  const projects = listProjects();
+  if (parentOpts.json) {
+    console.log(JSON.stringify(projects, null, 2));
+    return;
+  }
+  if (projects.length === 0) {
+    console.log(chalk.dim("No projects registered."));
+    return;
+  }
+  for (const p of projects) {
+    console.log(`${chalk.cyan(p.id.slice(0, 8))} ${chalk.bold(p.name)} \u2014 ${p.path}`);
+  }
+});
+program.command("init").description("Initialize .recordings/ in current directory").action(() => {
+  const { mkdirSync: mkdirSync2, writeFileSync, existsSync: existsSync3 } = __require("fs");
+  const { join: join3 } = __require("path");
+  const dir = join3(process.cwd(), ".recordings");
+  const audioDir = join3(dir, "audio");
+  const configFile = join3(dir, "config.json");
+  mkdirSync2(audioDir, { recursive: true });
+  if (!existsSync3(configFile)) {
+    const defaultConf = {
+      transcription_model: "gpt-4o-mini-transcribe",
+      enhancement_model: "gpt-4o",
+      language: "en",
+      auto_enhance: true
+    };
+    writeFileSync(configFile, JSON.stringify(defaultConf, null, 2));
+  }
+  console.log(chalk.green("Initialized .recordings/ directory"));
+  console.log(chalk.dim("  config: .recordings/config.json"));
+  console.log(chalk.dim("  audio:  .recordings/audio/"));
+  console.log(chalk.dim("  db:     .recordings/recordings.db"));
+});
+program.command("check").description("Check system dependencies (sox, API keys)").action(async () => {
+  const config = loadConfig();
+  const deps = await checkRecordingDeps();
+  if (deps.available) {
+    console.log(chalk.green(`\u2713 Recording tool: ${deps.tool}`));
+  } else {
+    console.log(chalk.red(`\u2717 ${deps.message}`));
+  }
+  if (config.openai_api_key) {
+    console.log(chalk.green(`\u2713 OpenAI API key configured`));
+  } else {
+    console.log(chalk.red(`\u2717 OpenAI API key not found. Set OPENAI_API_KEY env var or add to ~/.secrets`));
+  }
+  const enhKey = config.enhancement_api_key || config.openai_api_key;
+  if (enhKey) {
+    console.log(chalk.green(`\u2713 Enhancement API key configured (model: ${config.enhancement_model})`));
+  } else {
+    console.log(chalk.yellow(`\u26A0 Enhancement API key not configured \u2014 enhancement disabled`));
+  }
+});
+program.command("start").description("Launch the menu bar helper app (F5 to toggle recording)").option("--login", "Also add to Login Items so it starts automatically").action(async (opts) => {
+  const { execSync } = __require("child_process");
+  const { join: pathJoin } = __require("path");
+  const { homedir: getHome } = __require("os");
+  const { existsSync: fileExists } = __require("fs");
+  const home = getHome();
+  const appPath = pathJoin(home, ".recordings", "RecordingsHelper.app");
+  if (!fileExists(appPath)) {
+    console.error(chalk.red("RecordingsHelper.app not found. Run: recordings shortcut --install"));
+    process.exit(1);
+  }
+  try {
+    execSync("pkill -f RecordingsHelper", { stdio: "pipe" });
+  } catch {}
+  execSync(`open "${appPath}"`, { stdio: "pipe" });
+  console.log(chalk.green("Recordings helper launched \u2014 press F5 to record"));
+  if (opts.login) {
+    try {
+      execSync(`osascript -e 'tell application "System Events" to make login item at end with properties {path:"${appPath}", hidden:true}'`, { stdio: "pipe" });
+      console.log(chalk.green("Added to Login Items \u2014 will start on boot"));
+    } catch {
+      console.log(chalk.yellow("Could not add to Login Items \u2014 add manually in System Settings > General > Login Items"));
+    }
+  }
+});
+program.command("stop").description("Stop the menu bar helper app").action(() => {
+  const { execSync } = __require("child_process");
+  try {
+    execSync("pkill -f RecordingsHelper", { stdio: "pipe" });
+    console.log(chalk.green("Recordings helper stopped"));
+  } catch {
+    console.log(chalk.dim("Not running"));
+  }
+});
+program.command("listen").description("Push-to-talk mode \u2014 press Space to start/stop recording, Esc to quit").option("-t, --tags <tags>", "Comma-separated tags for all recordings").option("--no-enhance", "Skip AI enhancement").option("-l, --language <lang>", "Language code").option("--copy", "Copy output to clipboard").option("--paste", "Copy output to clipboard AND paste into frontmost app").action(async (opts) => {
+  const config = loadConfig();
+  ensureDataDir(config);
+  if (opts.language)
+    config.language = opts.language;
+  if (opts.noEnhance === false)
+    config.auto_enhance = false;
+  const deps = await checkRecordingDeps();
+  if (!deps.available) {
+    console.error(chalk.red(`Error: ${deps.message}`));
+    process.exit(1);
+  }
+  if (!config.openai_api_key) {
+    console.error(chalk.red("Error: OpenAI API key not configured."));
+    process.exit(1);
+  }
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
+  const parentOpts = program.opts();
+  console.log(chalk.bold(`
+  Recordings \u2014 Push-to-Talk
+`));
+  console.log(`  ${chalk.yellow("Space")}  Start/stop recording`);
+  console.log(`  ${chalk.yellow("Esc")}    Quit
+`);
+  let recording = false;
+  let audioPath = null;
+  process.stdin.setRawMode?.(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+  const cleanup = () => {
+    process.stdin.setRawMode?.(false);
+    process.stdin.pause();
+  };
+  process.stdin.on("data", async (key) => {
+    if (key === "\x1B") {
+      if (recording) {
+        stopRecording();
+      }
+      cleanup();
+      console.log(chalk.dim(`
+Bye.`));
+      process.exit(0);
+    }
+    if (key === "\x03") {
+      if (recording) {
+        stopRecording();
+      }
+      cleanup();
+      process.exit(0);
+    }
+    if (key === " ") {
+      if (!recording) {
+        try {
+          audioPath = startRecording(config);
+          recording = true;
+          process.stdout.write(chalk.red("  \u25CF Recording... ") + chalk.dim("(Space to stop)"));
+        } catch (e) {
+          console.error(chalk.red(`
+  Error: ${e instanceof Error ? e.message : e}`));
+        }
+      } else {
+        stopRecording();
+        recording = false;
+        process.stdout.write("\r" + " ".repeat(60) + "\r");
+        if (!audioPath)
+          return;
+        process.stdout.write(chalk.blue("  Transcribing..."));
+        try {
+          const transcription = await transcribeAudio(audioPath, config);
+          const processed = await processText(transcription.text, config);
+          const output = processed.mode === "enhanced" ? processed.text : transcription.text;
+          createRecording({
+            audio_path: audioPath,
+            raw_text: transcription.text,
+            processed_text: processed.mode === "enhanced" ? processed.text : undefined,
+            processing_mode: processed.mode,
+            model_used: transcription.model,
+            enhancement_model: processed.enhancement_model || undefined,
+            duration_ms: transcription.duration_ms,
+            language: transcription.language || undefined,
+            tags,
+            agent_id: parentOpts.agent || undefined,
+            project_id: parentOpts.project || undefined,
+            session_id: parentOpts.session || undefined
+          });
+          process.stdout.write("\r" + " ".repeat(60) + "\r");
+          const modeLabel = processed.mode === "enhanced" ? chalk.green("  [enhanced] ") : chalk.dim("  [raw] ");
+          console.log(modeLabel + output);
+          if (opts.copy || opts.paste) {
+            try {
+              const { execSync } = __require("child_process");
+              execSync("pbcopy", { input: output, stdio: ["pipe", "pipe", "pipe"] });
+              if (opts.paste) {
+                execSync(`osascript -e 'delay 0.1' -e 'tell application "System Events" to keystroke "v" using command down'`, { stdio: "pipe" });
+              }
+            } catch {}
+          }
+          console.log("");
+        } catch (e) {
+          process.stdout.write("\r" + " ".repeat(60) + "\r");
+          console.error(chalk.red(`  Error: ${e instanceof Error ? e.message : e}
+`));
+        }
+        audioPath = null;
+      }
+    }
+  });
+});
+program.command("shortcut").description("Set up a global keyboard shortcut for recording (macOS)").option("--raycast", "Generate Raycast script command").option("--install", "Set up F5 global shortcut via macOS Services (no extra installs)").option("--karabiner", "Set up Fn key via Karabiner-Elements").option("--skhd", "Generate skhd hotkey config").option("--hammerspoon", "Generate Hammerspoon config").option("--script", "Just output the shell script path").action((opts) => {
+  const { writeFileSync, mkdirSync: mkdirSync2, chmodSync, existsSync: fileExists } = __require("fs");
+  const { join: pathJoin } = __require("path");
+  const { homedir: getHome } = __require("os");
+  const home = getHome();
+  const scriptDir = pathJoin(home, ".recordings");
+  mkdirSync2(scriptDir, { recursive: true });
+  const scriptPath = pathJoin(scriptDir, "record-toggle.sh");
+  const pidFile = pathJoin(scriptDir, ".recording.pid");
+  const recordingsBin = pathJoin(home, ".bun", "bin", "recordings");
+  const script = `#!/bin/bash
+# Toggle recording on/off. Run this from a global hotkey.
+# Each press toggles: start recording -> stop + transcribe + copy to clipboard
+set -e
+
+PID_FILE="${pidFile}"
+RECORDINGS="${recordingsBin}"
+
+if [ -f "$PID_FILE" ]; then
+  # Stop recording
+  PID=$(cat "$PID_FILE")
+  kill -INT "$PID" 2>/dev/null || true
+  rm -f "$PID_FILE"
+
+  # Find the most recent audio file
+  AUDIO_DIR="${pathJoin(scriptDir, "audio")}"
+  LATEST=$(ls -t "$AUDIO_DIR"/*.wav 2>/dev/null | head -1)
+
+  if [ -n "$LATEST" ]; then
+    # Transcribe and copy to clipboard
+    OUTPUT=$("$RECORDINGS" transcribe "$LATEST" --json 2>/dev/null)
+    TEXT=$(echo "$OUTPUT" | grep -o '"processed_text":"[^"]*"' | head -1 | cut -d'"' -f4)
+    if [ -z "$TEXT" ]; then
+      TEXT=$(echo "$OUTPUT" | grep -o '"raw_text":"[^"]*"' | head -1 | cut -d'"' -f4)
+    fi
+    if [ -n "$TEXT" ]; then
+      echo -n "$TEXT" | pbcopy
+      # Optional: paste into frontmost app
+      # osascript -e 'delay 0.1' -e 'tell application "System Events" to keystroke "v" using command down'
+    fi
+  fi
+
+  # Notification
+  osascript -e 'display notification "Recording saved and copied to clipboard" with title "Recordings"' 2>/dev/null || true
+else
+  # Start recording in background
+  mkdir -p "${pathJoin(scriptDir, "audio")}"
+  rec -r 16000 -c 1 -b 16 "${pathJoin(scriptDir, "audio")}/recording-$(date +%Y%m%dT%H%M%S).wav" trim 0 300 &
+  echo $! > "$PID_FILE"
+
+  # Notification
+  osascript -e 'display notification "Recording started..." with title "Recordings"' 2>/dev/null || true
+fi
+`;
+  writeFileSync(scriptPath, script, "utf-8");
+  chmodSync(scriptPath, 493);
+  if (opts.install) {
+    const { execSync: exec } = __require("child_process");
+    const appPath = pathJoin(home, ".recordings", "RecordingsHelper.app");
+    const srcSwift = pathJoin(__dirname, "..", "native", "RecordingsHelper.swift");
+    const distApp = pathJoin(__dirname, "..", "RecordingsHelper.app");
+    if (fileExists(pathJoin(distApp, "Contents", "MacOS", "RecordingsHelper"))) {
+      exec(`rm -rf "${appPath}" && cp -R "${distApp}" "${appPath}"`, { stdio: "pipe", shell: "/bin/bash" });
+    } else if (fileExists(srcSwift)) {
+      console.log(chalk.blue("Compiling native helper app..."));
+      const appDir = pathJoin(home, ".recordings", "RecordingsHelper.app", "Contents", "MacOS");
+      mkdirSync2(appDir, { recursive: true });
+      const plistDir = pathJoin(home, ".recordings", "RecordingsHelper.app", "Contents");
+      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>CFBundleExecutable</key><string>RecordingsHelper</string>
+<key>CFBundleIdentifier</key><string>com.hasna.recordings-helper</string>
+<key>CFBundleName</key><string>Recordings</string>
+<key>LSUIElement</key><true/>
+<key>NSMicrophoneUsageDescription</key><string>Recordings needs microphone access for speech transcription.</string>
+</dict></plist>`;
+      writeFileSync(pathJoin(plistDir, "Info.plist"), plist, "utf-8");
+      try {
+        exec(`DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun swiftc -O -o "${appDir}/RecordingsHelper" "${srcSwift}" -framework Cocoa -framework Carbon`, { stdio: "pipe" });
+      } catch {
+        exec(`swiftc -O -o "${appDir}/RecordingsHelper" "${srcSwift}" -framework Cocoa -framework Carbon`, { stdio: "pipe" });
+      }
+    } else {
+      console.error(chalk.red("Cannot find RecordingsHelper. Run from the project directory or rebuild."));
+      process.exit(1);
+    }
+    try {
+      exec("pkill -f RecordingsHelper", { stdio: "pipe" });
+    } catch {}
+    exec(`open "${appPath}"`, { stdio: "pipe" });
+    try {
+      exec(`osascript -e 'tell application "System Events" to make login item at end with properties {path:"${appPath}", hidden:true}'`, { stdio: "pipe" });
+    } catch {}
+    console.log(chalk.green(`
+Recordings helper installed and running!
+`));
+    console.log(`  ${chalk.yellow("F5")}     Start/stop recording`);
+    console.log(`  ${chalk.dim("\uD83C\uDF99")}      Menu bar icon (click for options)`);
+    console.log(`  ${chalk.dim("Auto")}   Starts on login
+`);
+    console.log(chalk.dim("  Press F5 \u2192 speak \u2192 F5 \u2192 text is pasted where your cursor is."));
+    return;
+  }
+  if (opts.karabiner) {
+    const karabinerDir = pathJoin(home, ".config", "karabiner", "assets", "complex_modifications");
+    mkdirSync2(karabinerDir, { recursive: true });
+    const rule = {
+      title: "Recordings \u2014 Fn key to toggle recording",
+      rules: [
+        {
+          description: "Fn key toggles speech recording (open-recordings)",
+          manipulators: [
+            {
+              type: "basic",
+              from: {
+                key_code: "fn",
+                modifiers: { optional: ["any"] }
+              },
+              to: [
+                {
+                  shell_command: scriptPath
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    };
+    const karabinerPath = pathJoin(karabinerDir, "recordings-fn.json");
+    writeFileSync(karabinerPath, JSON.stringify(rule, null, 2) + `
+`, "utf-8");
+    console.log(chalk.green("Karabiner-Elements rule created!"));
+    console.log(chalk.dim(`  ${karabinerPath}
+`));
+    console.log("To activate:");
+    console.log("  1. Open Karabiner-Elements");
+    console.log("  2. Go to Complex Modifications tab");
+    console.log("  3. Click Add Predefined Rule");
+    console.log('  4. Enable "Fn key toggles speech recording"');
+    console.log(chalk.dim(`
+  Press Fn to start recording, Fn again to stop + copy to clipboard`));
+    return;
+  }
+  if (opts.raycast) {
+    const raycastDir = pathJoin(home, ".config", "raycast", "script-commands");
+    mkdirSync2(raycastDir, { recursive: true });
+    const raycastScript = `#!/bin/bash
+
+# Required parameters:
+# @raycast.schemaVersion 1
+# @raycast.title Toggle Recording
+# @raycast.mode silent
+# @raycast.packageName Recordings
+
+# Optional parameters:
+# @raycast.icon \uD83C\uDF99\uFE0F
+
+${scriptPath}
+`;
+    const raycastPath = pathJoin(raycastDir, "toggle-recording.sh");
+    writeFileSync(raycastPath, raycastScript, "utf-8");
+    chmodSync(raycastPath, 493);
+    console.log(chalk.green("Raycast script command created!"));
+    console.log(chalk.dim(`  ${raycastPath}`));
+    console.log(chalk.dim("  Open Raycast > Script Commands > reload to see it"));
+    console.log(chalk.dim("  Then assign a hotkey in Raycast preferences"));
+    return;
+  }
+  if (opts.skhd) {
+    console.log(chalk.bold(`Add to ~/.skhdrc:
+`));
+    console.log(chalk.cyan(`  fn - space : ${scriptPath}`));
+    console.log(chalk.dim(`
+  Then reload: skhd --restart-service`));
+    return;
+  }
+  if (opts.hammerspoon) {
+    console.log(chalk.bold(`Add to ~/.hammerspoon/init.lua:
+`));
+    console.log(chalk.cyan(`  hs.hotkey.bind({"ctrl"}, "space", function()
+    hs.execute("${scriptPath}")
+  end)`));
+    console.log(chalk.dim(`
+  Then reload Hammerspoon config`));
+    return;
+  }
+  console.log(chalk.bold("Global shortcut script created:"));
+  console.log(chalk.cyan(`  ${scriptPath}
+`));
+  console.log(`Bind it to a hotkey using any of these:
+`);
+  console.log(chalk.bold("  macOS built-in") + chalk.dim(" (no extra installs \u2014 recommended)"));
+  console.log(`    recordings shortcut --install
+`);
+  console.log(chalk.bold("  Karabiner-Elements") + chalk.dim(" (for Fn key specifically)"));
+  console.log(`    brew install --cask karabiner-elements`);
+  console.log(`    recordings shortcut --karabiner
+`);
+  console.log(chalk.bold("  Raycast"));
+  console.log(`    recordings shortcut --raycast
+`);
+  console.log(chalk.bold("  skhd"));
+  console.log(`    recordings shortcut --skhd
+`);
+  console.log(chalk.bold("  Hammerspoon"));
+  console.log(`    recordings shortcut --hammerspoon
+`);
+  console.log(chalk.bold("  macOS Automator"));
+  console.log(`    1. Open Automator > Quick Action`);
+  console.log(`    2. Add "Run Shell Script" action`);
+  console.log(`    3. Paste: ${scriptPath}`);
+  console.log(`    4. Save as "Toggle Recording"`);
+  console.log(`    5. System Settings > Keyboard > Shortcuts > Services`);
+  console.log(`    6. Assign a shortcut to "Toggle Recording"
+`);
+  console.log(chalk.bold("  Alfred"));
+  console.log(`    Create a workflow with a Hotkey trigger \u2192 Run Script: ${scriptPath}
+`);
+});
+function formatRecordingLine(r) {
+  const id = chalk.cyan(r.id.slice(0, 8));
+  const mode = r.processing_mode === "enhanced" ? chalk.green("enhanced") : chalk.dim("raw");
+  const text = (r.processed_text || r.raw_text).slice(0, 80);
+  const date = chalk.dim(r.created_at.slice(0, 16));
+  const tags = r.tags.length > 0 ? chalk.yellow(` [${r.tags.join(", ")}]`) : "";
+  return `${id} ${mode} ${date}${tags}
+  ${text}${text.length >= 80 ? "..." : ""}`;
+}
+function formatRecordingDetail(r) {
+  const lines = [
+    chalk.bold(`Recording ${r.id.slice(0, 8)}`),
+    "",
+    `  Mode:     ${r.processing_mode === "enhanced" ? chalk.green("enhanced") : chalk.dim("raw")}`,
+    `  Model:    ${r.model_used}`
+  ];
+  if (r.enhancement_model) {
+    lines.push(`  Enhanced: ${r.enhancement_model}`);
+  }
+  if (r.duration_ms) {
+    lines.push(`  Duration: ${(r.duration_ms / 1000).toFixed(1)}s`);
+  }
+  if (r.language) {
+    lines.push(`  Language: ${r.language}`);
+  }
+  if (r.audio_path) {
+    lines.push(`  Audio:    ${r.audio_path}`);
+  }
+  if (r.tags.length > 0) {
+    lines.push(`  Tags:     ${r.tags.join(", ")}`);
+  }
+  lines.push(`  Created:  ${r.created_at}`);
+  lines.push("");
+  lines.push(chalk.bold("Raw text:"));
+  lines.push(r.raw_text);
+  if (r.processed_text && r.processed_text !== r.raw_text) {
+    lines.push("");
+    lines.push(chalk.bold("Enhanced text:"));
+    lines.push(r.processed_text);
+  }
+  return lines.join(`
+`);
+}
+program.command("mcp").description("Install recordings MCP server into Claude Code, Codex, or Gemini").option("--claude", "Install into Claude Code (via `claude mcp add`)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove recordings MCP from config").action(async (opts) => {
+  const { readFileSync: readFileSync2, writeFileSync, existsSync: fileExists } = __require("fs");
+  const { join: pathJoin } = __require("path");
+  const { homedir: getHome } = __require("os");
+  const { execSync } = __require("child_process");
+  const home = getHome();
+  const mcpCmd = process.argv[0]?.includes("bun") ? pathJoin(home, ".bun", "bin", "recordings-mcp") : "recordings-mcp";
+  const targets = opts.all ? ["claude", "codex", "gemini"] : [
+    opts.claude ? "claude" : null,
+    opts.codex ? "codex" : null,
+    opts.gemini ? "gemini" : null
+  ].filter(Boolean);
+  if (targets.length === 0) {
+    console.log(chalk.yellow("Specify a target: --claude, --codex, --gemini, or --all"));
+    console.log(chalk.gray("Example: recordings mcp --all"));
+    return;
+  }
+  const action = opts.uninstall ? "Removed from" : "Installed into";
+  for (const target of targets) {
+    try {
+      if (target === "claude") {
+        if (opts.uninstall) {
+          execSync("claude mcp remove recordings", { stdio: "pipe" });
+        } else {
+          try {
+            execSync("claude mcp remove recordings", { stdio: "pipe" });
+          } catch {}
+          execSync(`claude mcp add --transport stdio --scope user recordings -- ${mcpCmd}`, { stdio: "pipe" });
+        }
+        console.log(chalk.green(`${action} Claude Code (user scope in ~/.claude.json)`));
+      }
+      if (target === "codex") {
+        const configPath = pathJoin(home, ".codex", "config.toml");
+        if (fileExists(configPath)) {
+          let content = readFileSync2(configPath, "utf-8");
+          if (opts.uninstall) {
+            content = content.replace(/\n\[mcp_servers\.recordings\]\ncommand = "[^"]*"\nargs = \[\]\n?/g, `
+`);
+          } else if (!content.includes("[mcp_servers.recordings]")) {
+            content += `
+[mcp_servers.recordings]
+command = "${mcpCmd}"
+args = []
+`;
+          }
+          writeFileSync(configPath, content, "utf-8");
+          console.log(chalk.green(`${action} Codex: ${configPath}`));
+        } else {
+          console.log(chalk.yellow(`Codex config not found: ${configPath}`));
+        }
+      }
+      if (target === "gemini") {
+        const configPath = pathJoin(home, ".gemini", "settings.json");
+        let config = {};
+        if (fileExists(configPath)) {
+          config = JSON.parse(readFileSync2(configPath, "utf-8"));
+        }
+        const servers = config["mcpServers"] || {};
+        if (opts.uninstall) {
+          delete servers["recordings"];
+        } else {
+          servers["recordings"] = { command: mcpCmd, args: [] };
+        }
+        config["mcpServers"] = servers;
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + `
+`, "utf-8");
+        console.log(chalk.green(`${action} Gemini: ${configPath}`));
+      }
+    } catch (e) {
+      console.error(chalk.red(`Failed for ${target}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+  }
+});
+program.parse();