@sean.holung/minicode 0.3.5 → 0.3.6

package/README.md

@@ -1,5 +1,7 @@
 # minicode
 
+> Now supports connecting to [OpenRouter](https://openrouter.ai/) account via minicode UI. Sign in with OpenRouter account. Use for free with compatible free tier OpenRouter hosted models from MiniMax, Nvidia, Qwen, Google, etc.
+
 A graph-native coding agent and code exploration environment built around structural context optimization that leverages symbol-aware retrieval, dependency graphs, and targeted context. It started as a way to make local models viable under tighter context budgets, and it now also works well with hosted frontier models through the same runtime, web UI, and OpenAI-compatible serve mode. 
 
 minicode is built on a simple bet: models perform better when you give them less, but better context. Bloated context directly degrades output quality: attention dilutes, positional biases cause mid-context information loss, and inference latency grows as token count increases.
@@ -10,6 +12,16 @@ _Run `minicode serve` to get the web UI on localhost: chat, tool activity, sessi
 
 <img width="1723" height="920" alt="Screenshot 2026-03-26 at 6 30 23 PM" src="https://github.com/user-attachments/assets/499c8dc7-cc2b-4125-abd5-32b2fc9795ea" />
 
+## Quick Start (OpenRouter)
+```bash
+npm install -g @sean.holung/minicode
+minicode serve
+```
+
+1. Navigate to [localhost:4567](http://localhost:4567)
+2. Click Connect OpenRouter to sign in to [OpenRouter](https://openrouter.ai/) and connect account.
+3. Choose a model. Choose a (free) model if on free tier. Model must support tool use.
+
 
 ## Quick Start (LM Studio)
 
@@ -19,8 +31,8 @@ _Run `minicode serve` to get the web UI on localhost: chat, tool activity, sessi
 # 2. Install
 npm install -g @sean.holung/minicode
 
-# 3. Configure (~/.minicode/agent.config.json is auto-created on first run)
-#    Set your model name — minicode will prompt you if this is missing.
+# 3. Configure
+#    Set your model name in ~/.minicode/.env — minicode will prompt you if this is missing.
 cat > ~/.minicode/.env << 'EOF'
 MODEL_PROVIDER=openai-compatible
 MODEL=your-model-name
@@ -164,12 +176,12 @@ See [docs/PLUGIN_SPEC.md](docs/PLUGIN_SPEC.md) for the full specification. Quick
 
 ## Configuration
 
-Configuration can come from (later sources override earlier):
+Configuration can come from:
 
-1. `~/.minicode/.env` — User-level defaults (API keys, model, etc.)
-2. `~/.minicode/agent.config.json` — User-level JSON config
-3. Project `.env` and `agent.config.json` in workspace root
-4. Environment variables (highest precedence)
+1. `~/.minicode/.env` — User-level defaults (API keys, model, runtime settings)
+2. Environment variables — Shell overrides for the current process
+
+When the same key is set in both places, the exported environment variable wins.
 
 Nothing is written inside your workspace; config and cache live under `~/.minicode/`.
 
@@ -184,6 +196,7 @@ Nothing is written inside your workspace; config and cache live under `~/.minico
 | `OPENAI_BASE_URL`       | No              | `http://localhost:1234/v1` | Base URL for OpenAI-compatible API (LM Studio, etc.)                                                                                  |
 | `OPENAI_API_KEY`        | No              | none                       | Optional for local servers; required if your endpoint enforces auth                                                                   |
 | `OPENROUTER_API_KEY`    | No              | none                       | Preferred key when `OPENAI_BASE_URL` points at OpenRouter; falls back to `OPENAI_API_KEY` if unset                                  |
+| `COMMAND_DENYLIST`      | No              | none                       | Optional JSON array or comma-separated regex patterns appended to the built-in destructive-command denylist                         |
 | `MAX_STEPS`             | No              | `50`                       | Max agent loop iterations per user turn                                                                                               |
 | `MAX_TOKENS`            | No              | `4096`                     | Max model output tokens per model call                                                                                                |
 | `MAX_CONTEXT_TOKENS`    | No              | `32000`                    | Approximate session history trimming target. For small models (e.g. 8k context), set lower (e.g. `6000`) to leave room for responses. |
@@ -202,44 +215,7 @@ Nothing is written inside your workspace; config and cache live under `~/.minico
 | `REASONING_EFFORT`      | No              | unset                      | Reasoning level for providers that support it. Valid values: `xhigh`, `high`, `medium`, `low`, `minimal`, `none`                   |
 
 
-### `agent.config.json`
-
-A global `~/.minicode/agent.config.json` is auto-created on first run. Only set what you need — everything has sensible defaults:
-
-```json
-{
-  "modelProvider": "openai-compatible",
-  "model": "your-model-name",
-  "openAiBaseUrl": "http://localhost:1234/v1",
-  "maxSteps": 50,
-  "maxTokens": 4096,
-  "maxContextTokens": 32000
-}
-```
-
-Field mapping:
-
-- `modelProvider` ↔ `MODEL_PROVIDER`
-- `model` ↔ `MODEL`
-- `maxSteps` ↔ `MAX_STEPS`
-- `workspaceRoot` ↔ `WORKSPACE_ROOT`
-- `maxTokens` ↔ `MAX_TOKENS`
-- `maxContextTokens` ↔ `MAX_CONTEXT_TOKENS`
-- `commandTimeout` ↔ `COMMAND_TIMEOUT_MS`
-- `commandDenylist` ↔ no env equivalent (config-only)
-- `confirmDestructive` ↔ `CONFIRM_DESTRUCTIVE`
-- `maxFileSizeBytes` ↔ `MAX_FILE_SIZE_BYTES`
-- `keepRecentMessages` ↔ `KEEP_RECENT_MESSAGES`
-- `loopDetectionWindow` ↔ `LOOP_DETECTION_WINDOW`
-- `openAiBaseUrl` ↔ `OPENAI_BASE_URL`
-- `openAiApiKey` ↔ `OPENAI_API_KEY` / `OPENROUTER_API_KEY` (when using OpenRouter)
-- `maxToolOutputChars` ↔ `MAX_TOOL_OUTPUT_CHARS`
-- `enableFileReadDedup` ↔ `ENABLE_FILE_READ_DEDUP`
-- `enableAdaptiveKeepRecent` ↔ `ENABLE_ADAPTIVE_KEEP_RECENT`
-- `enableToolOutputTruncation` ↔ `ENABLE_TOOL_OUTPUT_TRUNCATION`
-- `compactionThreshold` ↔ `COMPACTION_THRESHOLD`
-- `compactionModel` ↔ `COMPACTION_MODEL`
-- `reasoningEffort` ↔ `REASONING_EFFORT`
+All persisted user-level settings now live in `~/.minicode/.env`. The web UI settings dialog and `/config set` both update that file directly for non-secret runtime defaults.
 
 ## Usage
 

package/dist/src/agent/config.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
@@ -10,7 +10,7 @@ export const MINICODE_HOME = path.join(os.homedir(), ".minicode");
  */
 export function formatConfigForDisplay(config) {
     const lines = [
-        "configHome: " + MINICODE_HOME + " (.env, agent.config.json)",
+        "configHome: " + MINICODE_HOME + " (.env)",
         "workspaceRoot: " + config.workspaceRoot,
         "modelProvider: " + config.modelProvider,
         "model: " + config.model,
@@ -46,9 +46,14 @@ export function formatConfigForDisplay(config) {
  */
 export function getConfigMissing(config) {
     const missing = [];
+    const isOpenRouter = config.modelProvider === "openai-compatible" &&
+        config.openAiBaseUrl.includes("openrouter");
     if (!config.model) {
         missing.push("MODEL is not set");
     }
+    if (isOpenRouter && !config.openAiApiKey?.trim()) {
+        missing.push("OPENROUTER_API_KEY is not set");
+    }
     if (config.modelProvider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
         missing.push("ANTHROPIC_API_KEY is not set");
     }
@@ -63,8 +68,8 @@ export function getConfigSetupMessage(config) {
         "minicode is not configured yet. Missing:",
         ...missing.map((m) => `  - ${m}`),
         "",
-        `Set these in ~/.minicode/.env or as environment variables.`,
-        `Edit ~/.minicode/agent.config.json for non-secret settings.`,
+        "Set these in ~/.minicode/.env or as environment variables.",
+        "Editable runtime defaults set through the UI or /config are saved back to ~/.minicode/.env.",
         "",
         "Example ~/.minicode/.env for a local model:",
         "  MODEL_PROVIDER=openai-compatible",
@@ -117,20 +122,6 @@ function parseBoolean(value, fallback) {
     }
     return fallback;
 }
-export async function loadConfigFile(configPath) {
-    try {
-        await access(configPath);
-    }
-    catch {
-        return {};
-    }
-    const file = await readFile(configPath, "utf8");
-    const parsed = JSON.parse(file);
-    if (!parsed || typeof parsed !== "object") {
-        return {};
-    }
-    return parsed;
-}
 async function loadDotenvFile(envPath) {
     try {
         const file = await readFile(envPath, "utf8");
@@ -188,6 +179,24 @@ function parseUserDenylist(patterns) {
     }
     return denylist;
 }
+function parseCommandDenylistEnv(value) {
+    if (!value?.trim()) {
+        return [];
+    }
+    const trimmed = value.trim();
+    if (trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+                return parseUserDenylist(parsed);
+            }
+        }
+        catch {
+            return [];
+        }
+    }
+    return parseUserDenylist(trimmed.split(",").map((pattern) => pattern.trim()).filter(Boolean));
+}
 function parseModelProvider(value) {
     const normalized = value?.trim().toLowerCase();
     if (normalized === "openai-compatible" ||
@@ -198,74 +207,50 @@ function parseModelProvider(value) {
     }
     return "anthropic";
 }
-const DEFAULT_CONFIG_CONTENT = `{
-  "modelProvider": "openai-compatible",
-  "model": "",
-  "openAiBaseUrl": "http://localhost:1234/v1",
-  "maxSteps": 50,
-  "maxTokens": 4096,
-  "maxContextTokens": 32000
-}
-`;
 async function ensureMinicodeHome(minicodeHome) {
     await mkdir(minicodeHome, { recursive: true });
-    const configPath = path.join(minicodeHome, "agent.config.json");
-    try {
-        await access(configPath);
-    }
-    catch {
-        await writeFile(configPath, DEFAULT_CONFIG_CONTENT, "utf8");
-    }
 }
 export async function loadAgentConfig(cwd = process.cwd(), options = {}) {
     const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
     await ensureMinicodeHome(minicodeHome);
-    const homeConfigPath = path.join(minicodeHome, "agent.config.json");
-    const fileConfig = await loadConfigFile(homeConfigPath);
     const env = (await resolveConfigEnv({ minicodeHome })).values;
-    const rawWorkspaceRoot = env.WORKSPACE_ROOT ?? fileConfig.workspaceRoot ?? cwd;
+    const rawWorkspaceRoot = env.WORKSPACE_ROOT ?? cwd;
     const workspaceRoot = path.resolve(cwd, rawWorkspaceRoot);
     const commandDenylist = [
         ...DEFAULT_COMMAND_DENYLIST,
-        ...parseUserDenylist(fileConfig.commandDenylist),
+        ...parseCommandDenylistEnv(env.COMMAND_DENYLIST),
     ];
-    const rawBaseUrl = env.OPENAI_BASE_URL ??
-        fileConfig.openAiBaseUrl ??
-        "http://localhost:1234/v1";
+    const rawBaseUrl = env.OPENAI_BASE_URL ?? "http://localhost:1234/v1";
     const isOpenRouter = rawBaseUrl.includes("openrouter");
     const openAiApiKey = isOpenRouter
-        ? (env.OPENROUTER_API_KEY ??
-            env.OPENAI_API_KEY ??
-            fileConfig.openAiApiKey)
-        : (env.OPENAI_API_KEY ?? fileConfig.openAiApiKey);
+        ? (env.OPENROUTER_API_KEY ?? env.OPENAI_API_KEY)
+        : env.OPENAI_API_KEY;
     return {
-        modelProvider: parseModelProvider(env.MODEL_PROVIDER ?? fileConfig.modelProvider ?? "openai-compatible"),
-        model: env.MODEL ??
-            fileConfig.model ??
-            "",
-        maxSteps: parseNumber(env.MAX_STEPS, fileConfig.maxSteps ?? 50),
-        maxTokens: parseNumber(env.MAX_TOKENS, fileConfig.maxTokens ?? 4096),
-        maxContextTokens: parseNumber(env.MAX_CONTEXT_TOKENS, fileConfig.maxContextTokens ?? 32_000),
+        modelProvider: parseModelProvider(env.MODEL_PROVIDER ?? "openai-compatible"),
+        model: env.MODEL ?? "",
+        maxSteps: parseNumber(env.MAX_STEPS, 50),
+        maxTokens: parseNumber(env.MAX_TOKENS, 4096),
+        maxContextTokens: parseNumber(env.MAX_CONTEXT_TOKENS, 32_000),
         workspaceRoot,
-        commandTimeoutMs: parseNumber(env.COMMAND_TIMEOUT_MS, fileConfig.commandTimeout ?? 30_000),
-        maxFileSizeBytes: parseNumber(env.MAX_FILE_SIZE_BYTES, fileConfig.maxFileSizeBytes ?? 1_000_000),
+        commandTimeoutMs: parseNumber(env.COMMAND_TIMEOUT_MS, 30_000),
+        maxFileSizeBytes: parseNumber(env.MAX_FILE_SIZE_BYTES, 1_000_000),
         commandDenylist,
-        confirmDestructive: parseBoolean(env.CONFIRM_DESTRUCTIVE, fileConfig.confirmDestructive ?? true),
-        keepRecentMessages: parseNumber(env.KEEP_RECENT_MESSAGES, fileConfig.keepRecentMessages ?? 12),
-        loopDetectionWindow: parseNumber(env.LOOP_DETECTION_WINDOW, fileConfig.loopDetectionWindow ?? 6),
-        maxToolOutputChars: parseNumber(env.MAX_TOOL_OUTPUT_CHARS, fileConfig.maxToolOutputChars ?? 8_000),
+        confirmDestructive: parseBoolean(env.CONFIRM_DESTRUCTIVE, true),
+        keepRecentMessages: parseNumber(env.KEEP_RECENT_MESSAGES, 12),
+        loopDetectionWindow: parseNumber(env.LOOP_DETECTION_WINDOW, 6),
+        maxToolOutputChars: parseNumber(env.MAX_TOOL_OUTPUT_CHARS, 8_000),
         openAiBaseUrl: rawBaseUrl,
         ...(openAiApiKey !== undefined ? { openAiApiKey } : {}),
-        enableFileReadDedup: parseBoolean(env.ENABLE_FILE_READ_DEDUP, fileConfig.enableFileReadDedup ?? true),
-        enableAdaptiveKeepRecent: parseBoolean(env.ENABLE_ADAPTIVE_KEEP_RECENT, fileConfig.enableAdaptiveKeepRecent ?? true),
-        enableToolOutputTruncation: parseBoolean(env.ENABLE_TOOL_OUTPUT_TRUNCATION, fileConfig.enableToolOutputTruncation ?? true),
-        compactionThreshold: parseNumber(env.COMPACTION_THRESHOLD, fileConfig.compactionThreshold ?? 0.8),
-        ...(env.COMPACTION_MODEL ?? fileConfig.compactionModel
-            ? { compactionModel: env.COMPACTION_MODEL ?? fileConfig.compactionModel }
+        enableFileReadDedup: parseBoolean(env.ENABLE_FILE_READ_DEDUP, true),
+        enableAdaptiveKeepRecent: parseBoolean(env.ENABLE_ADAPTIVE_KEEP_RECENT, true),
+        enableToolOutputTruncation: parseBoolean(env.ENABLE_TOOL_OUTPUT_TRUNCATION, true),
+        compactionThreshold: parseNumber(env.COMPACTION_THRESHOLD, 0.8),
+        ...(env.COMPACTION_MODEL
+            ? { compactionModel: env.COMPACTION_MODEL }
             : {}),
-        enableDynamicPrompt: parseBoolean(env.ENABLE_DYNAMIC_PROMPT, fileConfig.enableDynamicPrompt ?? true),
+        enableDynamicPrompt: parseBoolean(env.ENABLE_DYNAMIC_PROMPT, true),
         ...(() => {
-            const effort = parseReasoningEffort(env.REASONING_EFFORT ?? fileConfig.reasoningEffort);
+            const effort = parseReasoningEffort(env.REASONING_EFFORT);
             return effort ? { reasoningEffort: effort } : {};
         })(),
     };

package/dist/src/agent/editable-config.js

@@ -1,6 +1,5 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { loadConfigFile, MINICODE_HOME, resolveConfigEnv, } from "./config.js";
+import { MINICODE_HOME, resolveConfigEnv, } from "./config.js";
+import { getHomeEnvPath, loadHomeEnvValues, upsertHomeEnvValues } from "./home-env.js";
 const REASONING_VALUES = [
     "xhigh",
     "high",
@@ -12,7 +11,6 @@ const REASONING_VALUES = [
 export const EDITABLE_CONFIG_DEFINITIONS = [
     {
         key: "modelProvider",
-        fileKey: "modelProvider",
         envVar: "MODEL_PROVIDER",
         type: "enum",
         values: ["anthropic", "openai-compatible"],
@@ -20,119 +18,102 @@ export const EDITABLE_CONFIG_DEFINITIONS = [
     },
     {
         key: "model",
-        fileKey: "model",
         envVar: "MODEL",
         type: "string",
         description: "Default model id for new sessions",
     },
     {
         key: "maxSteps",
-        fileKey: "maxSteps",
         envVar: "MAX_STEPS",
         type: "number",
         description: "Turn call limit before the agent pauses and waits for another prompt",
     },
     {
         key: "maxTokens",
-        fileKey: "maxTokens",
         envVar: "MAX_TOKENS",
         type: "number",
         description: "Maximum completion tokens per model response",
     },
     {
         key: "maxContextTokens",
-        fileKey: "maxContextTokens",
         envVar: "MAX_CONTEXT_TOKENS",
         type: "number",
         description: "Estimated prompt-context budget before compaction",
     },
     {
         key: "commandTimeoutMs",
-        fileKey: "commandTimeout",
         envVar: "COMMAND_TIMEOUT_MS",
         type: "number",
         description: "Shell command timeout in milliseconds",
     },
     {
         key: "maxFileSizeBytes",
-        fileKey: "maxFileSizeBytes",
         envVar: "MAX_FILE_SIZE_BYTES",
         type: "number",
         description: "Maximum file size allowed for read/edit tools",
     },
     {
         key: "confirmDestructive",
-        fileKey: "confirmDestructive",
         envVar: "CONFIRM_DESTRUCTIVE",
         type: "boolean",
         description: "Whether destructive commands require confirmation",
     },
     {
         key: "keepRecentMessages",
-        fileKey: "keepRecentMessages",
         envVar: "KEEP_RECENT_MESSAGES",
         type: "number",
         description: "Recent messages preserved when trimming session history",
     },
     {
         key: "loopDetectionWindow",
-        fileKey: "loopDetectionWindow",
         envVar: "LOOP_DETECTION_WINDOW",
         type: "number",
         description: "Window size for repeated-tool-call loop detection",
     },
     {
         key: "maxToolOutputChars",
-        fileKey: "maxToolOutputChars",
         envVar: "MAX_TOOL_OUTPUT_CHARS",
         type: "number",
         description: "Maximum tool output retained before truncation",
     },
     {
         key: "openAiBaseUrl",
-        fileKey: "openAiBaseUrl",
         envVar: "OPENAI_BASE_URL",
         type: "string",
         description: "Base URL for OpenAI-compatible providers",
     },
     {
         key: "enableFileReadDedup",
-        fileKey: "enableFileReadDedup",
         envVar: "ENABLE_FILE_READ_DEDUP",
         type: "boolean",
         description: "Deduplicate repeated file reads in prompt context",
     },
     {
         key: "enableAdaptiveKeepRecent",
-        fileKey: "enableAdaptiveKeepRecent",
         envVar: "ENABLE_ADAPTIVE_KEEP_RECENT",
         type: "boolean",
         description: "Adjust recent-message retention based on context pressure",
     },
     {
         key: "enableToolOutputTruncation",
-        fileKey: "enableToolOutputTruncation",
         envVar: "ENABLE_TOOL_OUTPUT_TRUNCATION",
         type: "boolean",
         description: "Truncate oversized tool output before storing it in session history",
     },
     {
         key: "compactionThreshold",
-        fileKey: "compactionThreshold",
         envVar: "COMPACTION_THRESHOLD",
         type: "number",
         description: "Compaction threshold ratio used before a turn starts",
     },
     {
         key: "compactionModel",
-        fileKey: "compactionModel",
         envVar: "COMPACTION_MODEL",
         type: "string",
         description: "Optional model id used for LLM-based compaction",
     },
     {
         key: "reasoningEffort",
-        fileKey: "reasoningEffort",
         envVar: "REASONING_EFFORT",
         type: "enum",
         values: REASONING_VALUES,
@@ -140,7 +121,6 @@ export const EDITABLE_CONFIG_DEFINITIONS = [
     },
     {
         key: "enableDynamicPrompt",
-        fileKey: "enableDynamicPrompt",
         envVar: "ENABLE_DYNAMIC_PROMPT",
         type: "boolean",
         description: "Toggle project-aware dynamic prompt generation",
@@ -194,9 +174,6 @@ function normalizePersistedValue(value) {
     }
     return null;
 }
-function isEmptyConfigFile(config) {
-    return Object.keys(config).length === 0;
-}
 export function listEditableConfigDefinitions() {
     return EDITABLE_CONFIG_DEFINITIONS;
 }
@@ -223,10 +200,25 @@ export function formatPersistedConfigValue(value) {
     return String(value);
 }
 export function getGlobalConfigPath(minicodeHome = MINICODE_HOME) {
-    return path.join(minicodeHome, "agent.config.json");
+    return getHomeEnvPath(minicodeHome);
 }
 export async function loadPersistedConfig(minicodeHome = MINICODE_HOME) {
-    return loadConfigFile(getGlobalConfigPath(minicodeHome));
+    return loadHomeEnvValues(minicodeHome);
+}
+function readPersistedEnvValue(definition, persisted) {
+    const rawValue = persisted[definition.envVar];
+    if (rawValue === undefined) {
+        return null;
+    }
+    try {
+        return parseEditableValue(definition, rawValue);
+    }
+    catch {
+        return rawValue;
+    }
+}
+function serializeEditableValue(value) {
+    return String(value);
 }
 export async function buildStructuredConfigPayload(config, minicodeHome = MINICODE_HOME) {
     const configPath = getGlobalConfigPath(minicodeHome);
@@ -235,10 +227,11 @@ export async function buildStructuredConfigPayload(config, minicodeHome = MINICO
     return {
         configPath,
         entries: EDITABLE_CONFIG_DEFINITIONS.map((definition) => {
-            const envValue = env.values[definition.envVar];
-            const envSource = env.sources[definition.envVar] ?? null;
-            const envSourcePath = envSource === "home-dotenv"
-                ? env.homeEnvPath
+            const envSource = env.sources[definition.envVar] === "process"
+                ? "process"
+                : null;
+            const envValue = envSource === "process"
+                ? (env.values[definition.envVar] ?? null)
                 : null;
             return {
                 key: definition.key,
@@ -247,11 +240,11 @@ export async function buildStructuredConfigPayload(config, minicodeHome = MINICO
                 envVar: definition.envVar,
                 ...(definition.values ? { values: definition.values } : {}),
                 effectiveValue: normalizePersistedValue(config[definition.key]),
-                persistedValue: normalizePersistedValue(persisted[definition.fileKey]),
-                envValue: envValue ?? null,
+                persistedValue: readPersistedEnvValue(definition, persisted),
+                envValue,
                 envSource,
-                envSourcePath,
-                overriddenByEnv: envValue !== undefined,
+                envSourcePath: envSource === "process" ? null : null,
+                overriddenByEnv: envSource === "process",
             };
         }),
     };
@@ -260,26 +253,25 @@ export async function setPersistedConfigValue(options) {
     const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
     const definition = getEditableConfigDefinition(options.key);
     const configPath = getGlobalConfigPath(minicodeHome);
-    const nextFile = await loadConfigFile(configPath);
     const storedValue = parseEditableValue(definition, options.rawValue);
-    nextFile[definition.fileKey] = storedValue;
-    await mkdir(path.dirname(configPath), { recursive: true });
-    await writeFile(configPath, JSON.stringify(nextFile, null, 2) + "\n", "utf8");
+    await upsertHomeEnvValues({
+        minicodeHome,
+        values: {
+            [definition.envVar]: serializeEditableValue(storedValue),
+        },
+    });
     return { path: configPath, storedValue };
 }
 export async function unsetPersistedConfigValue(options) {
     const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
     const definition = getEditableConfigDefinition(options.key);
     const configPath = getGlobalConfigPath(minicodeHome);
-    const nextFile = await loadConfigFile(configPath);
-    delete nextFile[definition.fileKey];
-    if (isEmptyConfigFile(nextFile)) {
-        await rm(configPath, { force: true });
-    }
-    else {
-        await mkdir(path.dirname(configPath), { recursive: true });
-        await writeFile(configPath, JSON.stringify(nextFile, null, 2) + "\n", "utf8");
-    }
+    await upsertHomeEnvValues({
+        minicodeHome,
+        values: {
+            [definition.envVar]: null,
+        },
+    });
     return { path: configPath };
 }
 export async function applyPersistedConfigUpdates(options) {
@@ -291,22 +283,22 @@ export async function applyPersistedConfigUpdates(options) {
         return { key: rawKey, value };
     });
     const saved = [];
+    const envUpdates = {};
     for (const item of planned) {
+        const definition = getEditableConfigDefinition(item.key);
         if (item.value === null) {
-            await unsetPersistedConfigValue({
-                key: item.key,
-                minicodeHome,
-            });
+            envUpdates[definition.envVar] = null;
             saved.push({ key: item.key, value: null });
             continue;
         }
-        await setPersistedConfigValue({
-            key: item.key,
-            rawValue: String(item.value),
-            minicodeHome,
-        });
-        saved.push({ key: item.key, value: item.value });
+        const storedValue = parseEditableValue(definition, String(item.value));
+        envUpdates[definition.envVar] = serializeEditableValue(storedValue);
+        saved.push({ key: item.key, value: storedValue });
     }
+    await upsertHomeEnvValues({
+        minicodeHome,
+        values: envUpdates,
+    });
     return {
         path: getGlobalConfigPath(minicodeHome),
         saved,

package/dist/src/agent/home-env.js

@@ -0,0 +1,74 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import dotenv from "dotenv";
+import { MINICODE_HOME } from "./config.js";
+export function getHomeEnvPath(minicodeHome = MINICODE_HOME) {
+    return path.join(minicodeHome, ".env");
+}
+export async function loadHomeEnvValues(minicodeHome = MINICODE_HOME) {
+    const envPath = getHomeEnvPath(minicodeHome);
+    try {
+        const existing = await readFile(envPath, "utf8");
+        return dotenv.parse(existing);
+    }
+    catch {
+        return {};
+    }
+}
+function formatEnvValue(value) {
+    return value;
+}
+export async function upsertHomeEnvValues(options) {
+    const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
+    const envPath = getHomeEnvPath(minicodeHome);
+    await mkdir(path.dirname(envPath), { recursive: true });
+    let existing = "";
+    try {
+        existing = await readFile(envPath, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    const pending = new Map(Object.entries(options.values));
+    const managedKeys = new Set(pending.keys());
+    const assignmentPattern = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+    const normalizedLines = existing === ""
+        ? []
+        : existing.split(/\r?\n/);
+    const nextLines = [];
+    const seen = new Set();
+    for (const line of normalizedLines) {
+        const match = line.match(assignmentPattern);
+        if (!match) {
+            nextLines.push(line);
+            continue;
+        }
+        const key = match[1];
+        if (!managedKeys.has(key)) {
+            nextLines.push(line);
+            continue;
+        }
+        if (seen.has(key)) {
+            continue;
+        }
+        const nextValue = pending.get(key);
+        if (nextValue !== null) {
+            nextLines.push(`${key}=${formatEnvValue(nextValue)}`);
+        }
+        seen.add(key);
+        pending.delete(key);
+    }
+    const pendingEntries = [...pending.entries()].filter((entry) => entry[1] !== null);
+    if (pendingEntries.length > 0 && nextLines.length > 0 && nextLines[nextLines.length - 1] !== "") {
+        nextLines.push("");
+    }
+    for (const [key, value] of pendingEntries) {
+        nextLines.push(`${key}=${formatEnvValue(value)}`);
+    }
+    const fileContent = `${nextLines.join("\n").replace(/\n+$/, "")}\n`;
+    await writeFile(envPath, fileContent, "utf8");
+    return {
+        path: envPath,
+        updatedKeys: Object.keys(options.values),
+    };
+}