mastracode 0.3.0 → 0.4.0

package/dist/cli.cjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 
-var chunkVZFPT5N7_cjs = require('./chunk-VZFPT5N7.cjs');
-var chunk7TFV3VBB_cjs = require('./chunk-7TFV3VBB.cjs');
-var chunk7K5VFY2N_cjs = require('./chunk-7K5VFY2N.cjs');
-var chunkC6XKRHRK_cjs = require('./chunk-C6XKRHRK.cjs');
+var chunkZ4QRXVST_cjs = require('./chunk-Z4QRXVST.cjs');
+var chunkC4X3C2DL_cjs = require('./chunk-C4X3C2DL.cjs');
+var chunkK4WJUBEC_cjs = require('./chunk-K4WJUBEC.cjs');
+var chunkS5ZLN7DR_cjs = require('./chunk-S5ZLN7DR.cjs');
 var fs = require('fs');
 var path = require('path');
 
@@ -40,7 +40,7 @@ process.on("unhandledRejection", (reason) => {
   handleFatalError(reason instanceof Error ? reason : new Error(String(reason)));
 });
 async function main() {
-  const result = await chunkVZFPT5N7_cjs.createMastraCode();
+  const result = await chunkZ4QRXVST_cjs.createMastraCode();
   harness = result.harness;
   mcpManager = result.mcpManager;
   hookManager = result.hookManager;
@@ -59,7 +59,7 @@ async function main() {
       console.info(`MCP: Failed to connect to "${s.name}": ${s.error}`);
     }
   }
