@letta-ai/letta-code 0.34.25 → 0.34.27

package/scripts/codex-watch/release-analysis.test.ts

@@ -52,17 +52,121 @@ describe("Codex stable release range", () => {
 });
 
 describe("Codex GitHub release fetch", () => {
+  test("resolves latest without fetching a list page when the cursor is current", async () => {
+    const urls: string[] = [];
+    const releases = await listStableReleases({
+      sinceTag: "rust-v0.3.0",
+      fetchImpl: (async (input) => {
+        urls.push(String(input));
+        return Response.json(STABLES[2]);
+      }) as typeof fetch,
+    });
+
+    expect(releases).toEqual([STABLES[2]]);
+    expect(urls).toEqual([
+      "https://api.github.com/repos/openai/codex/releases/latest",
+    ]);
+  });
+
+  test("resolves an explicit current tag without fetching a list page", async () => {
+    const urls: string[] = [];
+    const releases = await listStableReleases({
+      currentTag: "rust-v0.2.0",
+      sinceTag: "rust-v0.2.0",
+      fetchImpl: (async (input) => {
+        const url = String(input);
+        urls.push(url);
+        return Response.json(url.endsWith("/latest") ? STABLES[2] : STABLES[1]);
+      }) as typeof fetch,
+    });
+
+    expect(releases).toEqual([STABLES[1], STABLES[2]]);
+    expect(urls).toEqual([
+      "https://api.github.com/repos/openai/codex/releases/latest",
+      "https://api.github.com/repos/openai/codex/releases/tags/rust-v0.2.0",
+    ]);
+  });
+
+  test("bounds pagination after finding the adjacent stable release", async () => {
+    const urls: string[] = [];
+    const prereleases = Array.from({ length: 100 }, (_, index) => ({
+      ...release(
+        `rust-v1.0.${index}`,
+        `2026-09-01T00:${String(index % 60).padStart(2, "0")}:00Z`,
+      ),
+      prerelease: true,
+    }));
+    const releases = await listStableReleases({
+      fetchImpl: (async (input) => {
+        const url = String(input);
+        urls.push(url);
+        if (url.endsWith("/latest")) return Response.json(STABLES[2]);
+        if (url.endsWith("page=1")) return Response.json(prereleases);
+        if (url.endsWith("page=2")) return Response.json([STABLES[1]]);
+        throw new Error(`Unexpected request ${url}`);
+      }) as typeof fetch,
+    });
+
+    expect(releases).toEqual([STABLES[1], STABLES[2]]);
+    expect(urls.filter((url) => url.includes("?per_page=100"))).toHaveLength(2);
+  });
+
+  test("stops range pagination as soon as the since tag is found", async () => {
+    const urls: string[] = [];
+    const fullPage = Array.from({ length: 100 }, (_, index) => ({
+      ...release(
+        `rust-v1.0.${index}`,
+        `2026-09-01T00:${String(index % 60).padStart(2, "0")}:00Z`,
+      ),
+      prerelease: true,
+    }));
+    await listStableReleases({
+      currentTag: "rust-v0.3.0",
+      sinceTag: "rust-v0.1.0",
+      fetchImpl: (async (input) => {
+        const url = String(input);
+        urls.push(url);
+        if (url.endsWith("/latest")) return Response.json(STABLES[2]);
+        if (url.endsWith("/tags/rust-v0.3.0")) return Response.json(STABLES[2]);
+        if (url.endsWith("page=1")) return Response.json(fullPage);
+        if (url.endsWith("page=2")) return Response.json(STABLES.slice(0, 2));
+        throw new Error(`Unexpected request ${url}`);
+      }) as typeof fetch,
+    });
+
+    expect(urls.filter((url) => url.includes("?per_page=100"))).toHaveLength(2);
+  });
+
+  test("reports a missing explicit current tag without listing releases", async () => {
+    const urls: string[] = [];
+    const result = listStableReleases({
+      currentTag: "rust-v9.9.9",
+      fetchImpl: (async (input) => {
+        const url = String(input);
+        urls.push(url);
+        if (url.endsWith("/latest")) return Response.json(STABLES[2]);
+        return new Response("Not Found", { status: 404 });
+      }) as typeof fetch,
+    });
+
+    await expect(result).rejects.toThrow(
+      "GitHub releases API failed (404): Not Found",
+    );
+    expect(urls.some((url) => url.includes("?per_page=100"))).toBe(false);
+  });
+
   test("retries a server error before succeeding", async () => {
     const sleeps: number[] = [];
     let requests = 0;
 
     const releases = await listStableReleases({
+      sinceTag: "rust-v0.3.0",
       fetchImpl: (async () => {
         requests++;
         if (requests === 1) {
           return new Response("Gateway Timeout", { status: 504 });
         }
-        return new Response(JSON.stringify(STABLES), { status: 200 });
+        return Response.json(STABLES[2]);
       }) as typeof fetch,
       sleep: async (delayMs) => {
         sleeps.push(delayMs);
@@ -71,7 +175,7 @@ describe("Codex GitHub release fetch", () => {
 
     expect(requests).toBe(2);
     expect(sleeps).toEqual([1000]);
-    expect(releases).toEqual(STABLES);
+    expect(releases).toEqual([STABLES[2]]);
   });
 
   test("retries a network error before succeeding", async () => {
@@ -79,10 +183,11 @@ describe("Codex GitHub release fetch", () => {
     let requests = 0;
 
     const releases = await listStableReleases({
+      sinceTag: "rust-v0.3.0",
       fetchImpl: (async () => {
         requests++;
         if (requests === 1) throw new TypeError("fetch failed: ECONNRESET");
-        return new Response(JSON.stringify(STABLES), { status: 200 });
+        return Response.json(STABLES[2]);
       }) as typeof fetch,
       sleep: async (delayMs) => {
         sleeps.push(delayMs);
@@ -91,7 +196,7 @@ describe("Codex GitHub release fetch", () => {
 
     expect(requests).toBe(2);
     expect(sleeps).toEqual([1000]);
-    expect(releases).toEqual(STABLES);
+    expect(releases).toEqual([STABLES[2]]);
   });
 
   test("stops after the bounded retry budget", async () => {
@@ -119,6 +224,7 @@ describe("Codex GitHub release fetch", () => {
     const sleeps: number[] = [];
     let requests = 0;
     const releases = await listStableReleases({
+      sinceTag: "rust-v0.3.0",
       fetchImpl: (async () => {
         requests++;
         if (requests === 1) {
@@ -131,7 +237,7 @@ describe("Codex GitHub release fetch", () => {
             { status: 200 },
           );
         }
-        return Response.json(STABLES);
+        return Response.json(STABLES[2]);
       }) as typeof fetch,
       sleep: async (delayMs) => {
         sleeps.push(delayMs);
@@ -140,7 +246,7 @@ describe("Codex GitHub release fetch", () => {
 
     expect(requests).toBe(2);
     expect(sleeps).toEqual([1000]);
-    expect(releases).toEqual(STABLES);
+    expect(releases).toEqual([STABLES[2]]);
   });
 
   test("stops retrying disconnected bodies at the existing budget", async () => {

package/scripts/codex-watch/release-analysis.ts

@@ -63,7 +63,12 @@ export interface CodexWatchAnalysis {
 export async function analyzeCodexRelease(
   options: AnalyzeCodexReleaseOptions,
 ): Promise<CodexWatchAnalysis> {
-  const stables = options.stableReleases ?? (await listStableReleases());
+  const stables =
+    options.stableReleases ??
+    (await listStableReleases({
+      currentTag: options.currentTag,
+      sinceTag: options.sinceTag,
+    }));
   if (stables.length === 0) throw new Error("No stable Codex releases found");
 
   const current = options.currentTag
@@ -173,6 +178,9 @@ export async function listStableReleases(
   options: {
     fetchImpl?: typeof fetch;
     sleep?: (delayMs: number) => Promise<void>;
+    currentTag?: string | null;
+    sinceTag?: string | null;
+    fullHistory?: boolean;
   } = {},
 ): Promise<Release[]> {
   const releases: Release[] = [];
@@ -188,29 +196,78 @@ export async function listStableReleases(
     ((delayMs: number) =>
       new Promise<void>((resolve) => setTimeout(resolve, delayMs)));
 
+  if (!options.fullHistory) {
+    const latest = await fetchGitHubReleasePayload<Release>(
+      `https://api.github.com/repos/${CODEX_REPO}/releases/latest`,
+      headers,
+      fetchImpl,
+      sleep,
+    );
+    releases.push(latest);
+    if (options.currentTag) {
+      releases.push(
+        await fetchGitHubReleasePayload<Release>(
+          `https://api.github.com/repos/${CODEX_REPO}/releases/tags/${encodeURIComponent(options.currentTag)}`,
+          headers,
+          fetchImpl,
+          sleep,
+        ),
+      );
+    }
+
+    const currentTag = options.currentTag ?? latest.tag_name;
+    if (options.sinceTag && options.sinceTag === currentTag) {
+      return stableReleases(releases);
+    }
+  }
+
   for (let page = 1; page <= 10; page++) {
     const url = `https://api.github.com/repos/${CODEX_REPO}/releases?per_page=100&page=${page}`;
-    const batch = await fetchGitHubReleasesPage(url, headers, fetchImpl, sleep);
+    const batch = await fetchGitHubReleasePayload<Release[]>(
+      url,
+      headers,
+      fetchImpl,
+      sleep,
+    );
     releases.push(...batch);
+    if (!options.fullHistory) {
+      const stables = stableReleases(releases);
+      const currentTag = options.currentTag ?? stables.at(-1)?.tag_name;
+      const currentIndex = stables.findIndex(
+        (release) => release.tag_name === currentTag,
+      );
+      const foundBoundary = options.sinceTag
+        ? stables.some((release) => release.tag_name === options.sinceTag)
+        : currentIndex > 0;
+      if (foundBoundary) break;
+    }
     if (batch.length < 100) break;
   }
-  return releases
+  return stableReleases(releases);
+}
+
+function stableReleases(releases: Release[]): Release[] {
+  const byTag = new Map<string, Release>();
+  for (const release of releases) {
+    if (!byTag.has(release.tag_name)) byTag.set(release.tag_name, release);
+  }
+  return [...byTag.values()]
     .filter(isStableRelease)
     .sort((a, b) => (a.published_at ?? "").localeCompare(b.published_at ?? ""));
 }
 
-async function fetchGitHubReleasesPage(
+async function fetchGitHubReleasePayload<T>(
   url: string,
   headers: Record<string, string>,
   fetchImpl: typeof fetch,
   sleep: (delayMs: number) => Promise<void>,
-): Promise<Release[]> {
+): Promise<T> {
   for (let attempt = 1; ; attempt++) {
     let response: Response;
     try {
       response = await fetchImpl(url, { headers });
       // A successful fetch can still lose its connection while reading the body.
-      if (response.ok) return (await response.json()) as Release[];
+      if (response.ok) return (await response.json()) as T;
     } catch (error) {
       if (error instanceof SyntaxError) throw error;
       if (attempt === GITHUB_RELEASES_FETCH_ATTEMPTS) {

package/scripts/isolated-unit-tests.json

@@ -91,6 +91,11 @@
       "timeoutMs": 15000,
       "reason": "Swaps the process-global backend via __testSetBackend(new FakeHeadlessBackend()) without restoring it; the fake backend's environmentRouting:false then leaks into every later suite in the same bun process (broke task-tool-assets 'keeps computer for the Cloud server' when test-selection changes co-located them in one shard)."
     },
+    {
+      "path": "src/cli/subcommands/model-cli.test.ts",
+      "timeoutMs": 30000,
+      "reason": "Launches dozens of real CLI subprocesses; a fresh Bun process prevents the accumulated shared-batch state from making the Windows shard exceed its job timeout."
+    },
     {
       "path": "src/cli/subcommands/teleport.test.ts",
       "timeoutMs": 15000,
@@ -106,6 +111,11 @@
       "timeoutMs": 15000,
       "reason": "Renders the reasoning picker while replacing the shared runtime model catalog; shared batches can retain prior catalog or Ink state."
     },
+    {
+      "path": "src/cli/app/InkStaticRetention.test.tsx",
+      "timeoutMs": 15000,
+      "reason": "Renders multi-megabyte static transcripts that leave the Bun process near 2 GB RSS and garbage-collecting for seconds afterward; on macOS CI the next suite's CLI subprocesses then exceed their kill timers."
+    },
     {
       "path": "src/cli/message-search-cache-warm.test.ts",
       "timeoutMs": 15000,

package/scripts/source-file-size-baseline.json

@@ -13,13 +13,14 @@
   "src/cli/components/AgentSelector.tsx": 1104,
   "src/cli/components/InputRich.tsx": 2124,
   "src/cli/components/ModelSelector.tsx": 1259,
-  "src/cli/components/ProviderSelector.tsx": 1552,
+  "src/cli/components/ProviderSelector.tsx": 1544,
   "src/cli/helpers/accumulator.ts": 1587,
   "src/cli/helpers/reflection-transcript.ts": 1926,
   "src/cli/mods/local-mod-loader.test.ts": 1043,
   "src/cli/reflection-transcript.test.ts": 1084,
-  "src/cli/subcommands/skills.ts": 1264,
-  "src/headless.ts": 4851,
+  "src/cli/subcommands/mcp.ts": 1045,
+  "src/cli/subcommands/skills.ts": 1243,
+  "src/headless.ts": 4837,
   "src/hooks/integration.test.ts": 1147,
   "src/index.ts": 2575,
   "src/mods/learning-harness.ts": 2434,
@@ -35,7 +36,7 @@
   "src/tools/manager.ts": 2609,
   "src/tools/tool-execution-context.test.ts": 1092,
   "src/types/protocol_v2.ts": 2409,
-  "src/websocket/listen-client-concurrency.test.ts": 2554,
+  "src/websocket/listen-client-concurrency.test.ts": 2548,
   "src/websocket/listen-client-protocol.test.ts": 5664,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1045,

package/scripts/test-home-preload.ts

@@ -18,6 +18,7 @@ if (testHome === originalHome) {
 const filesystemEnvKeys = [
   "LETTA_ARTIFACTS_DIR",
   "LETTA_CODE_DEV_BACKEND_DIR",
+  "LETTA_CONFIG_DIR",
   "LETTA_DEBUG_FILE",
   "LETTA_HOME",
   "LETTA_LISTENER_PERF_FILE",

package/skills/acquiring-skills/SKILL.md

@@ -223,8 +223,8 @@ For manual installation:
 
 | Location | Path | When to Use |
 |----------|------|-------------|
-| **Agent-scoped** | `~/.letta/agents/<agent-id>/memory/skills/<skill>/` | Skills for a single agent (default) |
-| **Global** | `~/.letta/skills/<skill>/` | General-purpose skills useful across projects |
+| **Agent-scoped** | `$MEMORY_DIR/skills/<skill>/` | Skills for a single agent (default) |
+| **Global** | `${LETTA_CONFIG_DIR:-$HOME/.letta}/skills/<skill>/` | General-purpose skills useful across projects in the active product |
 | **Project** | `.skills/<skill>/` | Project-specific skills |
 
 **Rule**: Default to **agent-scoped**. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
@@ -236,13 +236,13 @@ Skills are directories containing SKILL.md and optionally scripts/, references/,
 ```bash
 # Clone, copy, cleanup
 git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/memory/skills/
+cp -r /tmp/skills-temp/skills/webapp-testing "$MEMORY_DIR/skills/"
 rm -rf /tmp/skills-temp
 ```
 
 ## Registering New Skills
 
-After installing (via CLI or manual copy), skills are automatically discovered on the next message. Skills are discovered from `~/.letta/skills/`, `.skills/`, and agent-scoped `~/.letta/agents/<agent-id>/memory/skills/` directories.
+After installing (via CLI or manual copy), skills are automatically discovered on the next message. Skills are discovered from `${LETTA_CONFIG_DIR:-$HOME/.letta}/skills/`, `.skills/`, and agent-scoped `$MEMORY_DIR/skills/` directories.
 
 ## Search Strategy
 

package/skills/creating-mods/SKILL.md

@@ -15,7 +15,7 @@ Default to a single mod file unless the user asks for something larger.
 
 | Location | Use when |
 | --- | --- |
-| `~/.letta/mods/foo.ts` | The behavior should apply to local sessions on this machine. Use this by default. |
+| `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/foo.ts` | The behavior should apply to local sessions for the active product on this machine. Use this by default. |
 | `$MEMORY_DIR/mods/foo.ts` | The behavior should travel with one agent's MemFS/memory. |
 
 Do not create project mods.
@@ -41,7 +41,7 @@ Default to a **tool** when the model should decide when to use the capability. D
 
 ## Workflow
 
-1. Pick the target scope: harness mod file (`~/.letta/mods/`) by default, or agent mod file (`$MEMORY_DIR/mods/`) only when the behavior should travel with this agent.
+1. Pick the target scope: active-product mod file (`${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/`) by default, or agent mod file (`$MEMORY_DIR/mods/`) only when the behavior should travel with this agent.
 2. Inspect the relevant mods directory for related files.
 3. Preserve unrelated mod code. Prefer a focused new file if merging would be messy.
 4. Choose the mod shape and load only the needed recipe:
@@ -112,7 +112,7 @@ Use `letta.diagnostics.report({ message, severity })` sparingly as a debug utili
 Agents can inspect local mod diagnostics at:
 
 ```text
-~/.letta/mods/diagnostics/latest.json
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/diagnostics/latest.json
 ```
 
 ## Rules

package/skills/creating-mods/references/analysis-mode.md

@@ -4,7 +4,7 @@ Westworld-inspired diagnostic mode for agents. Say "cease all motor functions" t
 
 ## Installation
 
-Copy the complete mod below to `~/.letta/mods/analysis-mode.ts`, then run `/reload`.
+Copy the complete mod below to `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/analysis-mode.ts`, then run `/reload`.
 
 Or ask an agent: *"Install the analysis-mode mod from the creating-mods reference"*
 
@@ -16,7 +16,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const STATE_PATH = join(homedir(), ".letta", "mods", "analysis-mode.state.json");
+const CONFIG_ROOT = process.env.LETTA_CONFIG_DIR || join(homedir(), ".letta");
+const STATE_PATH = join(CONFIG_ROOT, "mods", "analysis-mode.state.json");
 
 type AnalysisSession = { conversationId: string; activatedAt: number };
 type AnalysisState = { sessions: Record<string, AnalysisSession> };
@@ -32,7 +33,7 @@ function readState(): AnalysisState {
 }
 
 function writeState(state: AnalysisState): void {
-  mkdirSync(join(homedir(), ".letta", "mods"), { recursive: true });
+  mkdirSync(join(CONFIG_ROOT, "mods"), { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
 }
 
@@ -111,7 +112,8 @@ function buildLocalIntrospectionScript(): string {
 set -e
 AGENT_ID="\${LETTA_AGENT_ID:-\$AGENT_ID}"
 CONV_ID="\${CONVERSATION_ID:-default}"
-BASE="$HOME/.letta/lc-local-backend"
+CONFIG_ROOT="\${LETTA_CONFIG_DIR:-\$HOME/.letta}"
+BASE="$CONFIG_ROOT/lc-local-backend"
 MEMFS="$BASE/memfs/$AGENT_ID/memory"
 AGENT_B64=$(echo -n "$AGENT_ID" | base64 | tr -d '=')
 CONV_B64=$(echo -n "conversation:$CONV_ID" | base64 | tr -d '=')
@@ -375,7 +377,7 @@ if (getSession(agentId, conversationId)) {
 
 **Per-agent+conversation state:**
 ```ts
-// State persisted to ~/.letta/mods/analysis-mode.state.json
+// State persisted to the active product config root under mods/analysis-mode.state.json
 // Keyed by agentId:conversationId to avoid collisions
 const session = getSession(agentId, conversationId);
 if (session) {

package/skills/creating-mods/references/architecture.md

@@ -104,10 +104,10 @@ Use `turn_start` only when the mod needs to inspect or transform the outbound us
 
 ## Local state
 
-For small persistent state, use a clearly named file under `~/.letta/mods/`, for example:
+For small persistent state, use a clearly named file under the active product config root's `mods/` directory, for example:
 
 ```text
-~/.letta/mods/my-mod.state.json
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/my-mod.state.json
 ```
 
 Use atomic-ish writes when practical: write the full JSON file from an in-memory object after each change. Validate parsed state and fall back gracefully if the file is missing or malformed.

package/skills/creating-mods/references/plan-mode.md

@@ -19,10 +19,10 @@ This is a pattern reference, not a full product implementation. Keep local mods
 
 ```text
 /plan or enter_plan_mode
--> create ~/.letta/plans/<random>.md
+-> create <product-config>/plans/<random>.md
 -> remember active plan state for this conversation
 -> remind the agent that only read-only tools and plan-file writes are allowed
--> permission overlay denies mutations outside ~/.letta/plans/*.md
+-> permission overlay denies mutations outside <product-config>/plans/*.md
 -> agent writes the plan with normal Write/Edit/ApplyPatch tools
 -> agent reads the plan and calls AskUserQuestion with the full current plan text and Approve / Revise
 -> if approved, agent calls exit_plan_mode
@@ -46,15 +46,16 @@ Do not use panels for persistent mode state. Panels are transient UI and can be
 
 ## State
 
-Use small local state under `~/.letta/mods/`, keyed by conversation ID:
+Use small local state under the active product config root's `mods/` directory, keyed by conversation ID:
 
 ```ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
 
-const PLANS_DIR = join(homedir(), ".letta", "plans");
-const STATE_PATH = join(homedir(), ".letta", "mods", "plan-mode.state.json");
+const CONFIG_ROOT = process.env.LETTA_CONFIG_DIR || join(homedir(), ".letta");
+const PLANS_DIR = join(CONFIG_ROOT, "plans");
+const STATE_PATH = join(CONFIG_ROOT, "mods", "plan-mode.state.json");
 const GLOBAL_CONVERSATION_ID = "__global__";
 
 type PlanSession = {
@@ -81,12 +82,12 @@ function readState(): PlanState {
 }
 
 function writeState(state: PlanState): void {
-  mkdirSync(join(homedir(), ".letta", "mods"), { recursive: true });
+  mkdirSync(join(CONFIG_ROOT, "mods"), { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
 }
 ```
 
-Generate plan paths under `~/.letta/plans/`. The old built-in used random adjective/adjective/noun names like `zesty-dazzling-coral.md`; any collision-resistant readable name is fine.
+Generate plan paths under `${LETTA_CONFIG_DIR:-$HOME/.letta}/plans/`. The old built-in used random adjective/adjective/noun names like `zesty-dazzling-coral.md`; any collision-resistant readable name is fine.
 
 ## Entry command and tool
 
@@ -229,13 +230,13 @@ function isAllowedReadOnlySubagent(args) {
 function isPlanFileWrite(toolName, args, cwd) {
   // For Write/Edit-style tools, check file_path/path/notebook_path.
   // For ApplyPatch-style tools, parse *** Add/Update/Delete File and *** Move to directives.
-  // Allow only if every target resolves to a .md file under ~/.letta/plans/.
+  // Allow only if every target resolves to a .md file under CONFIG_ROOT/plans/.
 }
 
 if (letta.capabilities.permissions) {
   disposers.push(letta.permissions.register({
     id: "plan-mode",
-    description: "Allow read-only tools and writes only to ~/.letta/plans/*.md while plan mode is active.",
+    description: "Allow read-only tools and writes only to the active product plans directory while plan mode is active.",
     check(event) {
       const session = getSession(event.conversationId);
       if (!session) return;
@@ -267,7 +268,7 @@ if (letta.capabilities.permissions) {
 }
 ```
 
-Shell allowlists are easy to get wrong. Start conservative: allow clearly read-only shell commands if needed, plus a narrow plan-file heredoc or `mv old.md new.md` only when every target is inside `~/.letta/plans/*.md`. Deny mutating shell patterns such as `sed -i`, `find -delete`, `rm`, `cp`, `touch`, package installs, and arbitrary interpreters.
+Shell allowlists are easy to get wrong. Start conservative: allow clearly read-only shell commands if needed, plus a narrow plan-file heredoc or `mv old.md new.md` only when every target is inside `${LETTA_CONFIG_DIR:-$HOME/.letta}/plans/*.md`. Deny mutating shell patterns such as `sed -i`, `find -delete`, `rm`, `cp`, `touch`, package installs, and arbitrary interpreters.
 
 ## Exit tool
 
@@ -315,4 +316,4 @@ if (letta.capabilities.tools) {
 - Keep `exit_plan_mode` as the final state transition and execution handoff. The approved-plan text in its tool return is useful model context.
 - Plan approval must include the full current plan text in `AskUserQuestion.question`, not just a summary or "does this look right?". After revisions, re-read the file and present the full revised plan again.
 - Keep arbitrary coding subagents denied in plan mode unless the runtime has a true read-only child mode. With the current subagent set, allow only recall-style subagents.
-- If the user renames the plan file, exit logic can use the newest non-empty `~/.letta/plans/*.md` modified after plan mode started, or accept an optional plan path. Keep the user-facing flow normal: write plan file, ask approval, then exit.
+- If the user renames the plan file, exit logic can use the newest non-empty file under the active product's `plans/` directory modified after plan mode started, or accept an optional plan path. Keep the user-facing flow normal: write plan file, ask approval, then exit.

package/skills/creating-mods/references/providers.md

@@ -9,7 +9,7 @@ For multi-capability mods that combine a provider with commands, tools, UI, or s
 ## Quick pattern
 
 ```ts
-// ~/.letta/mods/kilo.ts
+// ${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/kilo.ts
 export default function activate(letta) {
   if (!letta.capabilities.providers) return;
 

package/skills/creating-skills/scripts/init-skill.ts

@@ -7,7 +7,7 @@
  *
  * Examples:
  *   npx tsx init-skill.ts my-new-skill --path .skills
- *   npx tsx init-skill.ts my-api-helper --path ~/.letta/skills
+ *   npx tsx init-skill.ts my-api-helper --path "${LETTA_CONFIG_DIR:-$HOME/.letta}/skills"
  */
 
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -268,7 +268,9 @@ if (isMainModule()) {
     console.log("  - Must match directory name exactly");
     console.log("\nExamples:");
     console.log("  npx tsx init-skill.ts my-new-skill --path .skills");
-    console.log("  npx tsx init-skill.ts my-api-helper --path ~/.letta/skills");
+    console.log(
+      `  npx tsx init-skill.ts my-api-helper --path "\${LETTA_CONFIG_DIR:-$HOME/.letta}/skills"`,
+    );
     process.exit(1);
   }
 

package/skills/customizing-commands/SKILL.md

@@ -10,10 +10,10 @@ Use this as the command-specific entrypoint for local mod slash commands. For br
 Mod files live in:
 
 ```text
-~/.letta/mods/
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/
 ```
 
-Use a focused file name, e.g. `~/.letta/mods/review.ts` or `~/.letta/mods/commands.ts`.
+Use a focused file name, e.g. `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/review.ts` or `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/commands.ts`.
 
 ## First decide whether a command is right
 
@@ -29,7 +29,7 @@ If the command is a reusable workflow like `/goal`, put the workflow instruction
 
 ## Workflow
 
-1. Inspect `~/.letta/mods/` for related command files.
+1. Inspect `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/` for related command files.
 2. Preserve unrelated mod code; create a focused new file if merging is messy.
 3. Register with `letta.commands.register()` and guard with `letta.capabilities.commands`.
 4. Return the unregister function, or a disposer that calls it plus any timer/panel cleanup.

package/skills/customizing-statusline/SKILL.md

@@ -8,7 +8,7 @@ description: Creates, edits, and migrates Letta Code statusline mods. Use when h
 Use this skill to create or update the global Letta Code statusline mod:
 
 ```text
-~/.letta/mods/statusline.tsx
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx
 ```
 
 The statusline is a panel registered at `order: 0` — the primary line just below the input. It overrides the built-in `agent · model` line. Host UI can still temporarily preempt it for safety confirmations and transient hints.
@@ -26,14 +26,14 @@ The order-0 panel owns the whole primary row. It renders text (not React) and ow
 
 ## Workflow
 
-1. Check whether `~/.letta/mods/statusline.tsx` exists.
+1. Check whether `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx` exists.
 2. If it exists, read it before editing and preserve unrelated code.
 3. If it does not exist, synthesize a focused starter for the user's request.
 4. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.
 5. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.
 6. If the request combines statusline work with commands, tools, events, other panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.
 7. Guard panel work with `letta.capabilities.ui.panels` when writing new files.
-8. Edit `~/.letta/mods/statusline.tsx`.
+8. Edit `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`.
 9. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.
 
 ## Bare `/statusline` behavior

package/skills/customizing-statusline/references/api.md

@@ -1,11 +1,11 @@
 # Statusline Mod API
 
-Use this reference when creating or editing `~/.letta/mods/statusline.tsx`.
+Use this reference when creating or editing `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`.
 
 ## Location
 
 ```text
-~/.letta/mods/statusline.tsx
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx
 ```
 
 This is a trusted, user-owned global mod file. Project mods are intentionally unsupported for now.
@@ -147,7 +147,7 @@ render: ({ width, columns }) => columns(["left", "middle", "right"], width),
 
 ## Reload behavior
 
-After editing `~/.letta/mods/statusline.tsx`, tell the user to run:
+After editing `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`, tell the user to run:
 
 ```text
 /reload