feat: MAGIC_CONTEXT_LOG_PATH env override for the diagnostic log (cortexkit#183)

Let users redirect the diagnostic log away from the harness temp-dir default,
which matters in sandboxed/ephemeral setups (Docker, CI) where TMPDIR is
disposable or the plugin and dashboard need to agree on a shared path. The
override is read at the single chokepoint getMagicContextLogPath (TS) and its
Rust mirror resolve_log_path_for, so both the plugin logger and the dashboard
log tail honor it; blank/whitespace is treated as unset. Docs updated in three
places.

Reimplemented from @kecsap's PR cortexkit#183 onto current master (the PR branch
predated the v0.30.2 WebSocket migration and carried a large stale revert).
Co-authored-by: kecsap <kecsap@users.noreply.github.com>

Author: KorenKrita

README.md

@@ -280,7 +280,7 @@ Magic Context also writes to a few other locations:
 |---|---|---|
 | `~/.local/share/cortexkit/magic-context/context.db` | SQLite database — tags, compartments, memories, all durable state (XDG-equivalent on Windows) | **Must persist.** Losing it loses your memory/history. |
 | `~/.local/share/cortexkit/magic-context/models/` | Local embedding model cache (~90 MB `Xenova/all-MiniLM-L6-v2` ONNX), downloaded on first use when local embeddings are enabled | Should persist, else re-downloaded each run. Not used when `memory.enabled: false` or an `openai_compatible`/`ollama` embedding backend is configured. |
-| `${TMPDIR}/opencode/magic-context/magic-context.log` (`pi/` for Pi) | Diagnostic log | Disposable. |
+| `$MAGIC_CONTEXT_LOG_PATH` (default: `${TMPDIR}/opencode/magic-context/magic-context.log`, `pi/` for Pi) | Diagnostic log. Set `MAGIC_CONTEXT_LOG_PATH` to redirect it (e.g. to a persistent path in a container). | Disposable. |
 
 **Sandboxed / ephemeral environments (Docker, CI, disposable containers):** mount the `~/.local/share/cortexkit/magic-context/` directory on a persistent volume so the database and model cache survive between runs. If only the model cache is ephemeral, the model is simply re-downloaded; if the database is ephemeral, memory and history don't accumulate. To avoid the ~90 MB model download entirely, set `memory.enabled: false` or point `embedding` at a remote `openai_compatible`/`ollama` backend.
 

packages/dashboard/README.md

@@ -71,7 +71,7 @@ packages/dashboard/
 The dashboard reads from the same SQLite database the plugin writes to:
 - **Database**: `~/.local/share/cortexkit/magic-context/context.db`
 - **Config**: `~/.config/cortexkit/magic-context.jsonc` (user) · `<project>/.cortexkit/magic-context.jsonc` (project)
-- **Logs**: `${TMPDIR}/opencode/magic-context/magic-context.log` (`pi/` for Pi)
+- **Logs**: `$MAGIC_CONTEXT_LOG_PATH` (default: `${TMPDIR}/opencode/magic-context/magic-context.log`, `pi/` for Pi)
 
 Database access uses WAL mode for safe concurrent reads while the plugin writes. Write operations (memory edits, dream queue entries) use `busy_timeout` to handle contention.
 

packages/dashboard/src-tauri/src/log_parser.rs

