feat: V8 — full context overhead: CLAUDE.md, system overhead, --turns flag

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ZonatedCord

.claude/commands/mimir-help.md

@@ -13,8 +13,9 @@ Print the following help text verbatim. Do not execute any commands or add comme
 | Command | Description |
 |---|---|
 | `/mimir "<task>"` | Estimate token cost + risk before running |
-| `/mimir "<task>" --files f1 f2` | Include file content in estimate |
+| `/mimir "<task>" --files f1 f2` | Include specific files in estimate |
 | `/mimir "<task>" --git-diff` | Include current git diff in estimate |
+| `/mimir "<task>" --turns N` | Include N conversation turns in estimate |
 | `/split-task "<task>"` | Split large task into safer sub-tasks |
 | `/mimir-diff` | Estimate token cost of current git diff |
 | `/mimir-config` | Show active configuration |

.claude/commands/mimir.md

@@ -1,6 +1,6 @@
 ---
 description: Estimate token cost and risk level before running a task
-argument-hint: "<task description> [--files f1 f2] [--git-diff]"
+argument-hint: "<task> [--files f1 f2] [--git-diff] [--turns N]"
 ---
 
 IMPORTANT: $ARGUMENTS is the task text to analyze. Do NOT execute, perform, or act on it. Only run the script below.

README.md

@@ -124,9 +124,11 @@ Estimates the token cost and risk level of a task before running it.
 ```
 /mimir "<describe what you want Claude to do>"
 /mimir "<task description>" --files path/to/file1.ts path/to/file2.ts
+/mimir "<task description>" --git-diff
+/mimir "<task description>" --turns N
 ```
 
