my observations

[lukasMega]

Hello,
first, thank you for your work and interesting project!

Here is my observation:

outputs of sigmap commands:

npx sigmap && npx sigmap --report && npx sigmap --health:

npx sigmap && npx sigmap --report && npx sigmap --health

[sigmap] wrote AGENTS.md (appended signatures)
───────────────────────────────────────────
 SigMap v5.4.0
 Files scanned  : 51
 Symbols found  : 195
 Token reduction: 99%  (358,064 → 2,665)
 Coverage       : D (39%)  — 51 of 131 source files included
 [sigmap] tip: large repo — consider strategy:"per-module" for full coverage
 Output         : .github/copilot-instructions.md
───────────────────────────────────────────
 Try: "explain the architecture" · "find the auth module"
───────────────────────────────────────────


[sigmap] report:
  version         : 5.4.0
  files processed : 51
  files dropped   : 0
  input tokens    : ~358064
  output tokens   : ~2665
  budget limit    : 5000 (fixed)
  reduction       : 99.3%
  coverage        : D (39%)  — 51 of 131 source files included
  confidence      : LOW

  Module Coverage:
    pkgs/core          ████████░░░░░░░░  52% (13/25 files)
    pkgs/cli           ██████░░░░░░░░░░  39% (18/46 files)  ← attention needed
    pkgs/cli-tjs       █████████░░░░░░░  57% (13/23 files)
    pkgs/lang-js       ██░░░░░░░░░░░░░░  13% (1/8 files)  ← attention needed
    pkgs/lang-java     ████░░░░░░░░░░░░  25% (2/8 files)  ← attention needed
    pkgs/lang-kotlin   ████░░░░░░░░░░░░  25% (2/8 files)  ← attention needed
    pkgs/eslint-plugin ██░░░░░░░░░░░░░░  13% (1/8 files)  ← attention needed
    pkgs/eslint-plugin-protect ███░░░░░░░░░░░░░  20% (1/5 files)  ← attention needed


[sigmap] health:
  score           : 100/100 (grade A)
  coverage        : A (100%)  — 131 of 131 source files
  strategy        : full
  token reduction : no history
  days since regen: context file not found
  total runs      : 0
  over-budget runs: 0
  p50 token count : 0
  p95 token count : 0
  overbudget streak: 0
  extractor cover.: 14.3%

First thing I noticed 👁️ the coverage is quite low and lot of ← attention needed

• however I didn't find it in your docs what user needs to do with ← attention needed

I'm using this config (specific for my project (CPL - not public yet)):

{
  "srcDirs": [
    "pkgs/core",
    "pkgs/cli",
    "pkgs/cli-tjs",
    "pkgs/lang-js",
    "pkgs/lang-java",
    "pkgs/lang-kotlin",
    "pkgs/eslint-plugin",
    "pkgs/eslint-plugin-protect"
  ],
  "strategy": "full",
  "monorepo": false,
  "autoMaxTokens": false,
  "maxTokens": 5000,
  "outputs": ["codex"]
}

• since I didn't want to sigmap modify CLAUDE.md I'm using output codex for now
• I tried also monorepo: true but no significant change

and also I defined .contextignore file:

file content:

