@caddis/cli 0.4.91 → 0.4.93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/plugin.json +1 -1
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  16. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  17. package/bundles/antigravity-plugin/scripts/caddis_gate.py +8 -8
  18. package/bundles/antigravity-plugin/scripts/caddis_guide.json +58 -6
  19. package/bundles/antigravity-plugin/scripts/caddis_lanes.py +17 -17
  20. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  21. package/bundles/antigravity-plugin/scripts/caddis_review.py +1 -1
  22. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +25 -39
  23. package/bundles/antigravity-plugin/scripts/caddis_routing.py +1 -1
  24. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  25. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  26. package/bundles/antigravity-plugin/scripts/caddis_spend.py +121 -138
  27. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  28. package/bundles/antigravity-plugin/scripts/oss_review.py +15 -13
  29. package/bundles/antigravity-plugin/scripts/roadmap-recheck.ps1 +4 -2
  30. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +6 -0
  31. package/bundles/antigravity-plugin/scripts/schemas/hub-spend.schema.json +6 -0
  32. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +65 -1
  33. package/bundles/antigravity-plugin/skills/_registry.md +3 -1
  34. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
  35. package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
  36. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +1 -1
  37. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +8 -2
  38. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  39. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  40. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  41. package/bundles/antigravity-plugin/skills/implement/SKILL.md +10 -6
  42. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  43. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  44. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +10 -6
  45. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +7 -6
  46. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  47. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  48. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  49. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  50. package/bundles/antigravity-plugin-extras/skills/_registry.md +1 -0
  51. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  52. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  53. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  54. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  55. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  56. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  57. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +10 -6
  58. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +7 -6
  59. package/bundles/manifest.json +3 -3
  60. package/dist/export/assets/export-CMtV-slT.css +1 -0
  61. package/dist/export/index.html +2 -2
  62. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  63. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  64. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  65. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  66. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  67. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  68. package/dist/ui/index.html +2 -2
  69. package/package.json +1 -1
  70. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  71. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  72. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  73. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  74. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -0,0 +1,554 @@
