turntax 0.2.0 → 0.4.0

package/dist/core/mcp.js

@@ -0,0 +1,227 @@
+const CHECKED_AT = '2026-10-11';
+/** Where each agent reads MCP servers from. Paths and keys come from the cited pages. */
+export const MCP_CONFIGS = [
+    { tool: 'claude-code', path: '.mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://code.claude.com/docs/en/mcp' },
+    { tool: 'cursor', path: '.cursor/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://cursor.com/docs/context/mcp' },
+    { tool: 'copilot', path: '.vscode/mcp.json', scope: 'project', key: 'servers', shape: 'vscode', source: 'https://code.visualstudio.com/docs/copilot/customization/mcp-servers' },
+    { tool: 'gemini-cli', path: '.gemini/settings.json', scope: 'project', key: 'mcpServers', shape: 'gemini', source: 'https://geminicli.com/docs/tools/mcp-server/' },
+    { tool: 'kiro', path: '.kiro/settings/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://kiro.dev/docs/mcp/configuration/' },
+    { tool: 'roo-code', path: '.roo/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo' },
+    { tool: 'opencode', path: 'opencode.json', scope: 'project', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+    { tool: 'opencode', path: 'opencode.jsonc', scope: 'project', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+    { tool: 'zed', path: '.zed/settings.json', scope: 'project', key: 'context_servers', shape: 'zed', source: 'https://zed.dev/docs/ai/mcp' },
+    { tool: 'codex', path: '.codex/config.toml', scope: 'project', key: 'mcp_servers', shape: 'codex-toml', source: 'https://learn.chatgpt.com/docs/extend/mcp' },
+    { tool: 'claude-code', path: '.claude.json', scope: 'user', key: 'mcpServers', shape: 'claude-json', source: 'https://code.claude.com/docs/en/mcp' },
+    { tool: 'cursor', path: '.cursor/mcp.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://cursor.com/docs/context/mcp' },
+    { tool: 'gemini-cli', path: '.gemini/settings.json', scope: 'user', key: 'mcpServers', shape: 'gemini', source: 'https://geminicli.com/docs/tools/mcp-server/' },
+    { tool: 'kiro', path: '.kiro/settings/mcp.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://kiro.dev/docs/mcp/configuration/' },
+    { tool: 'windsurf', path: '.config/devin/mcp_config.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://docs.devin.ai/desktop/cascade/mcp' },
+    { tool: 'windsurf', path: 'AppData/Roaming/devin/mcp_config.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://docs.devin.ai/desktop/cascade/mcp' },
+    { tool: 'codex', path: '.codex/config.toml', scope: 'user', key: 'mcp_servers', shape: 'codex-toml', source: 'https://learn.chatgpt.com/docs/extend/mcp' },
+    { tool: 'opencode', path: '.config/opencode/opencode.json', scope: 'user', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+];
+export const MCP_CHECKED_AT = CHECKED_AT;
+/** True for a repo-relative path that holds project MCP servers for some agent. */
+export function isMcpConfigFile(path) {
+    return MCP_CONFIGS.some((c) => c.scope === 'project' && c.path === path);
+}
+/** Home-relative paths of user-level MCP configs. */
+export const USER_MCP_PATHS = [...new Set(MCP_CONFIGS.filter((c) => c.scope === 'user').map((c) => c.path))];
+/** JSON with comments and trailing commas (VS Code, Zed and OpenCode accept both). */
+export function parseJsonc(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            out += c;
+            if (c === '\\')
+                out += text[++i] ?? '';
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"') {
+            inString = true;
+            out += c;
+        }
+        else if (c === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+        }
+        else if (c === '/' && text[i + 1] === '*') {
+            i = text.indexOf('*/', i + 2);
+            if (i < 0)
+                break;
+            i++;
+        }
+        else
+            out += c;
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1').replace(/^/, ''));
+}
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const strings = (v) => (Array.isArray(v) ? v.map(String) : undefined);
+const record = (v) => isObj(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, String(x)])) : undefined;
+function fromStandard(name, v, gemini = false) {
+    const type = String(v.type ?? v.transport ?? '').toLowerCase();
+    // Gemini CLI has no type field: `httpUrl` is streamable HTTP and `url` is SSE.
+    // Elsewhere `url` (Windsurf: `serverUrl`) is streamable HTTP unless the type says SSE.
+    const httpUrl = typeof v.httpUrl === 'string' ? v.httpUrl : undefined;
+    const url = httpUrl ?? (typeof v.url === 'string' ? v.url : typeof v.serverUrl === 'string' ? v.serverUrl : undefined);
+    const transport = !url ? 'stdio' : httpUrl ? 'http' : gemini || type === 'sse' ? 'sse' : 'http';
+    return {
+        name,
+        transport,
+        command: typeof v.command === 'string' ? v.command : undefined,
+        args: strings(v.args),
+        env: record(v.env),
+        cwd: typeof v.cwd === 'string' ? v.cwd : undefined,
+        url,
+        headers: record(v.headers),
+        disabled: v.disabled === true || v.enabled === false,
+        ...(v.alwaysLoad === true ? { alwaysLoad: true } : {}),
+    };
+}
+function fromOpencode(name, v) {
+    const command = strings(v.command) ?? [];
+    const remote = v.type === 'remote' || typeof v.url === 'string';
+    return {
+        name,
+        transport: remote ? 'http' : 'stdio',
+        command: remote ? undefined : command[0],
+        args: remote ? undefined : command.slice(1),
+        env: record(v.environment),
+        url: typeof v.url === 'string' ? v.url : undefined,
+        headers: record(v.headers),
+        disabled: v.enabled === false,
+    };
+}
+function fromZed(name, v) {
+    // Older Zed settings nest the command: { "command": { "path", "args", "env" } }.
+    if (isObj(v.command)) {
+        const c = v.command;
+        return fromStandard(name, { ...v, command: c.path ?? c.command, args: c.args, env: c.env });
+    }
+    return fromStandard(name, v);
+}
+function serversIn(container, shape) {
+    if (!isObj(container))
+        return [];
+    return Object.entries(container)
+        .filter(([, v]) => isObj(v))
+        .map(([name, v]) => shape === 'opencode'
+        ? fromOpencode(name, v)
+        : shape === 'zed'
+            ? fromZed(name, v)
+            : fromStandard(name, v, shape === 'gemini'));
+}
+/** Minimal TOML reader for Codex `[mcp_servers.<name>]` tables: strings, string arrays and inline tables. */
+export function parseCodexToml(text) {
+    const servers = {};
+    let current = null;
+    let sub = null;
+    const value = (raw) => {
+        const t = raw.trim();
+        if (t.startsWith('['))
+            return [...t.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2] ?? '');
+        if (t.startsWith('{'))
+            return Object.fromEntries([...t.matchAll(/([\w-]+|"[^"]*")\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/g)].map((m) => [m[1].replace(/"/g, ''), m[2] ?? m[3] ?? '']));
+        if (t === 'true' || t === 'false')
+            return t === 'true';
+        const s = /^"((?:[^"\\]|\\.)*)"|^'([^']*)'/.exec(t);
+        return s ? (s[1] ?? s[2]) : t;
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const header = /^\s*\[\s*mcp_servers\.(?:"([^"]+)"|([\w-]+))(?:\.(\w+))?\s*\]/.exec(line);
+        if (header) {
+            const name = (header[1] ?? header[2]);
+            servers[name] ??= {};
+            current = servers[name];
+            sub = header[3] ?? null;
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            current = null;
+            continue;
+        }
+        const kv = /^\s*([\w-]+)\s*=\s*(.+?)\s*(?:#.*)?$/.exec(line);
+        if (!kv || !current)
+            continue;
+        if (sub) {
+            const table = (current[sub] ??= {});
+            table[kv[1]] = value(kv[2]);
+        }
+        else
+            current[kv[1]] = value(kv[2]);
+    }
+    // Codex calls HTTP headers `http_headers`.
+    for (const v of Object.values(servers))
+        if (isObj(v) && v.http_headers && !v.headers)
+            v.headers = v.http_headers;
+    return servers;
+}
+/**
+ * Parses the MCP configs among `files`. Project files use repo-relative paths; user files are passed
+ * with a `~/` prefix. `projectRoot` (absolute) selects the per-project entry in ~/.claude.json.
+ */
+export function parseMcpConfigs(files, projectRoot) {
+    const servers = [];
+    const problems = [];
+    for (const f of files) {
+        const user = f.path.startsWith('~/');
+        const rel = user ? f.path.slice(2) : f.path;
+        const specs = MCP_CONFIGS.filter((c) => c.path === rel && c.scope === (user ? 'user' : 'project'));
+        if (!specs.length)
+            continue;
+        let data;
+        try {
+            data = specs[0].shape === 'codex-toml' ? parseCodexToml(f.text) : parseJsonc(f.text);
+        }
+        catch (e) {
+            problems.push({ path: f.path, message: `could not be parsed: ${e.message}` });
+            continue;
+        }
+        if (!isObj(data))
+            continue;
+        for (const spec of specs) {
+            const containers = spec.shape === 'codex-toml'
+                ? [data]
+                : spec.shape === 'claude-json'
+                    ? [data.mcpServers, projectEntry(data, projectRoot)?.mcpServers]
+                    : [data[spec.key]];
+            for (const c of containers)
+                for (const s of serversIn(c, spec.shape))
+                    servers.push({ ...s, tool: spec.tool, configPath: f.path, scope: spec.scope });
+        }
+    }
+    return { servers, problems };
+}
+/** The `projects["<abs path>"]` entry of ~/.claude.json for this repository, matched case- and slash-insensitively. */
+function projectEntry(data, root) {
+    if (!root || !isObj(data.projects))
+        return undefined;
+    const norm = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const hit = Object.entries(data.projects).find(([p]) => norm(p) === norm(root));
+    return hit && isObj(hit[1]) ? hit[1] : undefined;
+}
+/** Same server started by several agents or configs: one launch, one measurement. */
+export function serverKey(s) {
+    return JSON.stringify([s.transport, s.command ?? '', s.args ?? [], s.url ?? '', s.cwd ?? '']);
+}
+/**
+ * Claude Code defers MCP tool definitions by default (tool search): only tool names are in context
+ * until a tool is used. A server with `alwaysLoad: true` is exempt.
+ */
+export function defersTools(s) {
+    return s.tool === 'claude-code' && !s.alwaysLoad;
+}
+export const DEFERRED_NOTE = 'Claude Code defers MCP tool definitions by default (tool search): only tool names load every turn; full definitions load when a tool is used. Set ENABLE_TOOL_SEARCH=false or alwaysLoad: true to load them upfront.';
+/** Tool names only, as listed when definitions are deferred. */
+export function toolNamesText(tools) {
+    return tools.map((t) => t.name).join('\n');
+}
+/** The text an agent receives for a server's tools, as one JSON document per tool. */
+export function toolDefinitionsText(tools) {
+    return tools.map((t) => JSON.stringify({ name: t.name, description: t.description ?? '', input_schema: t.inputSchema ?? {} })).join('\n');
+}