-  const logFile = path__namespace.join(chunkC6XKRHRK_cjs.getAppDataDir(), "debug.log");
+  const logFile = path__namespace.join(chunkS5ZLN7DR_cjs.getAppDataDir(), "debug.log");
   const logStream = fs__namespace.createWriteStream(logFile, { flags: "a" });
   const fmt = (a) => {
     if (typeof a === "string") return a;
@@ -78,7 +78,17 @@ async function main() {
     logStream.write(`[WARN] ${(/* @__PURE__ */ new Date()).toISOString()} ${args.map(fmt).join(" ")}
 `);
   };
-  const tui = new chunk7TFV3VBB_cjs.MastraTUI({
+  const envTheme = process.env.MASTRA_THEME?.toLowerCase();
+  let themeMode;
+  if (envTheme === "dark" || envTheme === "light") {
+    themeMode = envTheme;
+  } else {
+    const settings = chunkK4WJUBEC_cjs.loadSettings();
+    const themePref = settings.preferences.theme;
+    themeMode = themePref === "dark" || themePref === "light" ? themePref : await chunkC4X3C2DL_cjs.detectTerminalTheme();
+  }
+  chunkK4WJUBEC_cjs.applyThemeMode(themeMode);
+  const tui = new chunkC4X3C2DL_cjs.MastraTUI({
     harness,
     hookManager,
     authStorage,
@@ -92,14 +102,14 @@ async function main() {
   });
 }
 var asyncCleanup = async () => {
-  chunk7K5VFY2N_cjs.releaseAllThreadLocks();
+  chunkK4WJUBEC_cjs.releaseAllThreadLocks();
   await Promise.allSettled([mcpManager?.disconnect(), harness?.stopHeartbeats()]);
 };
 process.on("beforeExit", () => {
   void asyncCleanup();
 });
 process.on("exit", () => {
-  chunk7K5VFY2N_cjs.releaseAllThreadLocks();
+  chunkK4WJUBEC_cjs.releaseAllThreadLocks();
 });
 process.on("SIGINT", () => {
   void asyncCleanup().finally(() => process.exit(0));
@@ -118,7 +128,7 @@ function hasEconnrefused(err, depth = 0) {
 function handleFatalError(error) {
   const write = (msg) => process.stderr.write(msg + "\n");
   if (hasEconnrefused(error)) {
-    const settings = chunk7K5VFY2N_cjs.loadSettings();
+    const settings = chunkK4WJUBEC_cjs.loadSettings();
     const connStr = settings.storage?.pg?.connectionString;
     const target = connStr ?? "localhost:5432";
     write(

package/dist/cli.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/main.ts"],"names":["createMastraCode","path","getAppDataDir","fs","MastraTUI","releaseAllThreadLocks","loadSettings"],"mappings":"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","file":"cli.cjs","sourcesContent":["#!/usr/bin/env node\n/**\n * Main entry point for Mastra Code TUI.\n */\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { loadSettings } from './onboarding/settings.js';\nimport { MastraTUI } from './tui/index.js';\nimport { getAppDataDir } from './utils/project.js';\nimport { releaseAllThreadLocks } from './utils/thread-lock.js';\nimport { createMastraCode } from './index.js';\n\nlet harness: Awaited<ReturnType<typeof createMastraCode>>['harness'];\nlet mcpManager: Awaited<ReturnType<typeof createMastraCode>>['mcpManager'];\nlet hookManager: Awaited<ReturnType<typeof createMastraCode>>['hookManager'];\nlet authStorage: Awaited<ReturnType<typeof createMastraCode>>['authStorage'];\n\n// Global safety nets — catch any uncaught errors from storage init, etc.\nprocess.on('uncaughtException', error => {\n  handleFatalError(error);\n});\nprocess.on('unhandledRejection', reason => {\n  handleFatalError(reason instanceof Error ? reason : new Error(String(reason)));\n});\n\nasync function main() {\n  const result = await createMastraCode();\n  harness = result.harness;\n  mcpManager = result.mcpManager;\n  hookManager = result.hookManager;\n  authStorage = result.authStorage;\n\n  if (result.storageWarning) {\n    console.info(`⚠ ${result.storageWarning}`);\n  }\n\n  if (mcpManager?.hasServers()) {\n    await mcpManager.init();\n    const statuses = mcpManager.getServerStatuses();\n    const connected = statuses.filter(s => s.connected);\n    const failed = statuses.filter(s => !s.connected);\n    const totalTools = connected.reduce((sum, s) => sum + s.toolCount, 0);\n    console.info(`MCP: ${connected.length} server(s) connected, ${totalTools} tool(s)`);\n    for (const s of failed) {\n      console.info(`MCP: Failed to connect to \"${s.name}\": ${s.error}`);\n    }\n  }\n\n  const logFile = path.join(getAppDataDir(), 'debug.log');\n  const logStream = fs.createWriteStream(logFile, { flags: 'a' });\n  const fmt = (a: unknown): string => {\n    if (typeof a === 'string') return a;\n    if (a instanceof Error) return `${a.name}: ${a.message}`;\n    try {\n      return JSON.stringify(a);\n    } catch {\n      return String(a);\n    }\n  };\n  console.error = (...args: unknown[]) => {\n    logStream.write(`[ERROR] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n  console.warn = (...args: unknown[]) => {\n    logStream.write(`[WARN] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n\n  const tui = new MastraTUI({\n    harness,\n    hookManager,\n    authStorage,\n    mcpManager,\n    appName: 'Mastra Code',\n    version: '0.1.0',\n    inlineQuestions: true,\n  });\n\n  tui.run().catch(error => {\n    handleFatalError(error);\n  });\n}\n\nconst asyncCleanup = async () => {\n  releaseAllThreadLocks();\n  await Promise.allSettled([mcpManager?.disconnect(), harness?.stopHeartbeats()]);\n};\n\nprocess.on('beforeExit', () => {\n  void asyncCleanup();\n});\nprocess.on('exit', () => {\n  releaseAllThreadLocks();\n});\nprocess.on('SIGINT', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\nprocess.on('SIGTERM', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\n\nfunction hasEconnrefused(err: unknown, depth = 0): boolean {\n  if (!err || depth > 5) return false;\n  const e = err as any;\n  if (e.code === 'ECONNREFUSED') return true;\n  if (e.cause) return hasEconnrefused(e.cause, depth + 1);\n  // AggregateError has .errors array\n  if (Array.isArray(e.errors)) return e.errors.some((inner: unknown) => hasEconnrefused(inner, depth + 1));\n  return false;\n}\n\nfunction handleFatalError(error: unknown): never {\n  // Always write to real stderr, even if console.error was overridden\n  const write = (msg: string) => process.stderr.write(msg + '\\n');\n\n  if (hasEconnrefused(error)) {\n    const settings = loadSettings();\n    const connStr = settings.storage?.pg?.connectionString;\n    const target = connStr ?? 'localhost:5432';\n    write(\n      `\\nFailed to connect to PostgreSQL at ${target}.` +\n        `\\nMake sure the database is running and accessible.` +\n        `\\n\\nTo switch back to LibSQL:` +\n        `\\n  Set MASTRA_STORAGE_BACKEND=libsql or change the backend in /settings\\n`,\n    );\n    process.exit(1);\n  }\n\n  write(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n\nmain().catch(error => {\n  handleFatalError(error);\n});\n"]}
+{"version":3,"sources":["../src/main.ts"],"names":["createMastraCode","path","getAppDataDir","fs","loadSettings","detectTerminalTheme","applyThemeMode","MastraTUI","releaseAllThreadLocks"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeA,IAAI,OAAA;AACJ,IAAI,UAAA;AACJ,IAAI,WAAA;AACJ,IAAI,WAAA;AAGJ,OAAA,CAAQ,EAAA,CAAG,qBAAqB,CAAA,KAAA,KAAS;AACvC,EAAA,gBAAA,CAAiB,KAAK,CAAA;AACxB,CAAC,CAAA;AACD,OAAA,CAAQ,EAAA,CAAG,sBAAsB,CAAA,MAAA,KAAU;AACzC,EAAA,gBAAA,CAAiB,MAAA,YAAkB,QAAQ,MAAA,GAAS,IAAI,MAAM,MAAA,CAAO,MAAM,CAAC,CAAC,CAAA;AAC/E,CAAC,CAAA;AAED,eAAe,IAAA,GAAO;AACpB,EAAA,MAAM,MAAA,GAAS,MAAMA,kCAAA,EAAiB;AACtC,EAAA,OAAA,GAAU,MAAA,CAAO,OAAA;AACjB,EAAA,UAAA,GAAa,MAAA,CAAO,UAAA;AACpB,EAAA,WAAA,GAAc,MAAA,CAAO,WAAA;AACrB,EAAA,WAAA,GAAc,MAAA,CAAO,WAAA;AAErB,EAAA,IAAI,OAAO,cAAA,EAAgB;AACzB,IAAA,OAAA,CAAQ,IAAA,CAAK,CAAA,OAAA,EAAK,MAAA,CAAO,cAAc,CAAA,CAAE,CAAA;AAAA,EAC3C;AAEA,EAAA,IAAI,UAAA,EAAY,YAAW,EAAG;AAC5B,IAAA,MAAM,WAAW,IAAA,EAAK;AACtB,IAAA,MAAM,QAAA,GAAW,WAAW,iBAAA,EAAkB;AAC9C,IAAA,MAAM,SAAA,GAAY,QAAA,CAAS,MAAA,CAAO,CAAA,CAAA,KAAK,EAAE,SAAS,CAAA;AAClD,IAAA,MAAM,SAAS,QAAA,CAAS,MAAA,CAAO,CAAA,CAAA,KAAK,CAAC,EAAE,SAAS,CAAA;AAChD,IAAA,MAAM,UAAA,GAAa,UAAU,MAAA,CAAO,CAAC,KAAK,CAAA,KAAM,GAAA,GAAM,CAAA,CAAE,SAAA,EAAW,CAAC,CAAA;AACpE,IAAA,OAAA,CAAQ,KAAK,CAAA,KAAA,EAAQ,SAAA,CAAU,MAAM,CAAA,sBAAA,EAAyB,UAAU,CAAA,QAAA,CAAU,CAAA;AAClF,IAAA,KAAA,MAAW,KAAK,MAAA,EAAQ;AACtB,MAAA,OAAA,CAAQ,KAAK,CAAA,2BAAA,EAA8B,CAAA,CAAE,IAAI,CAAA,GAAA,EAAM,CAAA,CAAE,KAAK,CAAA,CAAE,CAAA;AAAA,IAClE;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAeC,eAAA,CAAA,IAAA,CAAKC,+BAAA,EAAc,EAAG,WAAW,CAAA;AACtD,EAAA,MAAM,YAAeC,aAAA,CAAA,iBAAA,CAAkB,OAAA,EAAS,EAAE,KAAA,EAAO,KAAK,CAAA;AAC9D,EAAA,MAAM,GAAA,GAAM,CAAC,CAAA,KAAuB;AAClC,IAAA,IAAI,OAAO,CAAA,KAAM,QAAA,EAAU,OAAO,CAAA;AAClC,IAAA,IAAI,CAAA,YAAa,OAAO,OAAO,CAAA,EAAG,EAAE,IAAI,CAAA,EAAA,EAAK,EAAE,OAAO,CAAA,CAAA;AACtD,IAAA,IAAI;AACF,MAAA,OAAO,IAAA,CAAK,UAAU,CAAC,CAAA;AAAA,IACzB,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,OAAO,CAAC,CAAA;AAAA,IACjB;AAAA,EACF,CAAA;AACA,EAAA,OAAA,CAAQ,KAAA,GAAQ,IAAI,IAAA,KAAoB;AACtC,IAAA,SAAA,CAAU,KAAA,CAAM,CAAA,QAAA,EAAA,iBAAW,IAAI,IAAA,IAAO,WAAA,EAAa,CAAA,CAAA,EAAI,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,CAAE,IAAA,CAAK,GAAG,CAAC;AAAA,CAAI,CAAA;AAAA,EACpF,CAAA;AACA,EAAA,OAAA,CAAQ,IAAA,GAAO,IAAI,IAAA,KAAoB;AACrC,IAAA,SAAA,CAAU,KAAA,CAAM,CAAA,OAAA,EAAA,iBAAU,IAAI,IAAA,IAAO,WAAA,EAAa,CAAA,CAAA,EAAI,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,CAAE,IAAA,CAAK,GAAG,CAAC;AAAA,CAAI,CAAA;AAAA,EACnF,CAAA;AAIA,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,GAAA,CAAI,YAAA,EAAc,WAAA,EAAY;AACvD,EAAA,IAAI,SAAA;AACJ,EAAA,IAAI,QAAA,KAAa,MAAA,IAAU,QAAA,KAAa,OAAA,EAAS;AAC/C,IAAA,SAAA,GAAY,QAAA;AAAA,EACd,CAAA,MAAO;AACL,IAAA,MAAM,WAAWC,8BAAA,EAAa;AAC9B,IAAA,MAAM,SAAA,GAAY,SAAS,WAAA,CAAY,KAAA;AACvC,IAAA,SAAA,GAAY,cAAc,MAAA,IAAU,SAAA,KAAc,OAAA,GAAU,SAAA,GAAY,MAAMC,qCAAA,EAAoB;AAAA,EACpG;AACA,EAAAC,gCAAA,CAAe,SAAS,CAAA;AAExB,EAAA,MAAM,GAAA,GAAM,IAAIC,2BAAA,CAAU;AAAA,IACxB,OAAA;AAAA,IACA,WAAA;AAAA,IACA,WAAA;AAAA,IACA,UAAA;AAAA,IACA,OAAA,EAAS,aAAA;AAAA,IACT,OAAA,EAAS,OAAA;AAAA,IACT,eAAA,EAAiB;AAAA,GAClB,CAAA;AAED,EAAA,GAAA,CAAI,GAAA,EAAI,CAAE,KAAA,CAAM,CAAA,KAAA,KAAS;AACvB,IAAA,gBAAA,CAAiB,KAAK,CAAA;AAAA,EACxB,CAAC,CAAA;AACH;AAEA,IAAM,eAAe,YAAY;AAC/B,EAAAC,uCAAA,EAAsB;AACtB,EAAA,MAAM,OAAA,CAAQ,WAAW,CAAC,UAAA,EAAY,YAAW,EAAG,OAAA,EAAS,cAAA,EAAgB,CAAC,CAAA;AAChF,CAAA;AAEA,OAAA,CAAQ,EAAA,CAAG,cAAc,MAAM;AAC7B,EAAA,KAAK,YAAA,EAAa;AACpB,CAAC,CAAA;AACD,OAAA,CAAQ,EAAA,CAAG,QAAQ,MAAM;AACvB,EAAAA,uCAAA,EAAsB;AACxB,CAAC,CAAA;AACD,OAAA,CAAQ,EAAA,CAAG,UAAU,MAAM;AACzB,EAAA,KAAK,cAAa,CAAE,OAAA,CAAQ,MAAM,OAAA,CAAQ,IAAA,CAAK,CAAC,CAAC,CAAA;AACnD,CAAC,CAAA;AACD,OAAA,CAAQ,EAAA,CAAG,WAAW,MAAM;AAC1B,EAAA,KAAK,cAAa,CAAE,OAAA,CAAQ,MAAM,OAAA,CAAQ,IAAA,CAAK,CAAC,CAAC,CAAA;AACnD,CAAC,CAAA;AAED,SAAS,eAAA,CAAgB,GAAA,EAAc,KAAA,GAAQ,CAAA,EAAY;AACzD,EAAA,IAAI,CAAC,GAAA,IAAO,KAAA,GAAQ,CAAA,EAAG,OAAO,KAAA;AAC9B,EAAA,MAAM,CAAA,GAAI,GAAA;AACV,EAAA,IAAI,CAAA,CAAE,IAAA,KAAS,cAAA,EAAgB,OAAO,IAAA;AACtC,EAAA,IAAI,EAAE,KAAA,EAAO,OAAO,gBAAgB,CAAA,CAAE,KAAA,EAAO,QAAQ,CAAC,CAAA;AAEtD,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,MAAM,GAAG,OAAO,CAAA,CAAE,MAAA,CAAO,IAAA,CAAK,CAAC,KAAA,KAAmB,eAAA,CAAgB,KAAA,EAAO,KAAA,GAAQ,CAAC,CAAC,CAAA;AACvG,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,iBAAiB,KAAA,EAAuB;AAE/C,EAAA,MAAM,QAAQ,CAAC,GAAA,KAAgB,QAAQ,MAAA,CAAO,KAAA,CAAM,MAAM,IAAI,CAAA;AAE9D,EAAA,IAAI,eAAA,CAAgB,KAAK,CAAA,EAAG;AAC1B,IAAA,MAAM,WAAWJ,8BAAA,EAAa;AAC9B,IAAA,MAAM,OAAA,GAAU,QAAA,CAAS,OAAA,EAAS,EAAA,EAAI,gBAAA;AACtC,IAAA,MAAM,SAAS,OAAA,IAAW,gBAAA;AAC1B,IAAA,KAAA;AAAA,MACE;AAAA,mCAAA,EAAwC,MAAM,CAAA;AAAA;;AAAA;AAAA;AAAA;AAAA,KAIhD;AACA,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAEA,EAAA,KAAA,CAAM,CAAA,aAAA,EAAgB,iBAAiB,KAAA,GAAQ,KAAA,CAAM,UAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAE,CAAA;AAC9E,EAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAChB;AAEA,IAAA,EAAK,CAAE,MAAM,CAAA,KAAA,KAAS;AACpB,EAAA,gBAAA,CAAiB,KAAK,CAAA;AACxB,CAAC,CAAA","file":"cli.cjs","sourcesContent":["#!/usr/bin/env node\n/**\n * Main entry point for Mastra Code TUI.\n */\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { loadSettings } from './onboarding/settings.js';\nimport { detectTerminalTheme } from './tui/detect-theme.js';\nimport { MastraTUI } from './tui/index.js';\nimport { applyThemeMode } from './tui/theme.js';\nimport { getAppDataDir } from './utils/project.js';\nimport { releaseAllThreadLocks } from './utils/thread-lock.js';\nimport { createMastraCode } from './index.js';\n\nlet harness: Awaited<ReturnType<typeof createMastraCode>>['harness'];\nlet mcpManager: Awaited<ReturnType<typeof createMastraCode>>['mcpManager'];\nlet hookManager: Awaited<ReturnType<typeof createMastraCode>>['hookManager'];\nlet authStorage: Awaited<ReturnType<typeof createMastraCode>>['authStorage'];\n\n// Global safety nets — catch any uncaught errors from storage init, etc.\nprocess.on('uncaughtException', error => {\n  handleFatalError(error);\n});\nprocess.on('unhandledRejection', reason => {\n  handleFatalError(reason instanceof Error ? reason : new Error(String(reason)));\n});\n\nasync function main() {\n  const result = await createMastraCode();\n  harness = result.harness;\n  mcpManager = result.mcpManager;\n  hookManager = result.hookManager;\n  authStorage = result.authStorage;\n\n  if (result.storageWarning) {\n    console.info(`⚠ ${result.storageWarning}`);\n  }\n\n  if (mcpManager?.hasServers()) {\n    await mcpManager.init();\n    const statuses = mcpManager.getServerStatuses();\n    const connected = statuses.filter(s => s.connected);\n    const failed = statuses.filter(s => !s.connected);\n    const totalTools = connected.reduce((sum, s) => sum + s.toolCount, 0);\n    console.info(`MCP: ${connected.length} server(s) connected, ${totalTools} tool(s)`);\n    for (const s of failed) {\n      console.info(`MCP: Failed to connect to \"${s.name}\": ${s.error}`);\n    }\n  }\n\n  const logFile = path.join(getAppDataDir(), 'debug.log');\n  const logStream = fs.createWriteStream(logFile, { flags: 'a' });\n  const fmt = (a: unknown): string => {\n    if (typeof a === 'string') return a;\n    if (a instanceof Error) return `${a.name}: ${a.message}`;\n    try {\n      return JSON.stringify(a);\n    } catch {\n      return String(a);\n    }\n  };\n  console.error = (...args: unknown[]) => {\n    logStream.write(`[ERROR] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n  console.warn = (...args: unknown[]) => {\n    logStream.write(`[WARN] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n\n  // Detect and apply terminal theme\n  // MASTRA_THEME env var is the highest-priority override\n  const envTheme = process.env.MASTRA_THEME?.toLowerCase();\n  let themeMode: 'dark' | 'light';\n  if (envTheme === 'dark' || envTheme === 'light') {\n    themeMode = envTheme;\n  } else {\n    const settings = loadSettings();\n    const themePref = settings.preferences.theme;\n    themeMode = themePref === 'dark' || themePref === 'light' ? themePref : await detectTerminalTheme();\n  }\n  applyThemeMode(themeMode);\n\n  const tui = new MastraTUI({\n    harness,\n    hookManager,\n    authStorage,\n    mcpManager,\n    appName: 'Mastra Code',\n    version: '0.1.0',\n    inlineQuestions: true,\n  });\n\n  tui.run().catch(error => {\n    handleFatalError(error);\n  });\n}\n\nconst asyncCleanup = async () => {\n  releaseAllThreadLocks();\n  await Promise.allSettled([mcpManager?.disconnect(), harness?.stopHeartbeats()]);\n};\n\nprocess.on('beforeExit', () => {\n  void asyncCleanup();\n});\nprocess.on('exit', () => {\n  releaseAllThreadLocks();\n});\nprocess.on('SIGINT', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\nprocess.on('SIGTERM', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\n\nfunction hasEconnrefused(err: unknown, depth = 0): boolean {\n  if (!err || depth > 5) return false;\n  const e = err as any;\n  if (e.code === 'ECONNREFUSED') return true;\n  if (e.cause) return hasEconnrefused(e.cause, depth + 1);\n  // AggregateError has .errors array\n  if (Array.isArray(e.errors)) return e.errors.some((inner: unknown) => hasEconnrefused(inner, depth + 1));\n  return false;\n}\n\nfunction handleFatalError(error: unknown): never {\n  // Always write to real stderr, even if console.error was overridden\n  const write = (msg: string) => process.stderr.write(msg + '\\n');\n\n  if (hasEconnrefused(error)) {\n    const settings = loadSettings();\n    const connStr = settings.storage?.pg?.connectionString;\n    const target = connStr ?? 'localhost:5432';\n    write(\n      `\\nFailed to connect to PostgreSQL at ${target}.` +\n        `\\nMake sure the database is running and accessible.` +\n        `\\n\\nTo switch back to LibSQL:` +\n        `\\n  Set MASTRA_STORAGE_BACKEND=libsql or change the backend in /settings\\n`,\n    );\n    process.exit(1);\n  }\n\n  write(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n\nmain().catch(error => {\n  handleFatalError(error);\n});\n"]}

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { createMastraCode } from './chunk-HHX6BKLR.js';
-import { MastraTUI } from './chunk-LYETHS2L.js';
-import { releaseAllThreadLocks, loadSettings } from './chunk-V4HZ2AVV.js';
-import { getAppDataDir } from './chunk-VRZZSUQE.js';
+import { createMastraCode } from './chunk-M5LKPQB4.js';
+import { detectTerminalTheme, MastraTUI } from './chunk-X3BGE7CL.js';
+import { releaseAllThreadLocks, loadSettings, applyThemeMode } from './chunk-REVOTI2T.js';
+import { getAppDataDir } from './chunk-SM3QCOA7.js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -55,6 +55,16 @@ async function main() {
     logStream.write(`[WARN] ${(/* @__PURE__ */ new Date()).toISOString()} ${args.map(fmt).join(" ")}
 `);
   };
+  const envTheme = process.env.MASTRA_THEME?.toLowerCase();
+  let themeMode;
+  if (envTheme === "dark" || envTheme === "light") {
+    themeMode = envTheme;
+  } else {
+    const settings = loadSettings();
+    const themePref = settings.preferences.theme;
+    themeMode = themePref === "dark" || themePref === "light" ? themePref : await detectTerminalTheme();
+  }
+  applyThemeMode(themeMode);
   const tui = new MastraTUI({
     harness,
     hookManager,

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/main.ts"],"names":[],"mappings":"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","file":"cli.js","sourcesContent":["#!/usr/bin/env node\n/**\n * Main entry point for Mastra Code TUI.\n */\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { loadSettings } from './onboarding/settings.js';\nimport { MastraTUI } from './tui/index.js';\nimport { getAppDataDir } from './utils/project.js';\nimport { releaseAllThreadLocks } from './utils/thread-lock.js';\nimport { createMastraCode } from './index.js';\n\nlet harness: Awaited<ReturnType<typeof createMastraCode>>['harness'];\nlet mcpManager: Awaited<ReturnType<typeof createMastraCode>>['mcpManager'];\nlet hookManager: Awaited<ReturnType<typeof createMastraCode>>['hookManager'];\nlet authStorage: Awaited<ReturnType<typeof createMastraCode>>['authStorage'];\n\n// Global safety nets — catch any uncaught errors from storage init, etc.\nprocess.on('uncaughtException', error => {\n  handleFatalError(error);\n});\nprocess.on('unhandledRejection', reason => {\n  handleFatalError(reason instanceof Error ? reason : new Error(String(reason)));\n});\n\nasync function main() {\n  const result = await createMastraCode();\n  harness = result.harness;\n  mcpManager = result.mcpManager;\n  hookManager = result.hookManager;\n  authStorage = result.authStorage;\n\n  if (result.storageWarning) {\n    console.info(`⚠ ${result.storageWarning}`);\n  }\n\n  if (mcpManager?.hasServers()) {\n    await mcpManager.init();\n    const statuses = mcpManager.getServerStatuses();\n    const connected = statuses.filter(s => s.connected);\n    const failed = statuses.filter(s => !s.connected);\n    const totalTools = connected.reduce((sum, s) => sum + s.toolCount, 0);\n    console.info(`MCP: ${connected.length} server(s) connected, ${totalTools} tool(s)`);\n    for (const s of failed) {\n      console.info(`MCP: Failed to connect to \"${s.name}\": ${s.error}`);\n    }\n  }\n\n  const logFile = path.join(getAppDataDir(), 'debug.log');\n  const logStream = fs.createWriteStream(logFile, { flags: 'a' });\n  const fmt = (a: unknown): string => {\n    if (typeof a === 'string') return a;\n    if (a instanceof Error) return `${a.name}: ${a.message}`;\n    try {\n      return JSON.stringify(a);\n    } catch {\n      return String(a);\n    }\n  };\n  console.error = (...args: unknown[]) => {\n    logStream.write(`[ERROR] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n  console.warn = (...args: unknown[]) => {\n    logStream.write(`[WARN] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n\n  const tui = new MastraTUI({\n    harness,\n    hookManager,\n    authStorage,\n    mcpManager,\n    appName: 'Mastra Code',\n    version: '0.1.0',\n    inlineQuestions: true,\n  });\n\n  tui.run().catch(error => {\n    handleFatalError(error);\n  });\n}\n\nconst asyncCleanup = async () => {\n  releaseAllThreadLocks();\n  await Promise.allSettled([mcpManager?.disconnect(), harness?.stopHeartbeats()]);\n};\n\nprocess.on('beforeExit', () => {\n  void asyncCleanup();\n});\nprocess.on('exit', () => {\n  releaseAllThreadLocks();\n});\nprocess.on('SIGINT', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\nprocess.on('SIGTERM', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\n\nfunction hasEconnrefused(err: unknown, depth = 0): boolean {\n  if (!err || depth > 5) return false;\n  const e = err as any;\n  if (e.code === 'ECONNREFUSED') return true;\n  if (e.cause) return hasEconnrefused(e.cause, depth + 1);\n  // AggregateError has .errors array\n  if (Array.isArray(e.errors)) return e.errors.some((inner: unknown) => hasEconnrefused(inner, depth + 1));\n  return false;\n}\n\nfunction handleFatalError(error: unknown): never {\n  // Always write to real stderr, even if console.error was overridden\n  const write = (msg: string) => process.stderr.write(msg + '\\n');\n\n  if (hasEconnrefused(error)) {\n    const settings = loadSettings();\n    const connStr = settings.storage?.pg?.connectionString;\n    const target = connStr ?? 'localhost:5432';\n    write(\n      `\\nFailed to connect to PostgreSQL at ${target}.` +\n        `\\nMake sure the database is running and accessible.` +\n        `\\n\\nTo switch back to LibSQL:` +\n        `\\n  Set MASTRA_STORAGE_BACKEND=libsql or change the backend in /settings\\n`,\n    );\n    process.exit(1);\n  }\n\n  write(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n\nmain().catch(error => {\n  handleFatalError(error);\n});\n"]}
+{"version":3,"sources":["../src/main.ts"],"names":[],"mappings":"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","file":"cli.js","sourcesContent":["#!/usr/bin/env node\n/**\n * Main entry point for Mastra Code TUI.\n */\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { loadSettings } from './onboarding/settings.js';\nimport { detectTerminalTheme } from './tui/detect-theme.js';\nimport { MastraTUI } from './tui/index.js';\nimport { applyThemeMode } from './tui/theme.js';\nimport { getAppDataDir } from './utils/project.js';\nimport { releaseAllThreadLocks } from './utils/thread-lock.js';\nimport { createMastraCode } from './index.js';\n\nlet harness: Awaited<ReturnType<typeof createMastraCode>>['harness'];\nlet mcpManager: Awaited<ReturnType<typeof createMastraCode>>['mcpManager'];\nlet hookManager: Awaited<ReturnType<typeof createMastraCode>>['hookManager'];\nlet authStorage: Awaited<ReturnType<typeof createMastraCode>>['authStorage'];\n\n// Global safety nets — catch any uncaught errors from storage init, etc.\nprocess.on('uncaughtException', error => {\n  handleFatalError(error);\n});\nprocess.on('unhandledRejection', reason => {\n  handleFatalError(reason instanceof Error ? reason : new Error(String(reason)));\n});\n\nasync function main() {\n  const result = await createMastraCode();\n  harness = result.harness;\n  mcpManager = result.mcpManager;\n  hookManager = result.hookManager;\n  authStorage = result.authStorage;\n\n  if (result.storageWarning) {\n    console.info(`⚠ ${result.storageWarning}`);\n  }\n\n  if (mcpManager?.hasServers()) {\n    await mcpManager.init();\n    const statuses = mcpManager.getServerStatuses();\n    const connected = statuses.filter(s => s.connected);\n    const failed = statuses.filter(s => !s.connected);\n    const totalTools = connected.reduce((sum, s) => sum + s.toolCount, 0);\n    console.info(`MCP: ${connected.length} server(s) connected, ${totalTools} tool(s)`);\n    for (const s of failed) {\n      console.info(`MCP: Failed to connect to \"${s.name}\": ${s.error}`);\n    }\n  }\n\n  const logFile = path.join(getAppDataDir(), 'debug.log');\n  const logStream = fs.createWriteStream(logFile, { flags: 'a' });\n  const fmt = (a: unknown): string => {\n    if (typeof a === 'string') return a;\n    if (a instanceof Error) return `${a.name}: ${a.message}`;\n    try {\n      return JSON.stringify(a);\n    } catch {\n      return String(a);\n    }\n  };\n  console.error = (...args: unknown[]) => {\n    logStream.write(`[ERROR] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n  console.warn = (...args: unknown[]) => {\n    logStream.write(`[WARN] ${new Date().toISOString()} ${args.map(fmt).join(' ')}\\n`);\n  };\n\n  // Detect and apply terminal theme\n  // MASTRA_THEME env var is the highest-priority override\n  const envTheme = process.env.MASTRA_THEME?.toLowerCase();\n  let themeMode: 'dark' | 'light';\n  if (envTheme === 'dark' || envTheme === 'light') {\n    themeMode = envTheme;\n  } else {\n    const settings = loadSettings();\n    const themePref = settings.preferences.theme;\n    themeMode = themePref === 'dark' || themePref === 'light' ? themePref : await detectTerminalTheme();\n  }\n  applyThemeMode(themeMode);\n\n  const tui = new MastraTUI({\n    harness,\n    hookManager,\n    authStorage,\n    mcpManager,\n    appName: 'Mastra Code',\n    version: '0.1.0',\n    inlineQuestions: true,\n  });\n\n  tui.run().catch(error => {\n    handleFatalError(error);\n  });\n}\n\nconst asyncCleanup = async () => {\n  releaseAllThreadLocks();\n  await Promise.allSettled([mcpManager?.disconnect(), harness?.stopHeartbeats()]);\n};\n\nprocess.on('beforeExit', () => {\n  void asyncCleanup();\n});\nprocess.on('exit', () => {\n  releaseAllThreadLocks();\n});\nprocess.on('SIGINT', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\nprocess.on('SIGTERM', () => {\n  void asyncCleanup().finally(() => process.exit(0));\n});\n\nfunction hasEconnrefused(err: unknown, depth = 0): boolean {\n  if (!err || depth > 5) return false;\n  const e = err as any;\n  if (e.code === 'ECONNREFUSED') return true;\n  if (e.cause) return hasEconnrefused(e.cause, depth + 1);\n  // AggregateError has .errors array\n  if (Array.isArray(e.errors)) return e.errors.some((inner: unknown) => hasEconnrefused(inner, depth + 1));\n  return false;\n}\n\nfunction handleFatalError(error: unknown): never {\n  // Always write to real stderr, even if console.error was overridden\n  const write = (msg: string) => process.stderr.write(msg + '\\n');\n\n  if (hasEconnrefused(error)) {\n    const settings = loadSettings();\n    const connStr = settings.storage?.pg?.connectionString;\n    const target = connStr ?? 'localhost:5432';\n    write(\n      `\\nFailed to connect to PostgreSQL at ${target}.` +\n        `\\nMake sure the database is running and accessible.` +\n        `\\n\\nTo switch back to LibSQL:` +\n        `\\n  Set MASTRA_STORAGE_BACKEND=libsql or change the backend in /settings\\n`,\n    );\n    process.exit(1);\n  }\n\n  write(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n\nmain().catch(error => {\n  handleFatalError(error);\n});\n"]}

package/dist/docs/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: mastracode
+description: Documentation for mastracode. Use when working with mastracode APIs, configuration, or implementation.
+metadata:
+  package: "mastracode"
+  version: "0.4.0"
+---
+
+## When to use
+
+Use this skill whenever you are working with mastracode to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Docs
+
+- [Configuration](references/docs-mastra-code-configuration.md) - Learn how to configure Mastra Code with authentication, MCP servers, hooks, custom commands, skills, storage backends (LibSQL and PostgreSQL), and environment variables.
+- [Customization](references/docs-mastra-code-customization.md) - Learn how to extend Mastra Code programmatically by creating custom modes, adding tools, defining subagents, and integrating with your own TUI.
+- [Modes](references/docs-mastra-code-modes.md) - Learn how Mastra Code's three operating modes — Build, Plan, and Fast — shape the agent's behavior, tool access, and response style.
+- [Mastra Code overview](references/docs-mastra-code-overview.md) - Mastra Code is a terminal-based AI coding agent built with Mastra. It provides multi-model support, persistent conversations, coding tools, and a polished TUI.
+- [Tools](references/docs-mastra-code-tools.md) - Learn about Mastra Code's built-in tools for file viewing, editing, search, shell execution, web search, and task management.
+
+### Reference
+
+- [Reference: createMastraCode()](references/reference-mastra-code-createMastraCode.md) - API reference for createMastraCode(), the factory function that initializes the Mastra Code coding agent with its harness, MCP manager, hooks, and auth.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.4.0",
+  "package": "mastracode",
+  "exports": {
+    "createMastraCode": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-M5LKPQB4.js"
+    }
+  },
+  "modules": {}
+}

package/dist/docs/references/docs-mastra-code-configuration.md

@@ -0,0 +1,299 @@
+# Configuration
+
+Mastra Code is configured through project-level files, global settings, and environment variables. Configuration files live in `.mastracode/` directories at the project and user levels.
+
+## Authentication
+
+Mastra Code supports two authentication methods: **API keys** (environment variables) and **OAuth** (provider subscriptions). You can use either or both.
+
+### API keys
+
+The simplest way to get started is to set API key environment variables for the providers you want to use. Mastra Code auto-detects these on startup:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export GOOGLE_GENERATIVE_AI_API_KEY=...
+export DEEPSEEK_API_KEY=...
+export CEREBRAS_API_KEY=...
+```
+
+Mastra Code uses Mastra's [model router](https://mastra.ai/models), which routes requests to the correct provider based on the model ID and available API keys. No OAuth login is required when using API keys.
+
+### OAuth login (optional)
+
+If you have an Anthropic Claude Max or OpenAI ChatGPT Plus subscription, you can authenticate via OAuth to use your subscription instead of API keys. Run `/login` in the TUI to start the flow.
+
+| Provider      | OAuth flow              | What you get                                  |
+| ------------- | ----------------------- | --------------------------------------------- |
+| **Anthropic** | Claude Max subscription | Access to Claude models via your subscription |
+| **OpenAI**    | ChatGPT Plus / Codex    | Access to OpenAI models via your subscription |
+
+OAuth credentials are stored in `auth.json` alongside the database in the [app data directory](#database-location). During onboarding, you can skip the OAuth step if you already have API keys configured.
+
+### Anthropic OAuth warning
+
+Authenticating with a Claude Max subscription through OAuth is a grey area. Anthropic has reportedly banned users for using Claude max credentials outside of Claude Code, so it may violate Anthropic Terms of Service.
+
+## MCP servers
+
+Mastra Code can connect to external [MCP](https://mastra.ai/docs/mcp/overview) servers and make their tools available to the agent. Configure servers in JSON files:
+
+| Priority | Path                          | Scope                            |
+| -------- | ----------------------------- | -------------------------------- |
+| Highest  | `.mastracode/mcp.json`        | Project                          |
+|          | `~/.mastracode/mcp.json`      | Global                           |
+| Lowest   | `.claude/settings.local.json` | Project (Claude Code compatible) |
+
+Project config overrides global config by server name. Claude Code settings are the lowest priority fallback.
+
+### MCP config format
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server"],
+      "env": {
+        "API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+Each server entry requires a `command` field. The `args` and `env` fields are optional.
+
+On startup, Mastra Code connects to all configured servers and reports the status:
+
+```text
+MCP: 2 server(s) connected, 15 tool(s)
+```
+
+Tools from MCP servers are namespaced as `serverName_toolName` and appear in the agent's tool list alongside built-in tools.
+
+## Hooks
+
+Hooks are user-configured shell commands that run at specific lifecycle events. Use hooks for custom validation, logging, notifications, or integration with external systems.
+
+### Hook config format
+
+```json
+{
+  "PreToolUse": [
+    {
+      "type": "command",
+      "command": "node scripts/validate-tool.js",
+      "matcher": {
+        "tool_name": "execute_command"
+      },
+      "timeout": 5000,
+      "description": "Validate shell commands before execution"
+    }
+  ],
+  "PostToolUse": [
+    {
+      "type": "command",
+      "command": "node scripts/log-tool.js",
+      "description": "Log tool usage"
+    }
+  ]
+}
+```
+
+### Hook events
+
+| Event              | When it fires                                                   | Can block? |
+| ------------------ | --------------------------------------------------------------- | ---------- |
+| `PreToolUse`       | Before a tool call executes                                     | Yes        |
+| `PostToolUse`      | After a tool call completes                                     | No         |
+| `Stop`             | When an agent response ends (`complete`, `aborted`, or `error`) | Yes        |
+| `UserPromptSubmit` | When the user sends a message                                   | Yes        |
+| `SessionStart`     | When a session begins                                           | No         |
+| `SessionEnd`       | When a session ends                                             | No         |
+| `Notification`     | When the TUI fires a notification                               | No         |
+
+`UserPromptSubmit` runs before a non-command prompt is sent to the agent. If a hook blocks, the prompt is not sent.
+
+### Hook I/O protocol
+
+Hook processes receive a JSON payload on stdin with context about the event:
+
+```json
+{
+  "session_id": "thread-abc123",
+  "cwd": "/path/to/project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "execute_command",
+  "tool_input": { "command": "npm test" }
+}
+```
+
+For blocking events (`PreToolUse`, `Stop`, `UserPromptSubmit`), the hook can respond on stdout with a JSON object:
+
+```json
+{
+  "decision": "block",
+  "reason": "This command is not allowed"
+}
+```
+
+### Hook config locations
+
+| Priority | Path                       | Scope                           |
+| -------- | -------------------------- | ------------------------------- |
+| Higher   | `.mastracode/hooks.json`   | Project (appended after global) |
+| Lower    | `~/.mastracode/hooks.json` | Global (runs first)             |
+
+Global hooks run before project hooks. For the same event, all hooks execute in order.
+
+## Custom slash commands
+
+Define reusable prompt templates as markdown files. Mastra Code scans these directories for `.md` files:
+
+| Priority | Path                      | Scope                            |
+| -------- | ------------------------- | -------------------------------- |
+| Highest  | `.mastracode/commands/`   | Project                          |
+|          | `.claude/commands/`       | Project (Claude Code compatible) |
+|          | `~/.mastracode/commands/` | Global                           |
+| Lowest   | `~/.claude/commands/`     | Global (Claude Code compatible)  |
+
+Each command file can include YAML frontmatter with `name` and `description` fields:
+
+```yaml
+---
+name: review
+description: Review the current diff for issues
+---
+Review my current git diff. Look for bugs, security issues,
+and violations of the project's coding standards.
+```
+
+The filename (or directory structure) determines the command name. For example, `git/commit.md` becomes `/git:commit`.
+
+Commands support variables like `$ARGUMENTS` for positional args, `@filename` for file content injection, and `!command` for shell command output.
+
+## Skills
+
+Skills are structured instruction files that the agent loads automatically based on trigger conditions. They provide domain-specific guidance without manually pasting instructions.
+
+Mastra Code scans these directories for skills:
+
+| Priority | Path                    | Scope                            |
+| -------- | ----------------------- | -------------------------------- |
+| Highest  | `.mastracode/skills/`   | Project                          |
+|          | `.claude/skills/`       | Project (Claude Code compatible) |
+|          | `~/.mastracode/skills/` | Global                           |
+| Lowest   | `~/.claude/skills/`     | Global (Claude Code compatible)  |
+
+Each skill is a directory containing a `SKILL.md` file with instructions and trigger descriptions. Skills installed via symlinks (e.g., from `npx skills add`) are automatically resolved.
+
+## Agent instructions
+
+Mastra Code loads project-specific instructions from `AGENTS.md` or `CLAUDE.md` files and injects them into the agent's system prompt. This is how you can customize the agent's behavior for your project.
+
+### Lookup order
+
+For project instructions (first match wins):
+
+1. `AGENTS.md` or `CLAUDE.md` in the project root
+2. `.claude/AGENTS.md` or `.claude/CLAUDE.md`
+3. `.mastracode/AGENTS.md` or `.mastracode/CLAUDE.md`
+
+For global instructions (first match wins):
+
+1. `~/.claude/AGENTS.md` or `~/.claude/CLAUDE.md`
+2. `~/.mastracode/AGENTS.md` or `~/.mastracode/CLAUDE.md`
+3. `~/.config/claude/AGENTS.md` or `~/.config/claude/CLAUDE.md`
+4. `~/.config/mastracode/AGENTS.md` or `~/.config/mastracode/CLAUDE.md`
+
+`AGENTS.md` takes priority over `CLAUDE.md` when both exist at the same location.
+
+## Storage
+
+Mastra Code stores threads, messages, state, and observational memory in a database. It uses LibSQL by default with a local file — no setup needed.
+
+To switch to a remote LibSQL (Turso) or PostgreSQL backend, run `/settings` and select a storage backend. You'll be prompted for a connection URL.
+
+If a PostgreSQL connection fails on startup, Mastra Code falls back to LibSQL and shows a warning so you can fix the connection via `/settings`.
+
+## Observational memory
+
+[Observational memory](https://mastra.ai/docs/memory/observational-memory) (OM) uses background agents to maintain a dense log of observations and reflections about the conversation, providing long-term context that persists across sessions.
+
+### OM scope
+
+Control whether observations are scoped to individual threads or shared across all threads for a project:
+
+| Scope              | Behavior                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| `thread` (default) | Observations are private to each conversation thread            |
+| `resource`         | Observations are shared across all threads for the same project |
+
+Configure the scope through:
+
+1. `MASTRA_OM_SCOPE` environment variable (`"thread"` or `"resource"`)
+2. `.mastracode/database.json` → `omScope` field
+3. `~/.mastracode/database.json` → `omScope` field
+
+### OM model settings
+
+The observer and reflector models default to `google/gemini-2.5-flash`. Override them per-thread through the `/settings` panel or in the harness state.
+
+### OM thresholds
+
+| Threshold             | Default       | Description                                   |
+| --------------------- | ------------- | --------------------------------------------- |
+| Observation threshold | 30,000 tokens | Token count that triggers an observation pass |
+| Reflection threshold  | 40,000 tokens | Token count that triggers a reflection pass   |
+
+## Color theme
+
+Mastra Code detects your terminal's color scheme and applies a matching dark or light theme. You can override the detected theme with the `/theme` slash command or the `MASTRA_THEME` environment variable.
+
+### Detection order
+
+1. `MASTRA_THEME` environment variable — explicit `dark` or `light`
+2. Persisted setting from `/theme` command (stored in `settings.json`)
+3. OSC 11 query — asks your terminal for its actual background color
+4. `COLORFGBG` environment variable (set by some terminals like iTerm2 and Konsole)
+5. Falls back to dark theme
+
+### Switching themes
+
+Use the `/theme` command to change the theme at runtime:
+
+```text
+/theme light
+/theme dark
+/theme auto
+```
+
+Running `/theme` with no arguments shows the current theme. The choice is persisted across sessions.
+
+## Environment variables
+
+| Variable               | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `MASTRA_DB_URL`        | LibSQL database URL (e.g., `libsql://...` or `file:./data.db`) |
+| `MASTRA_DB_AUTH_TOKEN` | Auth token for remote LibSQL database                          |
+| `MASTRA_DB_PATH`       | Override the local database file path                          |
+| `MASTRA_USER_ID`       | Override the auto-detected user identity                       |
+| `MASTRA_RESOURCE_ID`   | Override the auto-detected project resource ID                 |
+| `MASTRA_OM_SCOPE`      | Observational memory scope (`thread` or `resource`)            |
+| `DEFAULT_OM_MODEL_ID`  | Default model for OM observer and reflector                    |
+| `MASTRA_THEME`         | Color theme override (`dark` or `light`)                       |
+| `TAVILY_API_KEY`       | Enable Tavily-powered web search and extract tools             |
+
+## Resource ID override
+
+Resource IDs determine how threads are grouped. By default, Mastra Code generates one from the Git remote URL or filesystem path. Override it to share threads across repositories or isolate threads within a monorepo:
+
+```json
+{
+  "resourceId": "my-custom-project-id"
+}
+```
+
+You can also set `MASTRA_RESOURCE_ID` as an environment variable. Two users who set the same resource ID share threads and observations for that resource.