@@ -33,6 +33,18 @@ impl Harness {
 /// in sync manually because the dashboard doesn't import any TypeScript
 /// source.
 pub fn resolve_log_path_for(harness: Harness) -> PathBuf {
+    // Mirror the plugin's getMagicContextLogPath: an explicit override wins over
+    // the harness temp-dir default so the dashboard reads the same file the
+    // plugin writes when the user relocates it. Blank/whitespace is treated as
+    // unset.
+    if let Some(env_path) = std::env::var("MAGIC_CONTEXT_LOG_PATH")
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+    {
+        return PathBuf::from(env_path);
+    }
+
     std::env::temp_dir()
         .join(harness.as_str())
         .join("magic-context")
@@ -436,3 +448,76 @@ pub fn read_log_tail(path: &PathBuf, max_lines: usize) -> Vec<LogEntry> {
         .filter_map(|line| parse_log_line(line))
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{resolve_log_path_for, Harness};
+    use std::path::PathBuf;
+    use std::sync::{Mutex, OnceLock};
+
+    // The env var is process-global; serialize the tests that mutate it.
+    fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+        static ENV_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        ENV_LOCK
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+    }
+
+    #[test]
+    fn resolve_log_path_for_uses_harness_fallback_when_env_unset() {
+        let _guard = env_lock();
+        std::env::remove_var("MAGIC_CONTEXT_LOG_PATH");
+
+        assert_eq!(
+            resolve_log_path_for(Harness::Opencode),
+            std::env::temp_dir()
+                .join("opencode")
+                .join("magic-context")
+                .join("magic-context.log")
+        );
+        assert_eq!(
+            resolve_log_path_for(Harness::Pi),
+            std::env::temp_dir()
+                .join("pi")
+                .join("magic-context")
+                .join("magic-context.log")
+        );
+    }
+
+    #[test]
+    fn resolve_log_path_for_honors_magic_context_log_path_override() {
+        let _guard = env_lock();
+        let custom = std::env::temp_dir()
+            .join("custom")
+            .join("magic-context.log");
+        std::env::set_var(
+            "MAGIC_CONTEXT_LOG_PATH",
+            custom.to_string_lossy().to_string(),
+        );
+
+        assert_eq!(
+            resolve_log_path_for(Harness::Opencode),
+            PathBuf::from(&custom)
+        );
+        assert_eq!(resolve_log_path_for(Harness::Pi), PathBuf::from(&custom));
+
+        std::env::remove_var("MAGIC_CONTEXT_LOG_PATH");
+    }
+
+    #[test]
+    fn resolve_log_path_for_ignores_blank_magic_context_log_path() {
+        let _guard = env_lock();
+        std::env::set_var("MAGIC_CONTEXT_LOG_PATH", "   ");
+
+        assert_eq!(
+            resolve_log_path_for(Harness::Pi),
+            std::env::temp_dir()
+                .join("pi")
+                .join("magic-context")
+                .join("magic-context.log")
+        );
+
+        std::env::remove_var("MAGIC_CONTEXT_LOG_PATH");
+    }
+}

packages/docs/src/content/docs/reference/dashboard.md

@@ -148,4 +148,4 @@ Use [Configuration](/reference/configuration/) for the full generated key refere
 
 ## Logs
 
-Optional **log tail** for `magic-context.log` with filtering, useful alongside Cache when correlating busts with plugin log lines.
+Optional **log tail** for `magic-context.log` with filtering, useful alongside Cache when correlating busts with plugin log lines. The log path defaults to `${TMPDIR}/opencode/magic-context/magic-context.log` (`pi/` for Pi); set the `MAGIC_CONTEXT_LOG_PATH` environment variable to redirect it.

packages/plugin/src/shared/data-path.test.ts

@@ -7,6 +7,7 @@ import {
     getCacheDir,
     getDataDir,
     getLegacyOpenCodeMagicContextStorageDir,
+    getMagicContextLogPath,
     getMagicContextStorageDir,
     getOpenCodeCacheDir,
     getOpenCodeStorageDir,
@@ -18,17 +19,20 @@ const savedEnv = {
     XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
     XDG_DATA_HOME: process.env.XDG_DATA_HOME,
     LOCALAPPDATA: process.env.LOCALAPPDATA,
+    MAGIC_CONTEXT_LOG_PATH: process.env.MAGIC_CONTEXT_LOG_PATH,
 };
 
 describe("data-path", () => {
     beforeEach(() => {
         process.env.XDG_CACHE_HOME = undefined;
         process.env.XDG_DATA_HOME = undefined;
         process.env.LOCALAPPDATA = undefined;
+        process.env.MAGIC_CONTEXT_LOG_PATH = undefined;
         // Bun's env handling: explicit delete for unset
         delete process.env.XDG_CACHE_HOME;
         delete process.env.XDG_DATA_HOME;
         delete process.env.LOCALAPPDATA;
+        delete process.env.MAGIC_CONTEXT_LOG_PATH;
     });
 
     afterEach(() => {
@@ -37,6 +41,9 @@ describe("data-path", () => {
         if (savedEnv.XDG_DATA_HOME !== undefined)
             process.env.XDG_DATA_HOME = savedEnv.XDG_DATA_HOME;
         if (savedEnv.LOCALAPPDATA !== undefined) process.env.LOCALAPPDATA = savedEnv.LOCALAPPDATA;
+        if (savedEnv.MAGIC_CONTEXT_LOG_PATH !== undefined)
+            process.env.MAGIC_CONTEXT_LOG_PATH = savedEnv.MAGIC_CONTEXT_LOG_PATH;
+        else delete process.env.MAGIC_CONTEXT_LOG_PATH;
     });
 
     test("getCacheDir falls back to <homedir>/.cache when XDG_CACHE_HOME is unset (all platforms)", () => {
@@ -158,6 +165,27 @@ describe("data-path", () => {
             path.join("/some/project/", ".cortexkit", "magic-context"),
         );
     });
+
+    test("getMagicContextLogPath falls back to the harness temp dir when the env override is unset", () => {
+        expect(getMagicContextLogPath("opencode")).toBe(
+            path.join(os.tmpdir(), "opencode", "magic-context", "magic-context.log"),
+        );
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
+
+    test("getMagicContextLogPath honors MAGIC_CONTEXT_LOG_PATH", () => {
+        process.env.MAGIC_CONTEXT_LOG_PATH = "/tmp/custom/magic-context.log";
+        expect(getMagicContextLogPath("pi")).toBe("/tmp/custom/magic-context.log");
+    });
+
+    test("getMagicContextLogPath ignores a blank MAGIC_CONTEXT_LOG_PATH", () => {
+        process.env.MAGIC_CONTEXT_LOG_PATH = "   ";
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
 });
 
 describe("ensureCortexKitArtifactGitignore", () => {

packages/plugin/src/shared/data-path.ts

@@ -46,6 +46,11 @@ export function getMagicContextTempDir(harness: HarnessId = getHarness()): strin
  * reflected in the next flush.
  */
 export function getMagicContextLogPath(harness: HarnessId = getHarness()): string {
+    // An explicit override wins over the harness temp-dir default, so users on
+    // sandboxed/ephemeral setups (Docker, CI) can point the diagnostic log at a
+    // persistent or shared path. Blank/whitespace is treated as unset.
+    const envPath = process.env.MAGIC_CONTEXT_LOG_PATH?.trim();
+    if (envPath) return envPath;
     return path.join(getMagicContextTempDir(harness), "magic-context.log");
 }