turntax 0.1.0 → 0.3.0

package/README.md

@@ -1,19 +1,48 @@
 # turntax
 
-Coding agents re-send their instruction files with every turn. `turntax` measures that fixed per-turn cost for a repository, per tool and per model, and shows where to cut it.
+Coding agents re-send their instruction files with every turn. `turntax` measures that fixed per-turn cost for a repository, for every agent that reads it, and shows where to cut it.
 
 ```bash
 npx turntax
 ```
 
-It reads the files each agent actually loads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules`, `.github/copilot-instructions.md`, Windsurf rules, skills) and applies each tool's documented loading rules: what is sent on every turn, what loads only when the agent works in a folder or touches a matching file, and what is ignored.
+Try it in the browser, with nothing uploaded: https://torutdev.github.io/turntax/
+
+## Supported agents
+
+Each agent's documented loading rules decide what is sent on every turn, what loads only when the agent works in a folder or touches a matching file, and what is ignored.
+
+| Agent | Files it reads from the repository |
+| --- | --- |
+| Aider | files listed under `read:` in `.aider.conf.yml` (`CONVENTIONS.md` only when listed or passed with `--read`) |
+| Amp | `AGENTS.md` (or `AGENT.md` / `CLAUDE.md`), nested `AGENTS.md`, @-mentioned files |
+| Claude Code | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules`, skills, commands, subagents, `AGENTS.md` when there is no `CLAUDE.md` |
+| Cline | `.clinerules/`, `.cline/rules/` |
+| Continue | `.continue/rules/` |
+| Cursor | `.cursor/rules/*.mdc`, `.cursorrules`, `AGENTS.md`, `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` |
+| Goose | `.goosehints`, `AGENTS.md` |
+| JetBrains Junie | `.junie/AGENTS.md`, or `AGENTS.md` with `.junie/rules/`, or `.junie/guidelines` |
+| Kiro | `.kiro/steering/`, `AGENTS.md` |
+| OpenAI Codex | `AGENTS.md`, `AGENTS.override.md`, `.agents/skills` |
+| OpenCode | `AGENTS.md`, or `CLAUDE.md` when there is none |
+| Roo Code | `.roo/rules/`, `.roo/rules-{mode}/`, `.roorules`, `AGENTS.md` |
+| Windsurf (Devin Desktop) | `.devin/rules/`, `.windsurf/rules/`, `.windsurfrules`, `AGENTS.md` |
+| Zed | the first of `.rules`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.github/copilot-instructions.md`, `AGENT.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` |
+
+Agents that load exactly the same files share one row in the report:
 
 ```text
-tool          always  o200k/turn  on-demand  model              tokens/turn  counted by                                100 turns  cached
-Claude Code   4       272         53         Claude Sonnet 5.5  -            needs --claude-api and ANTHROPIC_API_KEY  -          -
-OpenAI Codex  1       63          0          GPT-6.1 Sol        63           estimate (o200k_base proxy)               $0.01      $0.0006
-Cursor        4       297         37         Claude Sonnet 5.5  -            needs --claude-api and ANTHROPIC_API_KEY  -          -
-                                             GPT-6.1 Sol        297          estimate (o200k_base proxy)               $0.06      $0.0030
+always  o200k/turn  on-demand  model                tokens/turn  counted by                   100 turns  cached   agents
+4       272         53         (no selected model)                                                                Claude Code
+1       63          0          GPT-6.1 Sol          63           estimate (o200k_base proxy)  $0.01      $0.0006  OpenAI Codex, Roo Code, Kiro, JetBrains Junie, Goose, OpenCode
+1       17          0          (no selected model)                                                                Gemini CLI
+4       297         37         GPT-6.1 Sol          297          estimate (o200k_base proxy)  $0.06      $0.0030  Cursor
+2       74          8          GPT-6.1 Sol          74           estimate (o200k_base proxy)  $0.01      $0.0007  GitHub Copilot
+2       75          0          GPT-6.1 Sol          75           estimate (o200k_base proxy)  $0.01      $0.0008  Windsurf (Devin Desktop)
+1       11          0          GPT-6.1 Sol          11           estimate (o200k_base proxy)  $0.0022    $0.0001  Zed
+1       63          19         GPT-6.1 Sol          63           estimate (o200k_base proxy)  $0.01      $0.0006  Amp
 
 Advice (savings are estimates in o200k tokens per turn)
   HIGH duplicate CLAUDE.md, AGENTS.md [saves ~48 tokens/turn]