1
+ #!/usr/bin/env python3
2
+ """caddis /preload-review: how big is what loads before the first prompt?
3
+
4
+ Reads files only. Measures (estimated tokens, chars / 4):
5
+ user rules ~/.claude/CLAUDE.md and ~/AGENTS.md, with their @imports
6
+ enabled skills name + description of every skill in the enabled plugins (plugin cache) and ~/.claude/skills
7
+ MCP server names from ~/.claude.json and <repo>/.mcp.json (names only, never a value)
8
+ per repo root rules (+ @imports) and the MEMORY.md index = start-up cost;
9
+ nested CLAUDE.md / AGENTS.md load on demand, so they are reported apart
10
+
11
+ Secrets: `~/.claude/settings.json` is read for the `enabledPlugins` key only. `~/.claude.json` is read for
12
+ server names only. A file that does not parse is reported by error class name, never by message.
13
+
14
+ CLI: caddis_preload_review.py [--root PATH] [--home PATH] [--json] [--limit-repo-startup N]
15
+ [--limit-memory N] [--stamp]
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import argparse
20
+ import contextlib
21
+ import datetime as dt
22
+ import hashlib
23
+ import json
24
+ import os
25
+ import re
26
+ import sys
27
+ from dataclasses import asdict, dataclass, field
28
+ from pathlib import Path
29
+
30
+ _reconfig = getattr(sys.stdout, "reconfigure", None)
31
+ if _reconfig:
32
+ with contextlib.suppress(OSError, ValueError):
33
+ _reconfig(encoding="utf-8")
34
+
35
+ MAX_IMPORT_DEPTH = 4
36
+ # Folders the nested-rules walk never enters.
37
+ SKIP_DIRS = frozenset({"node_modules", ".git", ".worktrees", ".venv", "venv", "__pycache__", "dist", "build", ".next"})
38
+ RULE_NAMES = ("CLAUDE.md", "AGENTS.md")
39
+ _IMPORT_RE = re.compile(r"^\s*@(\S+)")
40
+ _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
41
+
42
+
43
+ # ── data ─────────────────────────────────────────────────────────────────────
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class PluginSkills:
48
+ plugin: str
49
+ version: str
50
+ count: int
51
+ chars: int
52
+
53
+
54
+ @dataclass(frozen=True)
55
+ class RepoRow:
56
+ name: str
57
+ rules_chars: int
58
+ memory_index_chars: int
59
+ memory_index_lines: int
60
+ memory_files: int
61
+ memory_chars: int
62
+ nested_files: int
63
+ nested_chars: int
64
+ project_skills: int
65
+ has_mcp_json: bool
66
+
67
+
68
+ @dataclass(frozen=True)
69
+ class UserRow:
70
+ rules_chars: int
71
+ skills: list[PluginSkills] = field(default_factory=list)
72
+ mcp: list[str] = field(default_factory=list)
73
+ enabled_known: bool = True
74
+
75
+
76
+ # ── measure ──────────────────────────────────────────────────────────────────
77
+
78
+
79
+ def est_tokens(chars: int) -> int:
80
+ """Token estimate: chars / 4. An estimate only."""
81
+ return round(chars / 4)
82
+
83
+
84
+ def _read_text(path: Path) -> str | None:
85
+ try:
86
+ return path.read_text(encoding="utf-8", errors="replace")
87
+ except OSError:
88
+ return None
89
+
90
+
91
+ def _import_target(ref: str, importer: Path, home: Path) -> Path:
92
+ if ref == "~" or ref.startswith(("~/", "~\\")):
93
+ return home / ref[2:]
94
+ target = Path(ref)
95
+ return target if target.is_absolute() else importer.parent / target
96
+
97
+
98
+ def _import_refs(text: str) -> list[str]:
99
+ """`@path` lines outside fenced code blocks."""
100
+ refs: list[str] = []
101
+ fence = ""
102
+ for line in text.splitlines():
103
+ m = _FENCE_RE.match(line)
104
+ if m:
105
+ marker = m.group(1)
106
+ if not fence:
107
+ fence = marker
108
+ elif marker[0] == fence[0] and len(marker) >= len(fence):
109
+ fence = ""
110
+ continue
111
+ if fence:
112
+ continue
113
+ m = _IMPORT_RE.match(line)
114
+ if m:
115
+ refs.append(m.group(1))
116
+ return refs
117
+
118
+
119
+ def rules_chars(path: Path, home: Path, _seen: set[Path] | None = None, _depth: int = 0) -> int:
120
+ """Chars of a rules file plus the files it imports with `@path` (depth 4, each file once)."""
121
+ seen = _seen if _seen is not None else set()
122
+ if _depth > MAX_IMPORT_DEPTH:
123
+ return 0
124
+ try:
125
+ key = path.resolve()
126
+ except OSError:
127
+ return 0
128
+ if key in seen or not path.is_file():
129
+ return 0
130
+ text = _read_text(path)
131
+ if text is None:
132
+ return 0
133
+ seen.add(key)
134
+ total = len(text)
135
+ for ref in _import_refs(text):
136
+ total += rules_chars(_import_target(ref, path, home), home, seen, _depth + 1)
137
+ return total
138
+
139
+
140
+ def _load_json_keys(path: Path) -> tuple[dict | None, str | None]:
141
+ """(parsed object, None), or (None, error class name). Never returns an error message."""
142
+ try:
143
+ data = json.loads(path.read_text(encoding="utf-8"))
144
+ except (OSError, ValueError) as e:
145
+ return None, type(e).__name__
146
+ return (data, None) if isinstance(data, dict) else (None, "NotAnObject")
147
+
148
+
149
+ def enabled_plugins(home: Path) -> set[str] | None:
150
+ """`plugin@marketplace` keys set to true in settings.json `enabledPlugins`. None = unknown."""
151
+ data, _err = _load_json_keys(home / ".claude" / "settings.json")
152
+ if data is None:
153
+ return None
154
+ plugins = data.get("enabledPlugins")
155
+ if not isinstance(plugins, dict):
156
+ return None
157
+ return {k for k, v in plugins.items() if v is True}
158
+
159
+
160
+ def _version_key(name: str) -> tuple[int, tuple[int, ...]]:
161
+ """Numeric versions compare as int tuples; anything else sorts below every numeric version."""
162
+ parts = name.split(".")
163
+ if all(p.isdigit() for p in parts):
164
+ return (1, tuple(int(p) for p in parts))
165
+ return (0, ())
166
+
167
+
168
+ def _strip_quotes(value: str) -> str:
169
+ value = value.strip()
170
+ if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
171
+ return value[1:-1]
172
+ return value
173
+
174
+
175
+ def _skill_chars(skill_md: Path) -> int:
176
+ """len(name) + len(description) from the SKILL.md frontmatter: what the skill list carries."""
177
+ text = _read_text(skill_md)
178
+ if text is None:
179
+ return 0
180
+ m = re.match(r"---\s*\n(.*?)\n---", text, re.DOTALL)
181
+ if not m:
182
+ return 0
183
+ fm = m.group(1)
184
+ name = re.search(r"^name:[ \t]*(.*)$", fm, re.MULTILINE)
185
+ desc = re.search(r"^description:[ \t]*(.*?)(?=^[\w-]+:|\Z)", fm, re.DOTALL | re.MULTILINE)
186
+ return len(_strip_quotes(name.group(1)) if name else "") + len(_strip_quotes(desc.group(1)) if desc else "")
187
+
188
+
189
+ def _skills_in(base: Path) -> tuple[int, int]:
190
+ files = sorted(base.glob("skills/*/SKILL.md"))
191
+ return len(files), sum(_skill_chars(f) for f in files)
192
+
193
+
194
+ def skill_listing(home: Path, enabled: set[str] | None) -> list[PluginSkills]:
195
+ """Skills per plugin from the plugin cache (newest version only), then user skills.
196
+
197
+ `enabled` None counts every cached plugin. A cache folder is `<marketplace>/<plugin>/<version>`.
198
+ """
199
+ out: list[PluginSkills] = []
200
+ cache = home / ".claude" / "plugins" / "cache"
201
+ if cache.is_dir():
202
+ for market in sorted(p for p in cache.iterdir() if p.is_dir()):
203
+ for plugin in sorted(p for p in market.iterdir() if p.is_dir()):
204
+ if enabled is not None and f"{plugin.name}@{market.name}" not in enabled:
205
+ continue
206
+ versions = [v for v in plugin.iterdir() if v.is_dir()]
207
+ if not versions:
208
+ continue
209
+ newest = max(versions, key=lambda v: (_version_key(v.name), v.name))
210
+ count, chars = _skills_in(newest)
211
+ if count:
212
+ out.append(PluginSkills(plugin.name, newest.name, count, chars))
213
+ user_skills = home / ".claude"
214
+ count, chars = _skills_in(user_skills)
215
+ if count:
216
+ out.append(PluginSkills("user", "", count, chars))
217
+ return out
218
+
219
+
220
+ def _norm(path: str | Path) -> str:
221
+ return os.path.normcase(os.path.normpath(str(path)))
222
+
223
+
224
+ def mcp_names(home: Path, repo: Path | None) -> list[str]:
225
+ """MCP server names only. A value, URL, argument or env var is never read into the result.
226
+
227
+ Sources: `~/.claude.json` `mcpServers` (user), its `projects[*].mcpServers` (the repo's entry, or all of
228
+ them when `repo` is None) and `<repo>/.mcp.json`. A file that does not parse adds `<unreadable: ErrorClass>`.
229
+ """
230
+ names: list[str] = []
231
+ data, err = _load_json_keys(home / ".claude.json")
232
+ if data is None:
233
+ if (home / ".claude.json").exists():
234
+ names.append(f"<unreadable ~/.claude.json: {err}>")
235
+ else:
236
+ servers = data.get("mcpServers")
237
+ if isinstance(servers, dict):
238
+ names += [str(n) for n in servers]
239
+ projects = data.get("projects")
240
+ if isinstance(projects, dict):
241
+ for proj_path, proj in projects.items():
242
+ if repo is not None and _norm(proj_path) != _norm(repo):
243
+ continue
244
+ if isinstance(proj, dict) and isinstance(proj.get("mcpServers"), dict):
245
+ label = Path(proj_path).name
246
+ names += [f"{n} ({label})" for n in proj["mcpServers"]]
247
+ if repo is not None:
248
+ mcp_json = repo / ".mcp.json"
249
+ pdata, perr = _load_json_keys(mcp_json)
250
+ if pdata is None:
251
+ if mcp_json.exists():
252
+ names.append(f"<unreadable .mcp.json: {perr}>")
253
+ elif isinstance(pdata.get("mcpServers"), dict):
254
+ names += [f"{n} (.mcp.json)" for n in pdata["mcpServers"]]
255
+ return list(dict.fromkeys(names))
256
+
257
+
258
+ def project_memory_dir(home: Path, repo: Path) -> Path:
259
+ """`~/.claude/projects/<repo path with every non-alphanumeric char as '-'>/memory`."""
260
+ return home / ".claude" / "projects" / re.sub(r"[^A-Za-z0-9]", "-", str(repo)) / "memory"
261
+
262
+
263
+ def _top_rule_files(root: Path) -> list[Path]:
264
+ return [root / "CLAUDE.md", root / "AGENTS.md", root / ".claude" / "CLAUDE.md", root / "CLAUDE.local.md"]
265
+
266
+
267
+ def _nested_rules(repo: Path) -> tuple[int, int]:
268
+ files = chars = 0
269
+ for dirpath, dirnames, filenames in os.walk(repo):
270
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
271
+ if Path(dirpath) == repo:
272
+ continue
273
+ for fname in filenames:
274
+ # <repo>/.claude/CLAUDE.md is a start-up file (counted in rules_chars), not a nested one
275
+ if fname in RULE_NAMES and Path(dirpath) != repo / ".claude":
276
+ text = _read_text(Path(dirpath) / fname)
277
+ if text is not None:
278
+ files += 1
279
+ chars += len(text)
280
+ return files, chars
281
+
282
+
283
+ def scan_repo(home: Path, repo: Path) -> RepoRow:
284
+ seen: set[Path] = set()
285
+ rules = sum(rules_chars(f, home, seen) for f in _top_rule_files(repo))
286
+ mem = project_memory_dir(home, repo)
287
+ index = _read_text(mem / "MEMORY.md") or ""
288
+ others = [f for f in sorted(mem.glob("*.md")) if f.name != "MEMORY.md"] if mem.is_dir() else []
289
+ mem_chars = sum(len(_read_text(f) or "") for f in others)
290
+ nested_files, nested_chars = _nested_rules(repo)
291
+ return RepoRow(
292
+ name=repo.name,
293
+ rules_chars=rules,
294
+ memory_index_chars=len(index),
295
+ memory_index_lines=len(index.splitlines()),
296
+ memory_files=len(others),
297
+ memory_chars=mem_chars,
298
+ nested_files=nested_files,
299
+ nested_chars=nested_chars,
300
+ project_skills=len(list(repo.glob(".claude/skills/*/SKILL.md"))),
301
+ has_mcp_json=(repo / ".mcp.json").is_file(),
302
+ )
303
+
304
+
305
+ def scan_user(home: Path) -> UserRow:
306
+ seen: set[Path] = set()
307
+ rules = sum(rules_chars(f, home, seen) for f in (home / ".claude" / "CLAUDE.md", home / "AGENTS.md"))
308
+ enabled = enabled_plugins(home)
309
+ return UserRow(
310
+ rules_chars=rules,
311
+ skills=skill_listing(home, enabled),
312
+ mcp=mcp_names(home, None),
313
+ enabled_known=enabled is not None,
314
+ )
315
+
316
+
317
+ # ── stamp ────────────────────────────────────────────────────────────────────
318
+
319
+ STAMP_NAME = ".last-preload-review"
320
+
321
+
322
+ @dataclass(frozen=True)
323
+ class Stamp:
324
+ date: dt.date
325
+ plugins: str
326
+
327
+
328
+ def plugins_hash(enabled: set[str] | None) -> str:
329
+ """sha256 hex of the sorted enabled plugin keys; the fixed text `unknown` when the set is unknown."""
330
+ if enabled is None:
331
+ return "unknown"
332
+ return hashlib.sha256("\n".join(sorted(enabled)).encode("utf-8")).hexdigest()
333
+
334
+
335
+ def _stamp_path(repo: Path) -> Path:
336
+ return repo / ".caddis" / STAMP_NAME
337
+
338
+
339
+ def read_stamp(repo: Path) -> Stamp | None:
340
+ """The stamp of `repo`, or None when the file is missing or malformed."""
341
+ text = _read_text(_stamp_path(repo))
342
+ if text is None:
343
+ return None
344
+ fields: dict[str, str] = {}
345
+ for line in text.splitlines():
346
+ key, sep, value = line.partition(":")
347
+ if sep:
348
+ fields[key.strip()] = value.strip()
349
+ try:
350
+ when = dt.date.fromisoformat(fields["date"])
351
+ except (KeyError, ValueError):
352
+ return None
353
+ plugins = fields.get("plugins", "")
354
+ return Stamp(when, plugins) if plugins else None
355
+
356
+
357
+ def write_stamp(repo: Path, enabled: set[str] | None, today: dt.date) -> None:
358
+ """Write `<repo>/.caddis/.last-preload-review`: two lines, the date and the plugin-set hash."""
359
+ path = _stamp_path(repo)
360
+ path.parent.mkdir(parents=True, exist_ok=True)
361
+ path.write_text(f"date: {today.isoformat()}\nplugins: {plugins_hash(enabled)}\n", encoding="utf-8", newline="\n")
362
+
363
+
364
+ # ── report ───────────────────────────────────────────────────────────────────
365
+
366
+ CONTEXT_NOTE = (
367
+ "Exact MCP tool lists, and skills that do not come from the plugin cache, need one /context run in a "
368
+ "session. Compare it with this table."
369
+ )
370
+
371
+
372
+ @dataclass(frozen=True)
373
+ class Limits:
374
+ repo_startup: int = 8000
375
+ rules_file: int = 6000
376
+ memory_tokens: int = 2000
377
+ memory_lines: int = 200
378
+ plugin_skills: int = 10
379
+
380
+
381
+ def startup_chars(row: RepoRow) -> int:
382
+ return row.rules_chars + row.memory_index_chars
383
+
384
+
385
+ def _sorted_rows(rows: list[RepoRow]) -> list[RepoRow]:
386
+ return sorted(rows, key=lambda r: (-startup_chars(r), r.name))
387
+
388
+
389
+ def cut_candidates(user: UserRow, rows: list[RepoRow], limits: Limits) -> list[str]:
390
+ """Advice lines. Each names one action; the command changes nothing."""
391
+ out: list[str] = []
392
+ if est_tokens(user.rules_chars) > limits.rules_file:
393
+ out.append(
394
+ f"User rules: about {est_tokens(user.rules_chars):,} tokens (limit {limits.rules_file:,}). "
395
+ "Run caddis:claude-md-curator on the user rules."
396
+ )
397
+ for s in user.skills:
398
+ if s.plugin != "caddis" and s.count > limits.plugin_skills:
399
+ action = (
400
+ "Move unused skills out of ~/.claude/skills."
401
+ if s.plugin == "user"
402
+ else "Turn the plugin off if you do not use it."
403
+ )
404
+ out.append(f"Plugin {s.plugin}: {s.count} skills (limit {limits.plugin_skills}). {action}")
405
+ for r in _sorted_rows(rows):
406
+ start = est_tokens(startup_chars(r))
407
+ if start > limits.repo_startup:
408
+ out.append(
409
+ f"{r.name}: start-up about {start:,} tokens (limit {limits.repo_startup:,}). "
410
+ "Run caddis:claude-md-curator on its rules file."
411
+ )
412
+ rules = est_tokens(r.rules_chars)
413
+ if rules > limits.rules_file:
414
+ out.append(
415
+ f"{r.name}: rules about {rules:,} tokens with imports (limit {limits.rules_file:,}). "
416
+ "Move how-to text into a doc that loads on demand."
417
+ )
418
+ index_tokens = est_tokens(r.memory_index_chars)
419
+ if index_tokens > limits.memory_tokens or r.memory_index_lines > limits.memory_lines:
420
+ out.append(
421
+ f"{r.name}: memory index about {index_tokens:,} tokens, {r.memory_index_lines} lines "
422
+ f"(limits {limits.memory_tokens:,} tokens, {limits.memory_lines} lines). Shorten the index lines."
423
+ )
424
+ return out
425
+
426
+
427
+ def _skills_chars(user: UserRow) -> int:
428
+ return sum(s.chars for s in user.skills)
429
+
430
+
431
+ def render_markdown(user: UserRow, rows: list[RepoRow], limits: Limits, root: Path) -> str:
432
+ skills_tokens = est_tokens(_skills_chars(user))
433
+ lines = [
434
+ "# Start-up size (estimates, chars ÷ 4)",
435
+ "",
436
+ f"Root: `{root}`",
437
+ "",
438
+ "## User level (same in every repo)",
439
+ "",
440
+ f"- Rules: about {est_tokens(user.rules_chars):,} tokens (estimate)",
441
+ f"- Skills (name + description): about {skills_tokens:,} tokens, {sum(s.count for s in user.skills)} skills (estimate)",
442
+ ]
443
+ if not user.enabled_known:
444
+ lines.append("- enabledPlugins unknown: counted every cached plugin")
445
+ lines.append(f"- MCP servers (names only): {', '.join(user.mcp) if user.mcp else 'none'}")
446
+ lines.append(f"- User-level total: about {est_tokens(user.rules_chars + _skills_chars(user)):,} tokens (estimate)")
447
+ if user.skills:
448
+ lines += ["", "| plugin | version | skills | tokens (estimate) |", "|---|---|---|---|"]
449
+ lines += [
450
+ f"| {s.plugin} | {s.version or '-'} | {s.count} | {est_tokens(s.chars):,} |"
451
+ for s in sorted(user.skills, key=lambda s: -s.chars)
452
+ ]
453
+ lines += [
454
+ "",
455
+ "## Repos (tokens are estimates)",
456
+ "",
457
+ "START = rules + memory index. Nested files load only when Claude works in that folder.",
458
+ "",
459
+ "| repo | rules | memory index | START | memory files | nested files | nested tokens |",
460
+ "|---|---|---|---|---|---|---|",
461
+ ]
462
+ lines += [
463
+ f"| {r.name} | {est_tokens(r.rules_chars):,} | {est_tokens(r.memory_index_chars):,} "
464
+ f"| {est_tokens(startup_chars(r)):,} | {r.memory_files} | {r.nested_files} | {est_tokens(r.nested_chars):,} |"
465
+ for r in _sorted_rows(rows)
466
+ ]
467
+ candidates = cut_candidates(user, rows, limits)
468
+ lines += ["", "## Cut candidates", ""]
469
+ lines += [f"- {c}" for c in candidates] if candidates else ["none over the limits"]
470
+ lines += ["", CONTEXT_NOTE, ""]
471
+ return "\n".join(lines)
472
+
473
+
474
+ def render_json(user: UserRow, rows: list[RepoRow], limits: Limits) -> str:
475
+ data = {
476
+ "estimate": True,
477
+ "user": {
478
+ "rules_chars": user.rules_chars,
479
+ "rules_tokens": est_tokens(user.rules_chars),
480
+ "skills": [{**asdict(s), "tokens": est_tokens(s.chars)} for s in user.skills],
481
+ "skills_tokens": est_tokens(_skills_chars(user)),
482
+ "mcp": user.mcp,
483
+ "enabled_known": user.enabled_known,
484
+ },
485
+ "repos": [
486
+ {
487
+ **asdict(r),
488
+ "rules_tokens": est_tokens(r.rules_chars),
489
+ "memory_index_tokens": est_tokens(r.memory_index_chars),
490
+ "startup_tokens": est_tokens(startup_chars(r)),
491
+ "nested_tokens": est_tokens(r.nested_chars),
492
+ }
493
+ for r in _sorted_rows(rows)
494
+ ],
495
+ "candidates": cut_candidates(user, rows, limits),
496
+ "limits": asdict(limits),
497
+ }
498
+ return json.dumps(data, indent=2, ensure_ascii=False)
499
+
500
+
501
+ # ── cli ──────────────────────────────────────────────────────────────────────
502
+
503
+
504
+ def today() -> dt.date:
505
+ return dt.datetime.now().astimezone().date()
506
+
507
+
508
+ def find_repo(start: Path) -> Path | None:
509
+ """The nearest folder at or above `start` that holds `.git` (a folder, or a file in a worktree)."""
510
+ for folder in (start, *start.parents):
511
+ if (folder / ".git").exists():
512
+ return folder
513
+ return None
514
+
515
+
516
+ def default_root(cwd: Path) -> Path:
517
+ """Parent of the git repo that holds `cwd`; `cwd` itself when it is not in a repo."""
518
+ repo = find_repo(cwd)
519
+ return repo.parent if repo else cwd
520
+
521
+
522
+ def main(argv: list[str] | None = None) -> int:
523
+ ap = argparse.ArgumentParser(description="Show what loads before the first prompt. Reads files only.")
524
+ ap.add_argument("--root", help="folder that holds the repos (default: parent of the current git repo)")
525
+ ap.add_argument("--home", help="home folder to read (default: the user home; tests use a fake one)")
526
+ ap.add_argument("--json", action="store_true", help="print JSON instead of Markdown")
527
+ ap.add_argument("--limit-repo-startup", type=int, default=Limits.repo_startup, metavar="N")
528
+ ap.add_argument("--limit-memory", type=int, default=Limits.memory_tokens, metavar="N")
529
+ ap.add_argument("--stamp", action="store_true", help="after the report, record the date and the plugin set")
530
+ args = ap.parse_args(argv)
531
+
532
+ cwd = Path.cwd()
533
+ home = Path(args.home).expanduser() if args.home else Path.home()
534
+ root = (Path(args.root).expanduser() if args.root else default_root(cwd)).resolve()
535
+ if not root.is_dir():
536
+ print(f"error: root is not a folder: {root}", file=sys.stderr)
537
+ return 2
538
+ limits = Limits(repo_startup=args.limit_repo_startup, memory_tokens=args.limit_memory)
539
+
540
+ user = scan_user(home)
541
+ rows = [scan_repo(home, d) for d in sorted(root.iterdir()) if d.is_dir() and not d.name.startswith(".")]
542
+ print(render_json(user, rows, limits) if args.json else render_markdown(user, rows, limits, root))
543
+
544
+ if args.stamp:
545
+ repo = find_repo(cwd)
546
+ if repo is None:
547
+ print("no git repo here: stamp not written", file=sys.stderr)
548
+ else:
549
+ write_stamp(repo, enabled_plugins(home), today())
550
+ return 0
551
+
552
+
553
+ if __name__ == "__main__":
554
+ sys.exit(main())
@@ -685,7 +685,7 @@ def launch_claude(prompt: str, worktree: Path, out: Path) -> str:
685
685
  # No `--allowedTools`: unscoped, it approves files outside the worktree (smoke run 18 Oct 2026: without it a
686
686
  # Read in the worktree ran, a Read of ~/.caddis/spend-cap.toml was refused).
687
687
  try:
688
- import caddis_spend # the recursion guard lives beside the spend cap (robustness #19)
688
+ import caddis_spend # the recursion guard lives beside the agy usage log (robustness #19)
689
689
  env_depth = caddis_spend.bump_headless_depth(os.environ)
690
690
  except ImportError:
691
691
  env_depth = None