package/dist/core/render.js

@@ -1,3 +1,4 @@
+import { DEFERRED_NOTE } from './mcp.js';
 export const METHOD_LABEL = {
     'offline-exact': 'exact (offline tokenizer)',
     'offline-proxy': 'estimate (o200k_base proxy)',
@@ -32,7 +33,11 @@ export function groupTools(report) {
             .filter((f) => f.tool === t.tool && f.mode !== 'ignored')
             .map((f) => [f.path, f.part, f.mode, f.o200k])
             .sort();
-        const key = JSON.stringify([files, t.models.map(({ model, perTurn, method, reason }) => [model, perTurn, method, reason])]);
+        const key = JSON.stringify([
+            files,
+            t.models.map(({ model, perTurn, method, reason }) => [model, perTurn, method, reason]),
+            report.mcp.filter((m) => m.tool === t.tool).map((m) => [m.configPath, m.name, m.status, m.o200k]),
+        ]);
         const g = groups.get(key);
         if (g)
             g.names.push(t.name);
@@ -54,9 +59,112 @@ export function groupFiles(report) {
     }
     return [...groups.values()];
 }
-/** Highest always-loaded o200k total across the reported tools. */
+/**
+ * Highest per-turn o200k total across the reported tools, for the badge and --max-tokens:
+ * repository files plus measured project MCP tool definitions. User-level files never count here.
+ */
 export function headlineTokens(report) {
-    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k));
+    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k + (t.mcpPerTurnO200k ?? 0)));
+}
+/** MCP cell: measured tokens, a "+" when some servers could not be measured, or how many are unmeasured. */
+export function mcpCell(t) {
+    if (!t.mcpServers)
+        return '-';
+    if (t.mcpMeasured)
+        return fmtTokens(t.mcpPerTurnO200k);
+    return t.mcpPerTurnO200k > 0 ? `${fmtTokens(t.mcpPerTurnO200k)}+` : `${t.mcpServers} not measured`;
+}
+function signed(n) {
+    return n > 0 ? `+${fmtTokens(n)}` : n < 0 ? `-${fmtTokens(-n)}` : '0';
+}
+function fmtMaybe(n) {
+    return n === null ? '-' : fmtTokens(n);
+}
+/** Agents with the same before/after numbers share one line. */
+function groupDeltas(diff) {
+    const groups = new Map();
+    for (const t of diff.tools) {
+        const key = `${t.before}|${t.after}`;
+        const g = groups.get(key);
+        if (g)
+            g.names.push(t.name);
+        else
+            groups.set(key, { names: [t.name], before: t.before, after: t.after, delta: t.delta });
+    }
+    return [...groups.values()].sort((a, b) => b.delta - a.delta);
+}
+export function renderDiffText(diff) {
+    const out = [`Change vs ${diff.base} (o200k tokens per turn, repository files)`];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('  No change in per-turn tokens.');
+    else {
+        const rows = [['before', 'after', 'change', 'agents']];
+        for (const g of changed)
+            rows.push([fmtMaybe(g.before), fmtMaybe(g.after), signed(g.delta), g.names.join(', ')]);
+        out.push(table(rows, '  '));
+    }
+    if (diff.files.length) {
+        out.push('  Files loaded every turn');
+        const rows = [['before', 'after', 'change', 'file']];
+        for (const f of diff.files)
+            rows.push([fmtMaybe(f.before), fmtMaybe(f.after), signed(f.delta), f.part === 'full' ? f.path : `${f.path} (${f.part})`]);
+        out.push(table(rows, '    '));
+    }
+    for (const s of diff.mcp.added)
+        out.push(`  MCP server added: ${s}`);
+    for (const s of diff.mcp.removed)
+        out.push(`  MCP server removed: ${s}`);
+    return out.join('\n');
+}
+export function renderDiffMarkdown(diff) {
+    const out = [`## Change vs \`${diff.base}\``, ''];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('No change in per-turn tokens (o200k, repository files).');
+    else {
+        out.push('o200k tokens added to every turn by repository instruction files.', '');
+        out.push('| Agents | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const g of changed)
+            out.push(`| ${g.names.join(', ')} | ${fmtMaybe(g.before)} | ${fmtMaybe(g.after)} | **${signed(g.delta)}** |`);
+    }
+    if (diff.files.length) {
+        out.push('', '| File loaded every turn | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const f of diff.files)
+            out.push(`| \`${f.part === 'full' ? f.path : `${f.path} (${f.part})`}\` | ${fmtMaybe(f.before)} | ${fmtMaybe(f.after)} | ${signed(f.delta)} |`);
+    }
+    if (diff.mcp.added.length || diff.mcp.removed.length) {
+        out.push('');
+        for (const s of diff.mcp.added)
+            out.push(`- MCP server added: ${s}`);
+        for (const s of diff.mcp.removed)
+            out.push(`- MCP server removed: ${s}`);
+    }
+    return out.join('\n');
+}
+/** MCP rows that are identical apart from the agent, merged. */
+function groupMcp(rows) {
+    const groups = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify([r.configPath, r.name, r.status, r.tools, r.o200k, r.error]);
+        const g = groups.get(key);
+        if (g)
+            g.tools.push(r.tool);
+        else
+            groups.set(key, { row: r, tools: [r.tool] });
+    }
+    return [...groups.values()];
+}
+function mcpDetail(r) {
+    if (r.status === 'measured')
+        return r.deferredO200k === undefined
+            ? `${r.tools} tools`
+            : `${r.tools} tools; names only, full definitions (${fmtTokens(r.deferredO200k)}) load when used`;
+    if (r.status === 'disabled')
+        return 'disabled in the config';
+    if (r.status === 'failed')
+        return r.error ?? 'failed';
+    return 'run with --mcp to count its tool definitions';
 }
 export function renderText(report, root) {
     const out = [];
@@ -66,11 +174,25 @@ export function renderText(report, root) {
         out.push('No agent instruction files found.');
         return out.join('\n');
     }
+    if (report.diff) {
+        out.push(renderDiffText(report.diff));
+        out.push('');
+    }
+    const showMcp = report.tools.some((t) => t.mcpServers > 0);
+    const showUser = report.tools.some((t) => t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0);
+    const extra = [...(showMcp ? ['mcp/turn'] : []), ...(showUser ? ['user/turn'] : []), ...(showMcp || showUser ? ['total'] : [])];
     const rows = [
-        ['always', 'o200k/turn', 'on-demand', 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached', 'agents'],
+        ['always', 'o200k/turn', 'on-demand', ...extra, 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached', 'agents'],
     ];
     for (const { names, tool: t } of groupTools(report)) {
-        const head = [String(t.alwaysFiles), fmtTokens(t.perTurnO200k), fmtTokens(t.onDemandO200k)];
+        const head = [
+            String(t.alwaysFiles),
+            fmtTokens(t.perTurnO200k),
+            fmtTokens(t.onDemandO200k),
+            ...(showMcp ? [mcpCell(t)] : []),
+            ...(showUser ? [fmtTokens(t.userPerTurnO200k)] : []),
+            ...(showMcp || showUser ? [fmtTokens(t.totalPerTurnO200k) + (t.mcpMeasured ? '' : '+')] : []),
+        ];
         const blank = head.map(() => '');
         const agents = names.join(', ');
         if (!t.models.length)
@@ -93,6 +215,14 @@ export function renderText(report, root) {
         fileRows.push([f.mode, name + (f.importedFrom ? ` <- @${f.importedFrom}` : ''), fmtTokens(f.o200k), f.trigger, tools.join(', ')]);
     }
     out.push(table(fileRows, '  '));
+    if (report.mcp.length) {
+        out.push('');
+        out.push('MCP servers (tool definitions are sent every turn)');
+        const mcpRows = [['status', 'server', 'config', 'o200k', 'detail', 'agents']];
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            mcpRows.push([r.status, r.name, r.configPath, r.o200k === undefined ? '-' : fmtTokens(r.o200k), mcpDetail(r), tools.join(', ')]);
+        out.push(table(mcpRows, '  '));
+    }
     const notes = [...new Set(report.files.flatMap((f) => f.notes.map((n) => `${f.path}: ${n}`)))];
     if (notes.length) {
         out.push('');
@@ -119,6 +249,10 @@ function footer(report) {
         'o200k = OpenAI o200k_base, counted offline. It is a reference for every file, not a Claude or Gemini count.',
         'Claude and Gemini tokenizers are not public: their counts come only from the vendor APIs (--claude-api, --gemini-api).',
         `Cost = tokens/turn x ${report.turns} turns x input price. "Cached" assumes every turn reads the context from the prompt cache.`,
+        ...(report.mcp.length
+            ? ['MCP tool definitions are counted as JSON with o200k (an estimate of what the agent sends) and are not included in model costs.']
+            : []),
+        ...(report.mcp.some((m) => m.deferredO200k !== undefined) ? [DEFERRED_NOTE] : []),
         'Prices (USD per 1M input tokens):',
     ];
     for (const m of report.models) {
@@ -129,6 +263,8 @@ function footer(report) {
 }
 export function renderMarkdown(report) {
     const out = ['# Agent context tax report', ''];
+    if (report.diff)
+        out.push(renderDiffMarkdown(report.diff), '');
     out.push(`Every agent re-sends its always-loaded instruction files with each turn. Costs are for ${report.turns} turns.`, '');
     out.push('## Per agent', '');
     out.push('| Agents | Model | Tokens / turn | Counted by | Uncached | Cached |', '| --- | --- | ---: | --- | ---: | ---: |');
@@ -141,6 +277,17 @@ export function renderMarkdown(report) {
                 ? `| ${agents} | ${m.label} | - | ${m.reason ?? ''} | - | - |`
                 : `| ${agents} | ${m.label} | ${fmtTokens(m.perTurn)} | ${METHOD_LABEL[m.method]} | ${fmtUsd(m.uncached)} | ${fmtUsd(m.cached)} |`);
     }
+    if (report.tools.some((t) => t.mcpServers > 0 || t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0)) {
+        out.push('', '### Every turn, by source (o200k)', '');
+        out.push('| Agents | Repository files | MCP tools | User level | Total |', '| --- | ---: | ---: | ---: | ---: |');
+        for (const { names, tool: t } of groupTools(report))
+            out.push(`| ${names.join(', ')} | ${fmtTokens(t.perTurnO200k)} | ${mcpCell(t)} | ${fmtTokens(t.userPerTurnO200k)} | ${fmtTokens(t.totalPerTurnO200k)}${t.mcpMeasured ? '' : '+'} |`);
+    }
+    if (report.mcp.length) {
+        out.push('', '## MCP servers', '', '| Status | Server | Config | o200k tokens | Detail | Agents |', '| --- | --- | --- | ---: | --- | --- |');
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            out.push(`| ${r.status} | ${escapeCell(r.name)} | \`${r.configPath}\` | ${r.o200k === undefined ? '-' : fmtTokens(r.o200k)} | ${escapeCell(mcpDetail(r))} | ${tools.join(', ')} |`);
+    }
     out.push('', '## Files', '', '| Mode | File | o200k tokens | Loads | Agents |', '| --- | --- | ---: | --- | --- |');
     for (const { file: f, tools } of groupFiles(report)) {
         const name = f.part === 'full' ? f.path : `${f.path} (${f.part})`;
@@ -157,6 +304,10 @@ export function renderMarkdown(report) {
     out.push('- o200k = OpenAI `o200k_base`, counted offline; a reference, not a Claude or Gemini count.');
     out.push('- Claude counts come only from Anthropic `count_tokens`; Gemini counts only from Google `countTokens`.');
     out.push('- "Cached" assumes every turn reads the context from the prompt cache.');
+    if (report.mcp.length)
+        out.push('- MCP tool definitions are counted as JSON with o200k, an estimate of what the agent sends; they are not in the model costs.');
+    if (report.mcp.some((m) => m.deferredO200k !== undefined))
+        out.push(`- ${DEFERRED_NOTE}`);
     for (const m of report.models)
         out.push(`- ${m.label}: $${m.inputPerMTok ?? 'n/a'} input / $${m.cachedInputPerMTok ?? 'n/a'} cached per 1M tokens ([source](${m.source}), checked ${m.checkedAt}).`);
     out.push('', badgeMarkdown(report));
@@ -177,3 +328,17 @@ export function badgeUrl(report) {
 export function badgeMarkdown(report) {
     return `[![context tax (o200k)](${badgeUrl(report)})](https://github.com/TorutDev/turntax)`;
 }
+export const PR_COMMENT_MARKER = '<!-- turntax-report -->';
+const COMMENT_LIMIT = 60_000;
+/**
+ * A pull request comment: the change against the base branch first, the full report folded below.
+ * Starts with a marker so the GitHub Action can update its own comment instead of adding new ones.
+ */
+export function renderPrComment(report) {
+    const top = report.diff ? renderDiffMarkdown(report.diff) : '## Agent context tax';
+    const headline = `Largest per-turn cost: **${fmtTokens(headlineTokens(report))}** o200k tokens (repository files and measured project MCP tools).`;
+    let full = renderMarkdown({ ...report, diff: undefined }).replace(/^# .*\n\n/, '');
+    if (full.length > COMMENT_LIMIT)
+        full = full.slice(0, COMMENT_LIMIT) + '\n\n_Report cut to fit in a comment; the job summary has all of it._\n';
+    return [PR_COMMENT_MARKER, top, '', headline, '', '<details><summary>Full report</summary>', '', full, '</details>', ''].join('\n');
+}

package/dist/core/user.js

@@ -0,0 +1,80 @@
+/**
+ * User-level instruction files: the ones in the home directory that an agent adds to every project.
+ * Each is classified by the same rules as its project counterpart, through a virtual path
+ * (for example ~/.codex/AGENTS.md is read like a root AGENTS.md, but only by Codex).
+ */
+import { classify } from './classify.js';
+const same = (p) => p;
+export const USER_FILES = [
+    { tool: 'claude-code', pattern: /^\.claude\/CLAUDE\.md$/, as: same, source: 'https://code.claude.com/docs/en/memory' },
+    { tool: 'claude-code', pattern: /^\.claude\/rules\/.+\.md$/, as: same, source: 'https://code.claude.com/docs/en/memory' },
+    { tool: 'claude-code', pattern: /^\.claude\/skills\/[^/]+\/SKILL\.md$/, as: same, source: 'https://code.claude.com/docs/en/skills' },
+    { tool: 'claude-code', pattern: /^\.claude\/commands\/.+\.md$/, as: same, source: 'https://code.claude.com/docs/en/skills' },
+    { tool: 'claude-code', pattern: /^\.claude\/agents\/[^/]+\.md$/, as: same, source: 'https://code.claude.com/docs/en/sub-agents' },
+    { tool: 'codex', pattern: /^\.codex\/AGENTS(\.override)?\.md$/, as: (p) => p.slice('.codex/'.length), source: 'https://learn.chatgpt.com/docs/agent-configuration/agents-md' },
+    { tool: 'codex', pattern: /^\.agents\/skills\/[^/]+\/SKILL\.md$/, as: same, source: 'https://learn.chatgpt.com/docs/build-skills' },
+    { tool: 'gemini-cli', pattern: /^\.gemini\/GEMINI\.md$/, as: () => 'GEMINI.md', source: 'https://geminicli.com/docs/cli/gemini-md/' },
+    { tool: 'windsurf', pattern: /^\.codeium\/windsurf\/memories\/global_rules\.md$/, as: () => '.windsurfrules', source: 'https://docs.devin.ai/desktop/cascade/memories' },
+    { tool: 'cline', pattern: /^(Documents\/Cline\/Rules|Cline\/Rules|\.cline\/rules)\/.+\.md$/, as: (p) => '.clinerules/' + p.replace(/^(Documents\/Cline\/Rules|Cline\/Rules|\.cline\/rules)\//, ''), source: 'https://docs.cline.bot/features/cline-rules' },
+    { tool: 'roo-code', pattern: /^\.roo\/rules(-[\w-]+)?\/.+\.(md|txt)$/, as: same, source: 'https://roocodeinc.github.io/Roo-Code/features/custom-instructions' },
+    { tool: 'kiro', pattern: /^\.kiro\/steering\/[^/]+\.md$/, as: same, source: 'https://kiro.dev/docs/steering/' },
+    { tool: 'goose', pattern: /^\.config\/goose\/\.goosehints$/, as: () => '.goosehints', source: 'https://goose-docs.ai/docs/guides/context-engineering/using-goosehints' },
+    { tool: 'amp', pattern: /^\.config\/(amp\/)?AGENTS\.md$/, as: () => 'AGENTS.md', source: 'https://ampcode.com/docs/customize/agents-md' },
+    { tool: 'opencode', pattern: /^\.config\/opencode\/AGENTS\.md$/, as: () => 'AGENTS.md', source: 'https://opencode.ai/docs/rules/' },
+    // OpenCode falls back to ~/.claude/CLAUDE.md when ~/.config/opencode/AGENTS.md is missing.
+    { tool: 'opencode', pattern: /^\.claude\/CLAUDE\.md$/, as: () => 'CLAUDE.md', source: 'https://opencode.ai/docs/rules/' },
+];
+/** Home-relative folders to search, and how deep. Kept narrow so nothing else in the home directory is read. */
+export const USER_ROOTS = [
+    { dir: '.claude', depth: 4 },
+    { dir: '.codex', depth: 0 },
+    { dir: '.agents/skills', depth: 1 },
+    { dir: '.gemini', depth: 0 },
+    { dir: '.codeium/windsurf/memories', depth: 0 },
+    { dir: 'Documents/Cline/Rules', depth: 3 },
+    { dir: 'Cline/Rules', depth: 3 },
+    { dir: '.cline/rules', depth: 3 },
+    { dir: '.roo', depth: 3 },
+    { dir: '.kiro/steering', depth: 0 },
+    { dir: '.config/goose', depth: 0 },
+    { dir: '.config', depth: 0 },
+    { dir: '.config/amp', depth: 0 },
+    { dir: '.config/opencode', depth: 0 },
+];
+export function isUserInstructionFile(homePath) {
+    return USER_FILES.some((r) => r.pattern.test(homePath));
+}
+/**
+ * Classifies user-level files (paths given as `~/...`). Each tool sees only its own files,
+ * so ~/.codex/AGENTS.md never counts for Claude Code.
+ */
+export function classifyUser(files, toolIds) {
+    const units = [];
+    const tools = [...new Set(USER_FILES.map((r) => r.tool))].filter((t) => !toolIds || toolIds.includes(t));
+    for (const tool of tools) {
+        // Files that map to the same place are all read (Amp loads both ~/.config/amp/AGENTS.md and
+        // ~/.config/AGENTS.md), so each collision is classified in a batch of its own.
+        const batches = [];
+        for (const f of files) {
+            const home = f.path.replace(/^~\//, '');
+            const rule = USER_FILES.find((r) => r.tool === tool && r.pattern.test(home));
+            if (!rule)
+                continue;
+            const as = rule.as(home);
+            let batch = batches.find((b) => !b.virtual.has(as));
+            if (!batch)
+                batches.push((batch = { virtual: new Map(), files: [] }));
+            batch.virtual.set(as, f.path);
+            batch.files.push({ path: as, text: f.text });
+        }
+        for (const batch of batches) {
+            for (const u of classify(batch.files, [tool])) {
+                const real = batch.virtual.get(u.path);
+                if (!real)
+                    continue; // an @import resolved inside the virtual tree; user-level imports are not followed
+                units.push({ ...u, path: real, trigger: `user level, ${u.trigger}`, scope: 'user' });
+            }
+        }
+    }
+    return units;
+}

package/dist/node/apply.js

@@ -0,0 +1,43 @@
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { realLocation } from './discover.js';
+const inside = (root, p) => {
+    const rel = relative(root, p);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+};
+/**
+ * Writes planned changes under `root`. Every file is checked first: files to change must still have the
+ * content the plan was made from, new files must not exist, and nothing may be written through a symlink
+ * (dangling ones included) or outside the repository. Nothing is written when a check fails.
+ */
+export function applyChanges(root, changes) {
+    const realRoot = realpathSync(root);
+    const exists = (p) => lstatSync(p, { throwIfNoEntry: false }) !== undefined;
+    const abs = (path) => {
+        const p = resolve(root, path);
+        if (lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error(`${path} is a symlink; nothing was written.`);
+        const real = realLocation(p);
+        if (!inside(root, p) || real === null || !inside(realRoot, real))
+            throw new Error(`${path} is outside ${root}; nothing was written.`);
+        return p;
+    };
+    for (const c of changes) {
+        const source = c.renamedFrom ?? c.path;
+        if (c.renamedFrom && exists(abs(c.path)))
+            throw new Error(`${c.path} already exists; nothing was written.`);
+        if (c.before === null ? exists(abs(c.path)) : !exists(abs(source)) || readFileSync(abs(source), 'utf8') !== c.before)
+            throw new Error(`${source} ${c.before === null ? 'already exists' : 'changed since it was read'}; nothing was written.`);
+    }
+    for (const c of changes) {
+        const target = abs(c.path);
+        mkdirSync(dirname(target), { recursive: true });
+        if (c.renamedFrom)
+            renameSync(abs(c.renamedFrom), target);
+        // New files are created exclusively, so a link placed in the meantime is not followed.
+        if (c.before === null)
+            writeFileSync(target, c.after, { flag: 'wx' });
+        else if (c.after !== c.before || !c.renamedFrom)
+            writeFileSync(target, c.after);
+    }
+}