@letta-ai/letta-code 0.19.6 → 0.19.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.19.6",
+  "version": "0.19.8",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -64,6 +64,7 @@
     "typescript": "^5.0.0"
   },
   "scripts": {
+    "prepare": "node .husky/install.mjs",
     "lint": "bunx --bun @biomejs/biome@2.2.5 check src",
     "fix": "bunx --bun @biomejs/biome@2.2.5 check --write src",
     "typecheck": "tsc --noEmit",

package/skills/context_doctor/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: Context Doctor
+id: context_doctor
+description: Identify and repair degradation in system prompt, external memory, and skills preventing you from following instructions or remembering information as well as you should.
+---
+
+# Context Doctor
+Your context is managed by yourself, along with additional memory subagents. Your context includes: 
+- Your system prompt and instructions (contained in `system/`)
+- Your external memory 
+- Your skills (procedural memory) 
+
+Over time, context can degrade — bloat and poor prompt quality erode your ability to remember the right things and follow instructions properly. This skill helps you identify issues with your context and repair them collaboratively with the user.
+
+## Operating Procedure
+
+### Step 1: Identifying and resolving context issues 
+Explore your memory files to identify issues. Consider what is confusing about your own prompts and context, and resolve the issues.
+
+Below are additional common issues with context and how they can be resolved: 
+
+### Context quality 
+Your system prompt and memory filesystem should be well structured and clear. 
+
+**Questions to ask**: 
+- Is my system prompt clear and well formatted? 
+- Are there wasteful or unnecessary tokens in my prompts? 
+- Do I know when to load which files in my memory filesystem? 
+
+#### System prompt bloat 
+Prompts that are compiled as part of the system prompt (contained in `system/`) should only take up about 10% of the total context size, though this is a recommendation, not a hard requirement. Usually this means about 15-20k tokens. 
+
+Use the following script to evaluate the token usage of the system prompt: 
+```bash
+bun scripts/estimate_system_tokens.ts --memory-dir "$MEMORY_DIR"
+```
+
+**Questions to ask**:
+- Do all these tokens need to be passed to the LLM on every turn, or can they be retrieved when needed through being part of external memory of my conversation history? 
+- Do any of these prompts confuse or distract me? 
+- Am I able to effectively follow critical instructions (e.g. persona information, user preferences) given the current prompt structure and contents? 
+
+**Solution**: Reduce the size of the system prompt if needed: 
+- Move files outside of `system/` so they are no longer part of the system prompt
+- Compact information to be more information dense or eliminate redundancy
+- Leverage progressive disclosure: move some context outside of `system/` and reference it to pull in dynamically
+
+**Scope**: You may refine, tighten, and restructure prompts to improve clarity and adherence — but do not change the intended semantics. The goal is better signal, not different behavior.
+- Do not alter persona-defining content (who you are, how you communicate)
+- Do not remove or change user identity or preferences (e.g. the human's name, their stated goals)
+- Do not rewrite instructions in ways that shift their meaning — only reduce noise and improve structure
+
+#### Context redundancy and unclear organization 
+The context in the memory filesystem should have a clear structure, with a well-defined purpose for each file. Memory file descriptions should be precise and non-overlapping. Their contents should be consistent with the description, and have non-overlapping content to other files. 
+
+**Questions to ask**: 
+- Do the descriptions make clear what file is for what? 
+- Do the contents of the file match the descriptions? (you can ask subagents to check)
+
+**Solution**: Read all memory files (use subagents for efficiency), then:
+- Consolidate redundant files
+- Reorganize files and rewrite descriptions to have clear separation of concerns
+- Avoid duplication by referencing common files from multiple places (e.g. `[[reference/api]]`)
+- Rewrite unclear or low-quality content
+
+#### Invalid context format
+Files in the memory filesystem must follow certain structural requirements: 
+- Must have a `system/persona.md`
+- Must NOT have overlapping file and folder names (e.g. `system/human.md` and `system/human/identity.md`) 
+- Must follow specification for skills (e.g. `skills/{skill_name}/`) with the format:
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+**Solution**: Reorganize files to follow the required structure
+
+### Poor use of progressive disclosure
+Only critical information should be in the system prompt, since it's passed on every turn. Use progressive disclosure so that context only *sometimes* needed can be dynamically retrieved.
+
+Files that are outside of `system/` are not part of the system prompt, and must be dynamically loaded. You must index your files to ensure your future self can discover them: for example, make sure that files have informative names and descriptions, or are referenced from parts of your system prompt. Otherwise, you will never discover the external context or make use of it. 
+
+**Solution**: 
+- Reference external skills from the relevant parts of in-context memory:
+```
+When running a migration, always use the skill [[skills/db-migrations]]
+```
+or external memory files: 
+```
+Sarah's active projects are: Letta Code [[projects/letta_code.md]] and Letta Cloud [[projects/letta_cloud]]
+```
+- Ensure that contents of files match the file name and descriptions 
+- Make sure your future self will be able to find and load external files when needed. 
+
+### Step 2: Implement context fixes
+Create a plan for what fixes you want to make, then implement them.
+
+Before moving on, verify:
+- [ ] System prompt token budget reviewed (target ~10% of context, usually 15-20k tokens)
+- [ ] No overlapping or redundant files remain
+- [ ] All file descriptions are unique, accurate, and match their contents
+- [ ] Moved-out knowledge has references from in-context memory so it can be discovered
+- [ ] No semantic changes to persona, user identity, or behavioral instructions
+
+### Step 3: Commit and push
+Review changes, then commit with a descriptive message:
+
+```bash
+cd $MEMORY_DIR
+git status                # Review what changed before staging
+git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
+git commit --author="<AGENT_NAME> <<ACTUAL_AGENT_ID>@letta.com>" -m "fix(doctor): <summary> 🏥
+
+<identified issues and implemented solutions>"
+
+git push
+```
+
+### Step 4: Final checklist and message
+Tell the user what issues you identitied, the fixes you made, the commit you made, and also recommend that they run `/recompile` to apply these changes to the current system prompt. 
+
+Before finishing make sure you: 
+- [ ] Resolved all the identified context issues
+- [ ] Pushed your changes successfully 
+- [ ] Told the user to run `/recompile` to refresh the system prompt and apply changes
+
+## Critical information 
+- **Ask the user about their goals for you, not the implementation**: You understand your own context best, and should follow the guidelines in this document. Do NOT ask the user about their structural preferences - the context is for YOU, not them. Ask them how they want YOU to behave or know instead. 

package/skills/context_doctor/scripts/estimate_system_tokens.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env bun
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getClient } from "../../../../agent/client";
+import { settingsManager } from "../../../../settings-manager";
+
+const BYTES_PER_TOKEN = 4;
+
+type FileEstimate = {
+  path: string;
+  tokens: number;
+};
+
+type ParsedArgs = {
+  memoryDir?: string;
+  agentId?: string;
+  top: number;
+};
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const parsed: ParsedArgs = { top: 20 };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--memory-dir") {
+      parsed.memoryDir = argv[i + 1];
+      i++;
+      continue;
+    }
+    if (arg === "--agent-id") {
+      parsed.agentId = argv[i + 1];
+      i++;
+      continue;
+    }
+    if (arg === "--top") {
+      const raw = argv[i + 1];
+      const value = Number.parseInt(raw ?? "", 10);
+      if (!Number.isNaN(value) && value >= 0) {
+        parsed.top = value;
+      }
+      i++;
+    }
+  }
+
+  return parsed;
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(Buffer.byteLength(text, "utf8") / BYTES_PER_TOKEN);
+}
+
+function normalizePath(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+function walkMarkdownFiles(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  const out: string[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git") {
+        continue;
+      }
+      out.push(...walkMarkdownFiles(full));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full);
+    }
+  }
+
+  return out;
+}
+
+function inferAgentIdFromMemoryDir(memoryDir: string): string | null {
+  const parts = normalizePath(memoryDir).split("/");
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === "agents" && parts[i + 1]?.startsWith("agent-")) {
+      return parts[i + 1];
+    }
+  }
+
+  const maybe = parts.at(-2);
+  return maybe?.startsWith("agent-") ? maybe : null;
+}
+
+async function resolveAgentId(
+  memoryDir: string,
+  cliAgentId?: string,
+): Promise<string> {
+  if (cliAgentId) {
+    return cliAgentId;
+  }
+
+  if (process.env.AGENT_ID) {
+    return process.env.AGENT_ID;
+  }
+
+  const inferred = inferAgentIdFromMemoryDir(memoryDir);
+  if (inferred) {
+    return inferred;
+  }
+
+  const fromSession = settingsManager.getEffectiveLastAgentId(process.cwd());
+  if (fromSession) {
+    return fromSession;
+  }
+
+  throw new Error(
+    "Unable to resolve agent ID. Pass --agent-id or set AGENT_ID.",
+  );
+}
+
+function formatNumber(value: number): string {
+  return value.toLocaleString("en-US");
+}
+
+async function main(): Promise<number> {
+  await settingsManager.initialize();
+
+  const args = parseArgs(process.argv.slice(2));
+  const memoryDir = args.memoryDir || process.env.MEMORY_DIR;
+
+  if (!memoryDir) {
+    throw new Error("Missing memory dir. Pass --memory-dir or set MEMORY_DIR.");
+  }
+
+  const systemDir = join(memoryDir, "system");
+  if (!existsSync(systemDir)) {
+    throw new Error(`Missing system directory: ${systemDir}`);
+  }
+
+  const agentId = await resolveAgentId(memoryDir, args.agentId);
+
+  // Use the SDK auth path used by letta-code (OAuth + API key handling via getClient).
+  const client = await getClient();
+  await client.agents.retrieve(agentId);
+
+  const files = walkMarkdownFiles(systemDir).sort();
+  const rows: FileEstimate[] = [];
+
+  for (const filePath of files) {
+    const text = readFileSync(filePath, "utf8");
+    const rel = normalizePath(filePath.slice(memoryDir.length + 1));
+    rows.push({ path: rel, tokens: estimateTokens(text) });
+  }
+
+  const estimatedTotalTokens = rows.reduce((sum, row) => sum + row.tokens, 0);
+
+  console.log("Estimated total tokens");
+  console.log(`  ${formatNumber(estimatedTotalTokens)}`);
+
+  console.log("\nPer-file token estimates");
+  console.log(`  ${"tokens".padStart(8)}  path`);
+
+  const sortedRows = [...rows].sort((a, b) => b.tokens - a.tokens);
+  for (const row of sortedRows.slice(0, Math.max(0, args.top))) {
+    console.log(`  ${formatNumber(row.tokens).padStart(8)}  ${row.path}`);
+  }
+
+  return 0;
+}
+
+main()
+  .then((code) => {
+    process.exit(code);
+  })
+  .catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });

package/skills/initializing-memory/SKILL.md

@@ -16,23 +16,23 @@ If you are running as a background subagent (you cannot use AskUserQuestion):
 - Use reasonable defaults for all preferences
 - Any specific overrides will be provided in your initial prompt
 
-## Your Goal: Explode Into 15-25 Hierarchical Files
+## Your Goal: Organize Into a Hierarchical Memory Structure
 
-Your goal is to **explode** memory into a **deeply hierarchical structure of 15-25 small, focused files**.
+Your goal is to **organize** memory into a **deeply hierarchical structure of small, focused files**.
 
 ### Target Output
 
 | Metric | Target |
 |--------|--------|
-| **Total files** | 15-25 (aim for ~20) |
-| **Max lines per file** | ~40 lines (split if larger) |
-| **Hierarchy depth** | 2-3 levels using `/` naming (e.g., `project/tooling/bun.md`) |
+| **Total files** | Enough focused files to cover distinct concepts without bloating any single file |
+| **File size** | Keep files concise and split when they become unwieldy |
+| **Hierarchy depth** | Use nested `/` paths whenever they improve clarity (e.g., `project/tooling/bun.md`) |
 | **Nesting requirement** | Every new file MUST be nested under a parent using `/` |
 
 **Anti-patterns to avoid:**