@@ -24,7 +53,7 @@ Advice (savings are estimates in o200k tokens per turn)
     Section "API package" is mostly about packages/api/. Move it to packages/api/AGENTS.md ...
 ```
 
-(Output for [`test/fixtures/mixed`](test/fixtures/mixed).)
+(Excerpt of the output for [`test/fixtures/mixed`](test/fixtures/mixed) with `--models gpt-6.1-sol`.)
 
 ## What it counts, and how
 
@@ -39,7 +68,7 @@ Claude's tokenizer is not public, and Anthropic's docs note that newer Claude mo
 
 Cost per N turns = tokens per turn × N × input price. The "cached" column assumes every turn reads the context from the prompt cache. Prices come from a dated table with a source link per model (`turntax --list-models`); pass `--prices my-prices.json` to use your own.
 
-See [docs/how-it-counts.md](docs/how-it-counts.md) for the loading rules per tool and their sources.
+See [docs/how-it-counts.md](docs/how-it-counts.md) for the loading rules per agent and their sources.
 
 ## Advice
 
@@ -54,16 +83,97 @@ All checks are deterministic. Each one shows an estimated saving in o200k tokens
 - **stale-reference**: referenced files or `npm run` scripts that no longer exist.
 - **non-english**: non-English sections. The token multiplier is measured only against an English version you supply (`--english CLAUDE.md=CLAUDE.en.md`) or, if you opt in, a Claude translation (`--translate`).
 
+## MCP servers
+
+Every MCP server an agent starts adds its tool definitions (names, descriptions, input schemas) to the context. `turntax` reads the agents' MCP configs and lists the servers each agent starts:
+
+| Agent | Project config | User config |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | `~/.claude.json` (user and per-project servers) |
+| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
+| GitHub Copilot (VS Code) | `.vscode/mcp.json` | |
+| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` |
+| Kiro | `.kiro/settings/mcp.json` | `~/.kiro/settings/mcp.json` |
+| Roo Code | `.roo/mcp.json` | |
+| OpenAI Codex | `.codex/config.toml` (trusted projects) | `~/.codex/config.toml` |
+| OpenCode | `opencode.json` | `~/.config/opencode/opencode.json` |
+| Zed | `.zed/settings.json` | |
+| Windsurf (Devin Desktop) | | `~/.config/devin/mcp_config.json` |
+
+Counting the tool definitions needs the servers running, so it is opt-in:
+
+```bash
+npx turntax --mcp
+```
+
+`--mcp` starts each stdio server with the command from its config (in the repository folder) and connects to streamable HTTP servers, asks for `tools/list`, and counts the definitions as JSON with o200k. A server several agents share is started once. Environment variables in the config (`${VAR}`, `${VAR:-default}`, `${env:VAR}`) are expanded; servers that need a VS Code `${input:...}` prompt, legacy SSE servers and servers that fail or time out (`--mcp-timeout`, default 30 s) are listed with the reason and not counted.
+
+Claude Code defers MCP tool definitions by default (tool search): only the tool names are in context until a tool is used, so its row counts the names and shows the full size separately. A server with `alwaysLoad: true` is counted in full.
+
+MCP tokens are an o200k estimate and are not included in the model cost columns.
+
+## User-level files
+
+Agents also read instruction files from your home directory in every project. `--include-user` adds them in a separate `user/turn` column and a `total`:
+
+```bash
+npx turntax --include-user
+```
+
+It reads only the documented locations: `~/.claude/` (CLAUDE.md, rules, skills, commands, agents), `~/.codex/AGENTS.md`, `~/.agents/skills`, `~/.gemini/GEMINI.md`, Windsurf's `global_rules.md`, Cline's global rules folders, `~/.roo/rules*`, `~/.kiro/steering`, `~/.config/goose/.goosehints`, Amp's `~/.config/AGENTS.md` and `~/.config/amp/AGENTS.md`, and `~/.config/opencode/AGENTS.md` (OpenCode falls back to `~/.claude/CLAUDE.md`), plus the user MCP configs above. Contradictions and duplicates between user-level and repository files are reported. User-level files never count toward the badge or `--max-tokens`, so the result does not depend on who runs it.
+
+## Comparing with a baseline
+
+```bash
+npx turntax --compare origin/main            # instruction files at a git ref, read with git show
+npx turntax --json --out before.json         # or save a report ...
+npx turntax --baseline before.json           # ... and compare with it later
+npx turntax --compare origin/main --max-increase 200   # exit 1 when any agent grows by more than 200 tokens
+```
+
+The comparison covers repository instruction files (o200k), per agent and per file, and lists MCP servers that were added or removed. It never changes the working tree.
+
+## GitHub Action
+
+The repository is also an Action. On pull requests it compares with the base branch, posts one comment (updated on every push) and writes the report to the job summary:
+
+```yaml
+name: turntax
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  turntax:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: TorutDev/turntax@v0.3.0
+        with:
+          max-increase: 500      # optional: fail when an agent grows by more than 500 tokens per turn
+          # max-tokens: 8000     # optional: absolute budget
+          # args: --tools claude-code,cursor
+```
+
+The comment opens with a table of the change per agent and per file, and folds the full report below it. Pull requests from forks get a read-only token, so the comment step is skipped there; the job summary still has the report.
+
 ## Options
 
 ```text
 turntax [path]
-  --tools claude-code,codex,gemini-cli,cursor,copilot,windsurf
+  --tools <ids>             agents to report (default: every agent that reads a file); see --help
   --models <ids>            see --list-models (default: claude-sonnet-5.5, gpt-6.1-sol, gemini-3.8-flash)
   --turns <n>               cost projection (default 100)
   --json | --md | --badge   output format (default: terminal table)
+  --pr-comment              Markdown for a pull request comment (change first, full report folded)
   --out <file>              write the output to a file
   --max-tokens <n>          exit 1 when any tool loads more than n o200k tokens per turn (CI gate)
+  --include-user            add user-level files and MCP servers from your home directory
+  --mcp                     start the configured MCP servers and count their tool definitions
+  --mcp-timeout <s>         seconds to wait for each MCP server (default 30)
+  --baseline <file.json>    compare with an earlier --json report
+  --compare <git-ref>       compare with the instruction files at a git ref
+  --max-increase <n>        exit 1 when any tool grows by more than n tokens per turn vs the baseline
   --claude-api              exact Claude counts (ANTHROPIC_API_KEY)
   --gemini-api              Gemini counts (GEMINI_API_KEY)
   --english <file=en>       measure a language multiplier against your English version
@@ -76,12 +186,12 @@ turntax [path]
 
 Offline by default: no network calls, no telemetry. File contents are sent only when you pass `--claude-api`, `--gemini-api` or `--translate`, and only to that vendor's API. Keys are read from environment variables and sent only in request headers.
 
+`--mcp` runs the commands in the MCP configs it finds and connects to the configured HTTP servers, as the agents themselves would. Run it only on repositories whose configs you trust. `turntax` prints each command before starting it. `--include-user` reads files in your home directory and never sends them anywhere.
+
 ## Web page
 
 [`web/`](web) is a static page that runs the same engine in the browser with the offline tokenizer only. Drop a repository folder or paste files; nothing is uploaded.
 
-Try it: https://torutdev.github.io/turntax/
-
 ```bash
 npm run build:web
 ```
@@ -94,12 +204,12 @@ npx turntax --badge
 
 [![context tax (o200k)](https://img.shields.io/badge/context%20tax%20(o200k)-297%20tokens%2Fturn-brightgreen)](https://github.com/TorutDev/turntax)
 
-The badge shows the largest always-loaded total among the tools found, counted with o200k_base.
+The badge shows the largest always-loaded total among the tools found, counted with o200k_base: repository files plus measured project MCP tools, never user-level files.
 
 ## Limits
 
-- Assumes the agent starts at the repository root. Files outside the repository (user-level `~/.claude/CLAUDE.md`, global rules, team rules in a dashboard) are not counted.
-- Counts instruction files only, not the agent's own system prompt, tool definitions or MCP servers.
+- Assumes the agent starts at the repository root. User-level files are counted only with `--include-user`; rules kept in an app's settings or a team dashboard (Cursor user rules, Copilot organization instructions) are not counted.
+- Counts instruction files and, with `--mcp`, MCP tool definitions; not the agent's own system prompt or built-in tools.
 - Loading rules change. Each rule cites the vendor page and the date it was checked; please open an issue when one is out of date.
 
 ## Contributing

package/dist/cli.js

@@ -1,13 +1,19 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { basename, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { hasNonEnglish } from './core/advice.js';
 import { audit } from './core/audit.js';
 import { classify } from './core/classify.js';
+import { asDiffInput, diffReports, maxIncrease } from './core/diff.js';
+import { parseMcpConfigs, serverKey, toolDefinitionsText, toolNamesText } from './core/mcp.js';
 import { DEFAULT_MODEL_IDS, MODELS, validateModels } from './core/prices.js';
-import { badgeMarkdown, headlineTokens, renderMarkdown, renderText } from './core/render.js';
+import { badgeMarkdown, headlineTokens, renderMarkdown, renderPrComment, renderText } from './core/render.js';
+import { countO200k } from './core/tokenize.js';
 import { TOOL_IDS } from './core/tools.js';
-import { discover, existsIn, packageScripts } from './node/discover.js';
+import { discover, discoverMcpConfigs, discoverUser, existsIn, packageScripts } from './node/discover.js';
+import { filesAtRef } from './node/git.js';
+import { measureServer } from './node/mcp.js';
 import { anthropicCounter, geminiCounter, translateToEnglish } from './node/remote.js';
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const HELP = `turntax ${VERSION}
@@ -22,9 +28,20 @@ Options:
   --turns <n>             Turns for the cost projection (default: 100)
   --json                  Print the full report as JSON
   --md                    Print a Markdown report