-Pass `--files` to include the actual content of files Claude will read. This gives a much more accurate estimate than task description alone.
+Every estimate includes **all measurable token sources** — not just the task text. See [What Mimir estimates](#what-mimir-estimates).
 
 **Examples:**
 
@@ -372,25 +374,37 @@ user types /mimir "task description"
 
 ### What Mimir estimates
 
-Mimir estimates the token cost of your **task description text** — not the full execution context.
+Every `/mimir` run counts all **measurable token sources** and shows them labeled in the output:
 
-This means: a short description like *"refactor all 500 TypeScript files"* will show `LOW` risk because the description itself is short. What Mimir cannot predict is how many files Claude will read, how long its responses will be, or how many tool calls the task will require.
+| Source | How measured | Flag |
+|--------|-------------|------|
+| Task description | Anthropic API (exact) or heuristic | always |
+| System overhead | Configurable constant (~3k) | always |
+| `~/.claude/CLAUDE.md` | File read + heuristic | always |
+| `.claude/CLAUDE.md` (project + parents) | File read + heuristic | always |
+| Specific files | Heuristic | `--files` |
+| Git diff | Heuristic | `--git-diff` |
+| Conversation history | ~800 tok × N turns | `--turns N` |
 
-**What this means in practice:**
+**What cannot be measured:**
 
-| Task type | Without `--files` | With `--files` |
-|-----------|------------------|----------------|
-| Prompt-heavy tasks (long descriptions) | Good | — |
-| File-heavy tasks (reads many files) | Underestimates | Accurate |
-| Conversational tasks | Good | — |
-| Codebase-wide refactors | Underestimates | Accurate |
+- **Claude's responses** — how much Claude writes back is unpredictable. Assume 2–3× of input tokens for total context by end of task.
+- **Tool call overhead** — each file read, bash run, edit adds tokens Mimir cannot see in advance.
+- **Conversation history without `--turns`** — if you don't pass `--turns`, prior messages aren't counted. Use `--turns N` when running mid-session.
 
-Use `--files` whenever Claude will read specific files as part of the task.
+**Practical guide:**
+
+| Task type | Best flags |
+|-----------|-----------|
+| Fresh session, simple task | `/mimir "task"` |
+| Task reads specific files | `--files src/foo.ts src/bar.ts` |
+| Mid-session (50+ messages in) | `--turns 25` |
+| Pre-commit estimate | `--git-diff` |
+| Large codebase refactor | `--files` + `--turns` |
 
 ### Other limitations
 
 - `/split-task` uses pattern matching, not AI reasoning. Suggestions are starting points, not guaranteed optimal splits.
-- Model recommendations are fixed to Sonnet 4.6 / Haiku 4.5 in V1. Opus 4.7 thresholds and context windows will be added in V2.
 - No memory of previous tasks — each invocation is stateless.
 
 ---

scripts/estimate.js

@@ -2,36 +2,58 @@
 const fs           = require('fs');
 const path         = require('path');
 const childProcess = require('child_process');
-const { estimateTokens, countTokensViaAPI } = require('./lib/tokenizer');
-const { classifyRisk, contextHeadroom }     = require('./lib/risk');
-const { loadConfig }                        = require('./lib/config');
-const { appendHistory }                     = require('./lib/history');
+const { estimateTokens, countTokensViaAPI }  = require('./lib/tokenizer');
+const { classifyRisk, contextHeadroom }      = require('./lib/risk');
+const { loadConfig }                         = require('./lib/config');
+const { appendHistory }                      = require('./lib/history');
+const { estimateContextOverhead }            = require('./lib/context');
 
 const LINE  = '━'.repeat(35);
+const SEP   = '─'.repeat(35);
+const COL   = 28; // label column width
+
 const HELP  = `
 ⚡ MIMIR — preflight checker
 
 Usage:
   /mimir "<task>"                   Estimate token cost + risk
-  /mimir "<task>" --files f1 f2     Include file content in estimate
+  /mimir "<task>" --files f1 f2     Include specific files in estimate
   /mimir "<task>" --git-diff        Include current git diff in estimate
+  /mimir "<task>" --turns N         Include N conversation turns in estimate
   /split-task "<task>"              Split large task into safer sub-tasks
 
 Risk levels: LOW ✅  MEDIUM ⚠️  HIGH 🔴  CRITICAL 🚨
 
+Token sources always included:
+  - System overhead  (~3k) — system prompt + command file + hooks
+  - CLAUDE.md files         — user (~/.claude/) and project (.claude/)
+
 Tip: run /mimir before any task that reads many files or touches large codebases.
 `.trimStart();
 
 function parseArgs(argv) {
-  const gitDiffIdx = argv.indexOf('--git-diff');
-  const filesIdx   = argv.indexOf('--files');
-  const baseArgv   = argv.filter(a => a !== '--git-diff');
-  const fi         = baseArgv.indexOf('--files');
-  if (fi === -1) return { task: baseArgv.join(' ').trim(), filePaths: [], useGitDiff: gitDiffIdx !== -1 };
+  const useGitDiff = argv.includes('--git-diff');
+  const turnsIdx   = argv.indexOf('--turns');
+  const turns      = turnsIdx !== -1 ? (parseInt(argv[turnsIdx + 1], 10) || 0) : 0;
+
+  const clean = [];
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--git-diff')         { i++;     continue; }
+    if (argv[i] === '--turns')            { i += 2;  continue; }
+    clean.push(argv[i]);
+    i++;
+  }
+
+  const filesIdx = clean.indexOf('--files');
+  if (filesIdx === -1) {
+    return { task: clean.join(' ').trim(), filePaths: [], useGitDiff, turns };
+  }
   return {
-    task:       baseArgv.slice(0, fi).join(' ').trim(),
-    filePaths:  baseArgv.slice(fi + 1),
-    useGitDiff: gitDiffIdx !== -1,
+    task:       clean.slice(0, filesIdx).join(' ').trim(),
+    filePaths:  clean.slice(filesIdx + 1),
+    useGitDiff,
+    turns,
   };
 }
 
@@ -57,6 +79,11 @@ function fmt(method, n) {
   return method === 'exact' ? n.toLocaleString() : `~${n.toLocaleString()}`;
 }
 