-- ❌ Ending with only 3-5 large files
+- ❌ Ending with only a few large files
 - ❌ Flat naming (all files at top level)
-- ❌ Mega-files with 10+ sections
+- ❌ Mega-files with many unrelated sections
 
 ## Memory Filesystem Integration
 
@@ -45,27 +45,27 @@ Your memory is a git-backed filesystem at `~/.letta/agents/<agent-id>/`. The act
 - The filesystem tree (all file paths + metadata) is always visible regardless of location
 - You can use bash commands (`ls`, `mkdir`, `mv`, `git`) to organize files
 - You MUST create a **deeply hierarchical file structure** — flat naming is NOT acceptable
-- **Target: 15-25 files in system/**, with additional reference files outside as needed
+- Create as many files as needed for clarity in `system/`, with additional reference files outside as needed
 
 **MANDATORY principles for hierarchical organization:**
 
 | Requirement | Target |
 |-------------|--------|
-| **Total files** | 15-25 files (aim for ~20) |
-| **Max lines per file** | ~40 lines (split if larger) |
-| **Hierarchy depth** | 2-3 levels using `/` naming |
+| **Total files** | Enough focused files to avoid monoliths while staying maintainable |
+| **File size** | Keep files concise and split when they become unwieldy |
+| **Hierarchy depth** | Use meaningful nesting with `/` naming where it helps organization |
 | **Nesting requirement** | EVERY new file MUST use `/` naming (no flat files) |
 
 **Anti-patterns to avoid:**
-- ❌ Creating only 3-5 large files
+- ❌ Creating only a few large files
 - ❌ Flat naming (all files at top level like `project-commands.md`)
-- ❌ Mega-files with 10+ sections
+- ❌ Mega-files with many unrelated sections
 
 **Rules:**
-- Use **2-3 levels of nesting** for ALL files (e.g., `project/tooling/bun.md`)
-- Keep files **focused and small** (~40 lines max per file)
+- Use clear nested paths for files whenever hierarchy improves discoverability (e.g., `project/tooling/bun.md`)
+- Keep files **focused and concise**
 - Use **descriptive paths** that make sense when you see just the filename
-- Split when a file has **2+ concepts** (be aggressive)
+- Split when a file starts mixing multiple concepts (be aggressive)
 
 **Example target structure (what success looks like):**
 
@@ -93,7 +93,7 @@ system/
     └── behavior.md               # How to behave
 ```
 
-This example has **~20 files** with **3 levels of hierarchy**. Your output should look similar.
+This example is illustrative. Your output should match the project’s actual complexity and the user’s needs.
 
 This approach makes memory more **scannable**, **maintainable**, and **shareable** with other agents.
 
@@ -319,7 +319,7 @@ You should ask these questions at the start (bundle them together in one AskUser
 2. **Identity**: "Which contributor are you?" (You can often infer this from git logs - e.g., if git shows "cpacker" as a top contributor, ask "Are you cpacker?")
 3. **Related repos**: "Are there other repositories I should know about and consider in my research?" (e.g., backend monorepo, shared libraries)
 4. **Historical sessions** (include this question if history data was found in step 2): "I found Claude Code / Codex history on your machine. Should I analyze it to learn your preferences, coding patterns, and project context? This significantly improves how I work with you but uses additional time and tokens." Options: "Yes, analyze history" / "Skip for now". Use "History" as the header.
-5. **Memory updates**: "How often should I check if I should update my memory?" with options "Frequent (every 3-5 turns)" and "Occasional (every 8-10 turns)". This should be a binary question with "Memory" as the header.
+5. **Memory updates**: "How often should I check whether to update memory?" with options "Frequent" and "Occasional". This should be a binary question with "Memory" as the header.
 6. **Communication style**: "Terse or detailed responses?"
 7. **Any specific rules**: "Rules I should always follow?"
 
@@ -364,11 +364,11 @@ mkdir -p ~/.letta/agents/<agent-id>/memory/system/human/prefs
 - **Every new file MUST use `/` naming** - no flat files allowed
 - Use `/` for hierarchy: `project/tooling/testing` (not `project-tooling-testing`)
 - File path determines the memory label: `system/project/overview.md` → label `project/overview`
-- Keep files small and focused (~40 lines max)
+- Keep files small and focused
 - Use **descriptive frontmatter** — the `description` field helps your future self understand each file's purpose
 
 **Checkpoint before proceeding:**
-Count your proposed files. **If you have fewer than 15 files, go back and split more aggressively.**
+Review your proposed files and split further if the structure still feels too flat or monolithic.
 
 **Benefits:**
 - More scannable and maintainable
@@ -376,17 +376,17 @@ Count your proposed files. **If you have fewer than 15 files, go back and split
 - Natural progressive disclosure (load parent, then drill into children)
 - Works like a file system you're familiar with
 
-### Split Aggressively - Target 15-25 Files
+### Split Aggressively
 
-**Don't create monolithic files.** Your goal is **15-25 total files**. Be aggressive about splitting:
+**Don't create monolithic files.** Be aggressive about splitting when it improves clarity:
 
 **Split when:**
-- A file has **40+ lines** (lower threshold than typical)
-- A file has **2+ distinct concepts** (not 3+, be aggressive)
+- A file becomes long enough that scanning it slows you down
+- A file mixes distinct concepts that would be clearer if separated
 - A section could stand alone as its own file
 - You can name the extracted content with a clear `/` path
 
-If a file is getting long (>40 lines), split it:
+If a file is getting long or conceptually mixed, split it:
 
 **Without memory filesystem** (flat naming - acceptable but not ideal):
 - `project-overview`: High-level description, tech stack, repo links
@@ -402,7 +402,7 @@ If a file is getting long (>40 lines), split it:
 - `project/architecture`: Directory structure, key modules
 - `project/gotchas`: Footguns, things to watch out for
 - **Must further nest**: `project/tooling/testing`, `project/tooling/linting`, `project/tooling/bun`
-- **Target 15-25 files total** - if commands is long, split into `project/commands/dev`, `project/commands/build`, etc.
+- If commands are broad, split into focused files like `project/commands/dev`, `project/commands/build`, etc.
 
 This makes memory more scannable and easier to update and share with other agents.
 
@@ -456,9 +456,9 @@ And add memory files that you think make sense to add (e.g., `project/architectu
 
 9. **Create/update memory structure** (can happen incrementally alongside steps 7-8):
    - **With memfs enabled**: Create a deeply hierarchical file structure using bash commands
-     - Use `mkdir -p` to create subdirectories (2-3 levels deep)
+     - Use `mkdir -p` to create subdirectories as needed
      - Create `.md` files for memory files using `/` naming
-     - **Target 15-25 total files** - be aggressive about splitting
+     - Be aggressive about splitting when it improves clarity
      - Use nested paths like `project/tooling/testing.md` (never flat like `project-testing.md`)
      - **Every new file MUST be nested** under a parent using `/`
      - **Every new file MUST be nested** under a parent using `/`
@@ -466,10 +466,9 @@ And add memory files that you think make sense to add (e.g., `project/architectu
    - **Don't wait until the end** - write findings as you go
    
    **Checkpoint verification:**
-   - After creating files, count them: `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`
-   - **If count < 15, you haven't split enough** - go back and split more
-   - Check maximum depth: `find ~/.letta/agents/<agent-id>/memory/system/ -type f | awk -F/ '{print NF}' | sort -n | tail -1`
-   - **Should be 2-3 levels deep** minimum
+   - Review file count and shape: `find ~/.letta/agents/<agent-id>/memory/system/ -type f | wc -l`
+   - Review hierarchy depth: `find ~/.letta/agents/<agent-id>/memory/system/ -type f | awk -F/ '{print NF}' | sort -n | tail -1`
+   - Verify the structure feels appropriately granular and discoverable for this project
 
 10. **Organize incrementally**:
    - Start with a basic structure
@@ -487,14 +486,13 @@ And add memory files that you think make sense to add (e.g., `project/architectu
 
 Before finishing, you MUST do a reflection step. **Your memory files are visible to you in your system prompt right now.** Look at them carefully and ask yourself:
 
-1. **File count check**: 
-   - Count your memory files: `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`
-   - **Do you have 15-25 files?** If not, you haven't split enough
-   - Too few files means they're too large - split more aggressively
+1. **File granularity check**: 
+   - Review your memory file set: `find ~/.letta/agents/<agent-id>/memory/system/ -type f | wc -l`
+   - Ask whether any files are still too broad and should be split
 
 2. **Hierarchy check**:
    - Are ALL new files using `/` naming? (e.g., `project/tooling/bun.md`)
-   - Do you have 2-3 levels of nesting minimum?
+   - Is the nesting meaningful for this project?
    - Are there any flat files like `project-commands.md`? **These should be nested**
 
 3. **Redundancy check**: Are there files with overlapping content? Either literally overlapping (due to errors while editing), or semantically/conceptually overlapping?
@@ -545,7 +543,7 @@ cat ~/.letta/agents/<agent-id>/memory/system/persona.md
 ❌ `project_testing.md` (underscore instead of `/`)
 
 ```bash
-# Create deeply nested directory structure (2-3 levels)
+# Create a nested directory structure suited to the content
 mkdir -p ~/.letta/agents/<agent-id>/memory/system/project/{tooling,architecture,conventions}
 mkdir -p ~/.letta/agents/<agent-id>/memory/system/human/prefs
 mkdir -p ~/.letta/agents/<agent-id>/memory/system/persona/behavior
@@ -584,22 +582,22 @@ mv ~/.letta/agents/<agent-id>/memory/system/project/tooling.md \
 
 Before you tell the user you're done, confirm:
 
-- [ ] **File count is 15-25** — Count your files with `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`. If < 15, split more.
+- [ ] **File granularity is appropriate** — verify no files are overly broad and split where useful.
 - [ ] **All new files use `/` naming** — No flat files like `my_notes.md` or `project-commands.md`
-- [ ] **Hierarchy is 2-3 levels deep** — e.g., `project/tooling/bun.md`, not just `project.md`
-- [ ] **No file exceeds ~40 lines** — Split larger files
-- [ ] **Each file has one concept** — If 2+ topics, split into 2+ files
+- [ ] **Hierarchy is meaningful** — nested paths should improve discoverability and organization.
+- [ ] **No file is bloated** — split files that are hard to scan quickly.
+- [ ] **Each file stays concept-focused** — split files that combine unrelated topics.
 - [ ] **Every file has real content** — No empty or pointer-only files
 - [ ] **Verify sync**: After creating files, check they appear in your memory files
 
-**If you have fewer than 15 files, you haven't split enough. Go back and split more.**
+**If the structure still feels flat or monolithic, split further until it is clear and maintainable.**
 
 ### Best Practices
 
 1. **Check memfs status first**: Look for `memory_filesystem` section in your system prompt
 2. **Start with directories**: Create the directory structure before populating files
-3. **Use short paths**: Aim for 2-3 levels (e.g., `project/tooling/testing`, not `project/dev/tools/testing/setup`)
-4. **Keep files focused**: Each file should cover one concept (~40 lines max)
+3. **Use practical paths**: prefer clear, readable nesting (e.g., `project/tooling/testing`) over unnecessarily deep paths.
+4. **Keep files focused**: each file should cover a coherent concept and remain easy to scan.
 5. **Every file should have real content** — no empty or pointer-only files
 6. **Be aggressive about splitting**: If in doubt, split. Too many small files is better than too few large ones.
 
@@ -636,15 +634,11 @@ LINES=$(wc -l < ~/.claude/history.jsonl)
 CHUNK_SIZE=$(( LINES / NUM_WORKERS + 1 ))
 split -l $CHUNK_SIZE ~/.claude/history.jsonl "$SPLIT_DIR/claude-"
 
-# Split Codex history (if it exists and is large enough to warrant splitting)
+# Split Codex history if it exists
 if [ -f ~/.codex/history.jsonl ]; then
   LINES=$(wc -l < ~/.codex/history.jsonl)
-  if [ "$LINES" -gt 100 ]; then
-    CHUNK_SIZE=$(( LINES / NUM_WORKERS + 1 ))
-    split -l $CHUNK_SIZE ~/.codex/history.jsonl "$SPLIT_DIR/codex-"
-  else
-    cp ~/.codex/history.jsonl "$SPLIT_DIR/codex-aa"
-  fi
+  CHUNK_SIZE=$(( LINES / NUM_WORKERS + 1 ))
+  split -l $CHUNK_SIZE ~/.codex/history.jsonl "$SPLIT_DIR/codex-"
 fi
 
 # Rename to .jsonl for clarity
@@ -702,12 +696,12 @@ After merging, **read every file in `system/`** and apply editorial judgment:
 
 Workers may have created files that don't fit the ideal hierarchy, or put too much into `system/`. Fix this:
 
-- Split oversized files (>40 lines) into focused sub-files
+- Split oversized or conceptually mixed files into focused sub-files
 - Move reference-quality content (detailed history, background context, evidence trails) to `reference/`
 - Ensure `system/` contains only what you genuinely need in-context: identity, active preferences, current project context, behavioral rules, gotchas
 - Merge near-duplicate files that cover the same topic
 
-**Rule of thumb**: If removing a file from `system/` wouldn't hurt your next 10 responses, it belongs in `reference/`.
+**Rule of thumb**: If removing a file from `system/` wouldn't materially affect near-term responses, it belongs in `reference/`.
 
 **3d. Clean up worktrees and branches:**