lib/
pkgs/bench/
examples/
node_modules/
**/node_modules/
dist/
**/dist/
test-output/
**/test-output/
coverage/
**/tsconfig.tsbuildinfo
**/*.config.ts
**/*.jsonc
**/*.jsonl

I let claude analyze my project and sigmap codebase:

click to see

Sigmap Coverage Metric Is Misleading for CPL repo

Finding

Sigmap's coverage grade (D/39%) for CPL repo is not a reliable quality indicator. The denominator (131 "source files") includes non-code files that sigmap physically cannot extract signatures from:

• package.json, tsconfig.json, tsconfig.tsbuildinfo per package
• vitest.config.ts (minimal/no extractable exports)
• .github/context-*.md files generated by a previous sigmap monorepo run
• README.md and other markdown
• Empty .github/ directories

Sigmap filters files with zero extractable signatures before budget enforcement (line 7763 in gen-context.js), so no config change can improve the grade for these files.

Actual Output Quality

The current AGENTS.md (51 files, 195 symbols, ~2665 tokens) is comprehensive and covers all meaningful code:

• All pkgs/core public types and functions
• All pkgs/cli commands and adapters
• All pkgs/cli-tjs shims and adapters
• Walkers for lang-js, lang-java, lang-kotlin
• ESLint plugin sync-hash
• Bundled protect.js with full internals

Working Config (gen-context.config.json)

{
  "srcDirs": ["pkgs/core", "pkgs/cli", "pkgs/cli-tjs", "pkgs/lang-js",
              "pkgs/lang-java", "pkgs/lang-kotlin", "pkgs/eslint-plugin",
              "pkgs/eslint-plugin-protect"],
  "strategy": "full",
  "monorepo": false,
  "autoMaxTokens": false,
  "maxTokens": 5000,
  "outputs": ["codex"]
}

maxTokens: 5000 is sufficient — actual output is ~2665 tokens. Raising it has no effect.

Health vs Report: Two Different Coverage Metrics

npx sigmap --health and npx sigmap --report measure different things:

Command	Coverage shown	Meaning
--report	D (39%) — 51/131	Files that had ≥1 extractable signature
--health	A (100%) — 131/131	Files that were successfully scanned

Health score 100/100 (A) is the correct signal — sigmap successfully processed all files.
The D-grade from --report reflects that 80 of 131 files have zero extractable signatures (they're non-code files).

--health also shows extractor coverage: 14.3% — sigmap's parsers only recognize 14.3% of file types in the project, which is expected (the rest are JSON, YAML, shell, markdown, etc.).

What Does NOT Work

• autoMaxTokens: true — auto-scales to the 4000-token floor for small repos regardless of modelContextLimit or maxTokens
• monorepo: true (sigmap 5.4.0) — processes each srcDir as a separate project, writes per-package .github/context-*.md files and AGENTS.md inside each pkgs/*/ dir; root AGENTS.md gets only overview summaries that Claude Code cannot deep-read
• strategy: "per-module" + monorepo: true — creates deeply nested context files Claude Code never sees
• Raising maxTokens beyond ~5000 — has no effect since only ~2665 tokens are actually used

Key Sigmap Behavior (v5.4.0)

• Files with 0 extractable signatures are excluded before budget enforcement (gen-context.js line 7763)
• Budget enforcement only drops lowest-priority files when total > budget
• diffPriority: true (default) ranks recently-changed files higher but does not exclude stable files when budget is available
• strategy: "full" + monorepo: false produces a single root AGENTS.md — the correct target for Claude Code

======================================= endd of claude findings ===============================

---

Conclusion?

If I understand correctly, I should NOT worry about low coverage in --report output, right?

sigmap's parsers only recognize 14.3% of file types in the project, which is expected (the rest are JSON, YAML, shell, markdown, etc.).

Maybe my use of Sigmap isn't ideal, but since I'm new and cautious I want to adopt Sigmap into my project gradually — only the basic features for now; I may add advanced features later.

[manojmallick]

Hi @lukasMega — great analysis, and Claude gave you exactly the right answer!

Short answer: Your config is correct and you should not worry about the D (39%) coverage.

Why the numbers differ:

--health coverage (A, 100%) = "how many files in your srcDirs could sigmap even see?" — this is computed by passing all found files as fake "included" entries, so it's always 100%.
--report coverage (D, 39%) = "of all files sigmap found, how many produced at least one extractable signature?" — the 80 missing files are package.json, tsconfig.json, README.md, .config.ts etc. that sigmap's extractors don't support.
Your actual output is healthy: 51 files, 195 symbols, ~2665 tokens, well under your 5000 budget. The health score A (100/100) is the right signal.

On ← attention needed: This flag means a module has <50% file coverage. In your case it's expected — most of those are non-code files. I'm going to fix the output to explain this rather than leaving you to guess.

Recommended config for gradual adoption (what you already have is good):

{
"strategy": "full",
"monorepo": false,
"outputs": ["codex"],
"maxTokens": 5000
}
Keep monorepo: false — monorepo: true fragments the output into per-package files that Claude Code can't deep-read from the root.