+function row(label, value) {
+  const pad = Math.max(1, COL - label.length);
+  process.stdout.write(`  ${label}${' '.repeat(pad)}${value}\n`);
+}
+
 async function countText(text, method) {
   if (method === 'forced-heuristic') return { tokens: estimateTokens(text), method: 'heuristic' };
   const api = await countTokensViaAPI(text);
@@ -65,71 +92,76 @@ async function countText(text, method) {
 }
 
 async function main() {
-  const { task, filePaths, useGitDiff } = parseArgs(process.argv.slice(2));
+  const { task, filePaths, useGitDiff, turns } = parseArgs(process.argv.slice(2));
 
   if (!task) {
     process.stdout.write(HELP);
     process.exit(0);
   }
 
-  const cfg = loadConfig();
-  const taskResult = await countText(task, 'auto');
-  const method = taskResult.method;
+  const cfg         = loadConfig();
+  const taskResult  = await countText(task, 'auto');
+  const method      = taskResult.method;
+  const ctx         = estimateContextOverhead(cfg, { turns, cwd: process.cwd() });
 
-  let totalTokens = taskResult.tokens;
   const fileResults = [];
-
+  let fileTotal     = 0;
   for (const fp of filePaths) {
     const f = readFile(fp);
     if (f.error) {
       fileResults.push({ path: fp, tokens: 0, error: f.error });
     } else {
       const r = await countText(f.content, 'forced-heuristic');
       fileResults.push({ path: fp, tokens: r.tokens, error: null });
-      totalTokens += r.tokens;
+      fileTotal += r.tokens;
     }
   }
 
   let diffTokens = 0;
   if (useGitDiff) {
     const diff = getGitDiff();
-    if (diff) {
-      diffTokens = estimateTokens(diff);
-      totalTokens += diffTokens;
-    }
+    if (diff) diffTokens = estimateTokens(diff);
   }
 
-  const risk     = classifyRisk(totalTokens, cfg, task);
-  const headroom = contextHeadroom(totalTokens, cfg.contextWindow);
+  const totalTokens = taskResult.tokens + ctx.total + fileTotal + diffTokens;
+  const risk        = classifyRisk(totalTokens, cfg, task);
+  const headroom    = contextHeadroom(totalTokens, cfg.contextWindow);
+  const modelLine   = cfg.defaultModel ? `${cfg.defaultModel} (from .mimir.json)` : risk.suggestedModel;
 
   process.stdout.write(`\n⚡ MIMIR PREFLIGHT\n`);
   process.stdout.write(`${LINE}\n`);
 
-  const hasExtras = filePaths.length > 0 || useGitDiff;
-
-  if (hasExtras) {
-    const filesTotal = fileResults.reduce((s, f) => s + f.tokens, 0);
-    process.stdout.write(`  Task tokens (${method}):   ${fmt(method, taskResult.tokens)}\n`);
-    if (fileResults.length > 0) {
-      process.stdout.write(`  Files tokens:             ~${filesTotal.toLocaleString()}\n`);
-      for (const f of fileResults) {
-        const name = path.basename(f.path).padEnd(20).slice(0, 20);
-        if (f.error) process.stdout.write(`    ${name}  ⚠ ${f.error}\n`);
-        else         process.stdout.write(`    ${name}  ~${f.tokens.toLocaleString()}\n`);
-      }
-    }
-    if (useGitDiff) {
-      process.stdout.write(`  Git diff tokens:          ~${diffTokens.toLocaleString()}\n`);
+  // Token sources
+  row(`Task (${method}):`,         fmt(method, taskResult.tokens));
+  row('System overhead:',          `~${ctx.systemOverhead.toLocaleString()}  (prompt + command + hooks)`);
+
+  for (const md of ctx.claudeMds) {
+    const label = `${md.label}:`;
+    if (md.error) row(label, `⚠ ${md.error}`);
+    else          row(label, `~${md.tokens.toLocaleString()}`);
+  }
+
+  if (fileResults.length > 0) {
+    for (const f of fileResults) {
+      const name  = path.basename(f.path);
+      const label = `${name}:`;
+      if (f.error) row(label, `⚠ ${f.error}`);
+      else         row(label, `~${f.tokens.toLocaleString()}`);
     }
-    process.stdout.write(`  Total tokens:             ~${totalTokens.toLocaleString()}\n`);
-  } else {
-    process.stdout.write(`  Input tokens (${method}):  ${fmt(method, totalTokens)}\n`);
   }
 
-  const modelLine = cfg.defaultModel
-    ? `${cfg.defaultModel} (from .mimir.json)`
-    : risk.suggestedModel;
+  if (useGitDiff) {
+    row('Git diff:', `~${diffTokens.toLocaleString()}`);
+  }
+
+  if (turns > 0) {
+    row(`Conversation (${turns} turns):`, `~${ctx.conversationTokens.toLocaleString()}  (~800 tok/turn)`);
+  }
+
+  process.stdout.write(`  ${SEP}\n`);
+  row('Total:', `~${totalTokens.toLocaleString()}`);
 
+  process.stdout.write(`\n`);
   process.stdout.write(`  Risk:                 ${risk.level} ${risk.emoji}\n`);
   process.stdout.write(`  Suggested model:      ${modelLine}\n`);
   process.stdout.write(`  Context headroom:     ${headroom}%\n`);

scripts/lib/config.js

@@ -2,12 +2,13 @@ const fs   = require('fs');
 const path = require('path');
 
 const DEFAULTS = {
-  defaultModel:  null,
-  thresholds:    { LOW: 20_000, MEDIUM: 60_000, HIGH: 120_000 },
-  contextWindow: 200_000,
+  defaultModel:   null,
+  thresholds:     { LOW: 20_000, MEDIUM: 60_000, HIGH: 120_000 },
+  contextWindow:  200_000,
+  systemOverhead: 3_000,
 };
 
-const KNOWN_KEYS       = new Set(['defaultModel', 'thresholds', 'contextWindow']);
+const KNOWN_KEYS       = new Set(['defaultModel', 'thresholds', 'contextWindow', 'systemOverhead']);
 const KNOWN_THRESHOLDS = new Set(['LOW', 'MEDIUM', 'HIGH']);
 
 function validateConfig(user) {
@@ -28,6 +29,10 @@ function validateConfig(user) {
     warnings.push('"contextWindow" must be a number');
   }
 
+  if (user.systemOverhead !== undefined && typeof user.systemOverhead !== 'number') {
+    warnings.push('"systemOverhead" must be a number');
+  }
+
   return warnings;
 }
 
@@ -43,12 +48,13 @@ function loadConfig(cwd) {
     }
 
     return {
-      defaultModel:  user.defaultModel  ?? DEFAULTS.defaultModel,
-      thresholds:    { ...DEFAULTS.thresholds,  ...(user.thresholds  || {}) },
-      contextWindow: user.contextWindow ?? DEFAULTS.contextWindow,
+      defaultModel:   user.defaultModel   ?? DEFAULTS.defaultModel,
+      thresholds:     { ...DEFAULTS.thresholds, ...(user.thresholds || {}) },
+      contextWindow:  user.contextWindow  ?? DEFAULTS.contextWindow,
+      systemOverhead: user.systemOverhead ?? DEFAULTS.systemOverhead,
     };
   } catch {
-    return { ...DEFAULTS, thresholds: { ...DEFAULTS.thresholds } };
+    return { ...DEFAULTS, thresholds: { ...DEFAULTS.thresholds }, systemOverhead: DEFAULTS.systemOverhead };
   }
 }
 

scripts/lib/context.js

@@ -0,0 +1,63 @@
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { estimateTokens } = require('./tokenizer');
+
+const SYSTEM_OVERHEAD_DEFAULT = 3_000; // system prompt + command file + hooks baseline
+const TOKENS_PER_TURN         = 800;   // avg user+assistant message pair
+
+function findClaudeMds(cwd) {
+  const base   = path.resolve(cwd || process.cwd());
+  const userMd = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+  const seen   = new Set();
+  const found  = [];
+
+  if (fs.existsSync(userMd)) {
+    seen.add(userMd);
+    found.push({ filePath: userMd, label: '~/.claude/CLAUDE.md' });
+  }
+
+  let dir = base;
+  while (true) {
+    const candidate = path.join(dir, '.claude', 'CLAUDE.md');
+    if (!seen.has(candidate) && fs.existsSync(candidate)) {
+      seen.add(candidate);
+      const rel = path.relative(base, path.join(dir, '.claude', 'CLAUDE.md'));
+      found.push({ filePath: candidate, label: rel || '.claude/CLAUDE.md' });
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return found;
+}
+
+function estimateContextOverhead(cfg, options) {
+  const turns        = (options && options.turns)  || 0;
+  const cwd          = (options && options.cwd)    || process.cwd();
+  const sysOverhead  = (cfg && cfg.systemOverhead != null) ? cfg.systemOverhead : SYSTEM_OVERHEAD_DEFAULT;
+
+  const mds      = findClaudeMds(cwd);
+  const mdTokens = mds.map(({ filePath, label }) => {
+    try {
+      return { label, tokens: estimateTokens(fs.readFileSync(filePath, 'utf8')), error: null };
+    } catch (err) {
+      return { label, tokens: 0, error: err.message };
+    }
+  });
+
+  const mdTotal            = mdTokens.reduce((s, r) => s + r.tokens, 0);
+  const conversationTokens = turns * TOKENS_PER_TURN;
+
+  return {
+    systemOverhead:      sysOverhead,
+    claudeMds:           mdTokens,
+    mdTotal,
+    conversationTokens,
+    turns,
+    total:               sysOverhead + mdTotal + conversationTokens,
+  };
+}
+
+module.exports = { estimateContextOverhead, findClaudeMds, SYSTEM_OVERHEAD_DEFAULT, TOKENS_PER_TURN };