+  --pr-comment            Print a pull request comment: the change first, the full report folded
   --out <file>            Write the report to a file instead of stdout
   --badge                 Print a shields.io badge snippet
   --max-tokens <n>        Exit with code 1 if any tool loads more than n o200k tokens per turn
+                          (repository files plus measured project MCP tools)
+  --include-user          Also count user-level files and MCP servers in your home directory
+                          (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...)
+  --mcp                   Start the configured MCP servers and count their tool definitions
+                          (runs the commands in .mcp.json and the other agents' MCP configs)
+  --mcp-timeout <s>       Seconds to wait for each MCP server (default: 30)
+  --baseline <file.json>  Compare with an earlier --json report
+  --compare <git-ref>     Compare with the instruction files at a git ref (for example origin/main)
+  --max-increase <n>      Exit with code 1 if any tool's per-turn tokens grew by more than n
+                          compared with --baseline or --compare
   --claude-api            Count Claude tokens with Anthropic's count_tokens (needs ANTHROPIC_API_KEY;
                           sends file contents to api.anthropic.com)
   --gemini-api            Count Gemini tokens with Google's countTokens (needs GEMINI_API_KEY;
@@ -37,7 +54,7 @@ Options:
   -h, --help              Show help
   -v, --version           Show version
 
-Without --claude-api or --gemini-api nothing leaves your machine.
+Without --claude-api, --gemini-api or --mcp nothing leaves your machine.
 `;
 class UsageError extends Error {
 }
@@ -68,6 +85,7 @@ export async function main(argv, env = process.env) {
                 turns: { type: 'string' },
                 json: { type: 'boolean' },
                 md: { type: 'boolean' },
+                'pr-comment': { type: 'boolean' },
                 out: { type: 'string' },
                 badge: { type: 'boolean' },
                 'max-tokens': { type: 'string' },
@@ -77,6 +95,12 @@ export async function main(argv, env = process.env) {
                 translate: { type: 'boolean' },
                 prices: { type: 'string' },
                 'section-tokens': { type: 'string' },
+                'include-user': { type: 'boolean' },
+                mcp: { type: 'boolean' },
+                'mcp-timeout': { type: 'string' },
+                baseline: { type: 'string' },
+                compare: { type: 'string' },
+                'max-increase': { type: 'string' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
             },
@@ -121,6 +145,27 @@ export async function main(argv, env = process.env) {
                 throw new UsageError(`Unknown tool "${t}". Use: ${TOOL_IDS.join(', ')}`);
         const root = resolve(positionals[0] ?? '.');
         const files = await discover(root);
+        if (o.baseline && o.compare)
+            throw new UsageError('Use --baseline or --compare, not both.');
+        if (o['max-increase'] !== undefined && !o.baseline && !o.compare)
+            throw new UsageError('--max-increase needs --baseline or --compare.');
+        const maxIncreaseLimit = o['max-increase'] === undefined ? undefined : nonNegativeInt('max-increase', o['max-increase']);
+        let userFiles = [];
+        let mcpFiles = discoverMcpConfigs(root);
+        if (o['include-user']) {
+            const user = discoverUser(env.HOME || env.USERPROFILE || homedir());
+            userFiles = user.files;
+            mcpFiles = [...mcpFiles, ...user.mcpConfigs];
+        }
+        const parsedMcp = parseMcpConfigs(mcpFiles, root);
+        for (const p of parsedMcp.problems)
+            notice(`${p.path} ${p.message}`);
+        const servers = parsedMcp.servers;
+        let measured;
+        if (o.mcp) {
+            const timeoutMs = positiveInt('mcp-timeout', o['mcp-timeout'], 30) * 1000;
+            measured = await measureAll(servers.filter((s) => !s.disabled && (!tools || tools.includes(s.tool))), root, timeoutMs, env);
+        }
         const counters = {};
         if (o['claude-api']) {
             const key = env.ANTHROPIC_API_KEY;
@@ -167,6 +212,8 @@ export async function main(argv, env = process.env) {
             models,
             counters,
             turns: positiveInt('turns', o.turns, 100),
+            userFiles,
+            mcp: { servers, measured },
             advice: {
                 exists: existsIn(root),
                 packageScripts: packageScripts(root),
@@ -174,23 +221,51 @@ export async function main(argv, env = process.env) {
                 sectionTokens: positiveInt('section-tokens', o['section-tokens'], 600),
             },
         });
+        if (o.baseline) {
+            let data;
+            try {
+                data = JSON.parse(readFileSync(o.baseline, 'utf8'));
+            }
+            catch (e) {
+                throw new UsageError(`Could not read --baseline ${o.baseline}: ${e.message}`);
+            }
+            report.diff = diffReports(asDiffInput(data), report, basename(o.baseline));
+        }
+        else if (o.compare) {
+            const base = await filesAtRef(root, o.compare).catch((e) => {
+                throw new UsageError(e.message);
+            });
+            const before = await audit(base.files, {
+                tools,
+                models: [],
+                mcp: { servers: parseMcpConfigs(base.mcpConfigs, root).servers },
+            });
+            report.diff = diffReports(before, report, o.compare);
+        }
         const output = o.json
             ? JSON.stringify({ root, ...report }, null, 2) + '\n'
-            : o.md
-                ? renderMarkdown(report)
-                : o.badge
-                    ? badgeMarkdown(report) + '\n'
-                    : renderText(report, root) + '\n';
+            : o['pr-comment']
+                ? renderPrComment(report)
+                : o.md
+                    ? renderMarkdown(report)
+                    : o.badge
+                        ? badgeMarkdown(report) + '\n'
+                        : renderText(report, root) + '\n';
         if (o.out)
             writeFileSync(o.out, output);
         else
             process.stdout.write(output);
+        let code = 0;
         const max = o['max-tokens'] === undefined ? undefined : positiveInt('max-tokens', o['max-tokens'], 0);
         if (max !== undefined && headlineTokens(report) > max) {
             process.stderr.write(`turntax: ${headlineTokens(report)} o200k tokens per turn exceeds --max-tokens ${max}\n`);
-            return 1;
+            code = 1;
         }
-        return 0;
+        if (maxIncreaseLimit !== undefined && report.diff && maxIncrease(report.diff) > maxIncreaseLimit) {
+            process.stderr.write(`turntax: per-turn tokens grew by ${maxIncrease(report.diff)} vs ${report.diff.base}, more than --max-increase ${maxIncreaseLimit}\n`);
+            code = 1;
+        }
+        return code;
     }
     catch (e) {
         if (e instanceof UsageError) {
@@ -201,6 +276,40 @@ export async function main(argv, env = process.env) {
         return 1;
     }
 }
+function nonNegativeInt(name, value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0)
+        throw new UsageError(`--${name} must be a non-negative integer`);
+    return n;
+}
+/** Starts each distinct server once (several agents often share one) and counts its tool definitions. */
+async function measureAll(servers, root, timeoutMs, env) {
+    const unique = new Map();
+    for (const s of servers)
+        if (!unique.has(serverKey(s)))
+            unique.set(serverKey(s), s);
+    const out = new Map();
+    const queue = [...unique.entries()];
+    for (const [, s] of queue)
+        notice(s.transport === 'stdio'
+            ? `Starting MCP server "${s.name}" from ${s.configPath}: ${[s.command, ...(s.args ?? [])].join(' ')}`
+            : `Connecting to MCP server "${s.name}" from ${s.configPath}: ${s.url}`);
+    const worker = async () => {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            const [key, s] = next;
+            const r = await measureServer(s, { root, timeoutMs, env });
+            if (r.tools) {
+                out.set(key, { tools: r.tools.length, o200k: countO200k(toolDefinitionsText(r.tools)), namesO200k: countO200k(toolNamesText(r.tools)) });
+            }
+            else {
+                out.set(key, { error: r.error ?? 'failed' });
+                notice(`MCP server "${s.name}" was not measured: ${r.error}`);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(4, queue.length) }, worker));
+    return out;
+}
 function notice(message) {
     process.stderr.write(`turntax: ${message}\n`);
 }

package/dist/core/advice.js

@@ -3,14 +3,16 @@ import { countO200k } from './tokenize.js';
 import { TOOLS } from './tools.js';
 const DEFAULT_SECTION_TOKENS = 600;
 export function buildAdvice(units, files, opts = {}) {
+    // User-level files take part in checks across files; moving sections or checking paths only makes sense in the repository.
+    const repo = units.filter((u) => !u.scope);
     const advice = [
         ...misconfigured(units),
         ...sizeLimits(units, files),
         ...duplicates(units),
         ...contradictions(units),
-        ...sections(units, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
+        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
         ...nonEnglish(units, opts.english),
-        ...staleReferences(units, opts),
+        ...staleReferences(repo, opts),
     ];
     const order = { high: 0, medium: 1, low: 2 };
     return advice.sort((a, b) => order[a.severity] - order[b.severity] || (b.savingTokens ?? 0) - (a.savingTokens ?? 0));
@@ -396,7 +398,7 @@ function nonEnglish(units, english) {
 /** True for instruction files that live in a package subdirectory rather than at the root or in a root tool folder. */
 function isNested(path) {
     const dir = dirname(path);
-    return dir !== '' && !/^\.(claude|github|cursor|windsurf|devin|agents)(\/|$)/.test(dir);
+    return dir !== '' && !/^\.(claude|github|cursor|windsurf|devin|agents|clinerules|cline|roo|kiro|junie|continue)(\/|$)/.test(dir);
 }
 function staleReferences(units, opts) {
     const out = [];

package/dist/core/audit.js

@@ -1,7 +1,9 @@
 import { buildAdvice } from './advice.js';
 import { classify, detectTools } from './classify.js';
+import { defersTools, serverKey } from './mcp.js';
 import { countO200k, offlineCounter } from './tokenize.js';
 import { TOOLS } from './tools.js';
+import { classifyUser } from './user.js';
 export function modelsForTool(tool, models) {
     const spec = TOOLS.find((t) => t.id === tool);
     return spec.families.length ? models.filter((m) => spec.families.includes(m.family)) : models;
@@ -15,9 +17,12 @@ function counterFor(model, opts) {
 }
 export async function audit(files, opts) {
     const turns = opts.turns ?? 100;
-    const allUnits = classify(files);
-    const toolIds = opts.tools ?? detectTools(allUnits);
+    const allUnits = [...classify(files), ...classifyUser(opts.userFiles ?? [])];
+    const servers = opts.mcp?.servers ?? [];
+    const toolIds = opts.tools ??
+        [...new Set([...detectTools(allUnits), ...servers.filter((s) => !s.disabled).map((s) => s.tool)])].sort((a, b) => TOOLS.findIndex((t) => t.id === a) - TOOLS.findIndex((t) => t.id === b));
     const units = allUnits.filter((u) => toolIds.includes(u.tool));
+    const mcp = servers.filter((s) => toolIds.includes(s.tool)).map((s) => mcpRow(s, opts.mcp?.measured));
     // Count each distinct text once per model, only for the tools that run that model.
     const counts = new Map();
     for (const model of opts.models) {
@@ -39,6 +44,8 @@ export async function audit(files, opts) {
         };
         if (u.importedFrom)
             row.importedFrom = u.importedFrom;
+        if (u.scope)
+            row.scope = u.scope;
         if (u.mode !== 'ignored')
             for (const m of modelsForTool(u.tool, opts.models)) {
                 const c = counts.get(m.id)?.get(u.text);
@@ -51,21 +58,48 @@ export async function audit(files, opts) {
         const spec = TOOLS.find((t) => t.id === id);
         const rows = files_.filter((r) => r.tool === id);
         const always = rows.filter((r) => r.mode === 'always');
-        const onDemand = rows.filter((r) => r.mode === 'on-demand');
+        const repoAlways = always.filter((r) => !r.scope);
+        const userAlways = always.filter((r) => r.scope === 'user');
+        const onDemand = rows.filter((r) => r.mode === 'on-demand' && !r.scope);
         const models = modelsForTool(id, opts.models).map((m) => modelCost(m, always, turns));
+        const toolMcp = mcp.filter((r) => r.tool === id && r.status !== 'disabled');
+        const mcpTokens = (scope) => sum(toolMcp.filter((r) => r.scope === scope).map((r) => r.o200k ?? 0));
+        const perTurnO200k = sum(repoAlways.map((r) => r.o200k));
+        const userPerTurnO200k = sum(userAlways.map((r) => r.o200k)) + mcpTokens('user');
+        const mcpPerTurnO200k = mcpTokens('project');
         return {
             tool: id,
             name: spec.name,
-            alwaysFiles: new Set(always.map((r) => r.path)).size,
+            alwaysFiles: new Set(repoAlways.map((r) => r.path)).size,
             onDemandFiles: new Set(onDemand.map((r) => r.path)).size,
-            perTurnO200k: sum(always.map((r) => r.o200k)),
+            perTurnO200k,
             onDemandO200k: sum(onDemand.map((r) => r.o200k)),
+            userAlwaysFiles: new Set(userAlways.map((r) => r.path)).size,
+            userPerTurnO200k,
+            mcpServers: toolMcp.length,
+            mcpPerTurnO200k,
+            mcpMeasured: toolMcp.every((r) => r.status === 'measured'),
+            totalPerTurnO200k: perTurnO200k + mcpPerTurnO200k + userPerTurnO200k,
             models,
             notes: spec.notes,
             sources: spec.sources,
         };
     });
-    return { turns, tools, files: files_, advice: buildAdvice(units, files, opts.advice), models: opts.models };
+    const adviceFiles = [...files, ...(opts.userFiles ?? [])];
+    return { turns, tools, files: files_, advice: buildAdvice(units, adviceFiles, opts.advice), models: opts.models, mcp };
+}
+function mcpRow(s, measured) {
+    const row = { name: s.name, tool: s.tool, configPath: s.configPath, scope: s.scope, transport: s.transport, status: 'not-measured' };
+    if (s.disabled)
+        return { ...row, status: 'disabled' };
+    const m = measured?.get(serverKey(s));
+    if (!m)
+        return row;
+    if ('error' in m)
+        return { ...row, status: 'failed', error: m.error };
+    if (defersTools(s))
+        return { ...row, status: 'measured', tools: m.tools, o200k: m.namesO200k, deferredO200k: m.o200k };
+    return { ...row, status: 'measured', tools: m.tools, o200k: m.o200k };
 }
 function modelCost(model, always, turns) {
     const counts = always.map((r) => r.counts[model.id]);

package/dist/core/classify.js

@@ -1,4 +1,4 @@
-import { basename, dirname, findImports, firstParagraph, parseFrontmatter, resolvePath, stripHtmlComments } from './markdown.js';
+import { basename, configList, dirname, findImports, firstParagraph, parseFrontmatter, resolvePath, stripHtmlComments } from './markdown.js';
 import { TOOLS } from './tools.js';
 /** Works out which files each tool loads, when, and with what text. */
 export function classify(input, toolIds) {
@@ -48,6 +48,28 @@ function applyRule(tool, rule, files, byPath) {
             return files
                 .filter((f) => rule.pattern.test(f.path))
                 .map((f) => unit(tool.id, f.path, 'ignored', rule.reason, f.text, { problem: rule.reason }));
+        case 'pattern':
+            return files
+                .filter((f) => rule.pattern.test(f.path))
+                .map((f) => unit(tool.id, f.path, rule.mode, rule.trigger, f.text, { notes: rule.note ? [rule.note] : [] }));
+        case 'precedence': {
+            const inGroup = (g) => files.filter((f) => g.patterns.some((p) => p.test(f.path)));
+            const winner = rule.groups.find((g) => inGroup(g).length > 0);
+            if (!winner)
+                return [];
+            return rule.groups.flatMap((g) => inGroup(g).map((f) => g === winner
+                ? unit(tool.id, f.path, 'always', 'project instructions', f.text, { notes: rule.note ? [rule.note] : [] })
+                : unit(tool.id, f.path, 'ignored', `${winner.label} takes precedence`, f.text)));
+        }
+        case 'config-list': {
+            const config = byPath.get(rule.configPath);
+            if (!config)
+                return [];
+            return configList(config, rule.key)
+                .map((p) => byPath.get(p))
+                .filter((f) => f !== undefined)
+                .map((f) => unit(tool.id, f.path, 'always', rule.trigger, f.text));
+        }
         case 'frontmatter':
             return files
                 .filter((f) => rule.pattern.test(f.path))
@@ -111,19 +133,27 @@ function applyHierarchical(tool, rule, files, byPath) {
         conditionFails = 'CLAUDE.md exists at the root, so Claude Code reads it instead of AGENTS.md (default setting).';
     if (rule.condition === 'copilot-no-agents-md' && files.some((f) => f.path === 'AGENTS.md'))
         conditionFails = 'A root AGENTS.md exists, which Copilot uses instead.';
-    const winners = new Map();
+    // Every matching file is read, except where the tool reads only one file per directory.
+    const firstPerLevel = new Map();
+    const read = [];
     const out = [];
     for (const name of rule.names) {
         for (const f of matches.filter((m) => basename(m.path) === name)) {
             const level = levelOf(f.path, rule.sameLevelDirs);
-            if (rule.onePerDirectory && winners.has(level)) {
-                out.push(unit(tool.id, f.path, 'ignored', `${basename(winners.get(level).path)} takes precedence`, f.text));
+            // The docs do not say when subdirectory copies load, so they are not counted either way.
+            if (level !== '' && rule.nested === 'skip')
+                continue;
+            const first = firstPerLevel.get(level);
+            if (rule.onePerDirectory && first) {
+                out.push(unit(tool.id, f.path, 'ignored', `${basename(first.path)} takes precedence`, f.text));
                 continue;
             }
-            winners.set(level, f);
+            if (!first)
+                firstPerLevel.set(level, f);
+            read.push(f);
         }
     }
-    for (const f of winners.values()) {
+    for (const f of read) {
         if (conditionFails) {
             out.push(unit(tool.id, f.path, 'ignored', conditionFails, f.text));
             continue;
@@ -186,7 +216,18 @@ function expandImports(tool, parent, rule, byPath, depth, seen = new Set([parent
             continue;
         seen.add(resolved);
         const notes = [];
-        const child = unit(tool, f.path, parent.mode, parent.trigger, transform(f.text, rule, notes), {
+        let mode = parent.mode;
+        let trigger = parent.trigger;
+        let text = f.text;
+        if (rule.importGlobs) {
+            const { frontmatter, body } = parseFrontmatter(f.text);
+            if (frontmatter.globs !== undefined && String(frontmatter.globs) !== '') {
+                mode = 'on-demand';
+                trigger = `globs: ${Array.isArray(frontmatter.globs) ? frontmatter.globs.join(', ') : String(frontmatter.globs)}`;
+                text = body;
+            }
+        }
+        const child = unit(tool, f.path, mode, trigger, transform(text, rule, notes), {
             importedFrom: parent.path,
             notes,
         });