@x6txy/ctxscope 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 - 2026-06-21
+
+Published as `@x6txy/ctxscope` on npm. The installed binary is still `ctxscope`.
+
+### Added
+
+- Added `ctxscope scan [path]` CLI command.
+- Added agent filters for `all`, `codex`, `opencode`, `claude`, and `generic`.
+- Added context file discovery for common coding-agent instruction surfaces.
+- Added token estimates for discovered context files.
+- Added warning codes `CTX001` through `CTX006` for safe context hygiene checks.
+- Added human-readable terminal output with aligned columns and color support.
+- Added stable JSON output via `--json`.
+- Added README, MIT license, and npm package metadata.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x6txy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# ctxscope
+
+Inspect and lint coding-agent context files.
+
+`ctxscope` helps you see the instructions your coding agents may read before they start working: `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, OpenCode skills, Cursor rules, and GitHub Copilot instructions.
+
+It answers the first questions every agent-heavy repo eventually has:
+
+- What context files exist?
+- How much context do they add?
+- Which agent is each file probably for?
+- Which files are suspiciously large, empty, duplicated, or stale?
+
+## Install
+
+Run without installing:
+
+```bash
+npx @x6txy/ctxscope scan
+```
+
+Or install globally:
+
+```bash
+npm install -g @x6txy/ctxscope
+ctxscope scan
+```
+
+## Usage
+
+```bash
+ctxscope --help
+ctxscope --version
+ctxscope scan [path]
+ctxscope scan --agent <all|codex|opencode|claude|generic>
+ctxscope scan --json
+```
+
+Examples:
+
+```bash
+ctxscope scan
+ctxscope scan apps/web
+ctxscope scan --agent codex
+ctxscope scan --agent opencode --json
+```
+
+## Output
+
+```text
+ctxscope scan
+
+Agent   all
+Target  /repo
+
+Files (3)
+Path                               Tokens  Agents
+.opencode/skills/backend/SKILL.md      ~6  opencode, generic
+AGENTS.md                             ~13  codex, opencode, claude, generic
+src/AGENTS.md                          ~3  codex, opencode, claude, generic
+
+Summary
+  3 files, ~22 tokens, 4 warnings
+
+Warnings (4)
+WARN CTX002  AGENTS.md
+  heading "testing" appears in 2 context files
+```
+
+## Supported Agents
+
+v0.1 uses pattern-based discovery. It does not claim perfect runtime tracing for every agent.
+
+| Agent | Files detected |
+| --- | --- |
+| Codex | `AGENTS.md`, `**/AGENTS.md` |
+| OpenCode | `AGENTS.md`, `**/AGENTS.md`, `.opencode/**/*.md`, `.opencode/skills/**/SKILL.md` |
+| Claude Code | `CLAUDE.md`, `**/CLAUDE.md`, `AGENTS.md` |
+| Generic | `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `**/SKILL.md`, `.cursor/rules/**`, `.github/copilot-instructions.md` |
+
+Ignored directories:
+
+- `.git`
+- `node_modules`
+- `dist`
+
+## Warning Codes
+
+`ctxscope scan` reports objective hygiene warnings only.
+
+| Code | Meaning |
+| --- | --- |
+| `CTX001` | Oversized context file |
+| `CTX002` | Duplicate heading across context files |
+| `CTX003` | Stale relative markdown link |
+| `CTX004` | Empty context file |
+| `CTX005` | TODO, FIXME, or obsolete marker |
+| `CTX006` | Repeated paragraph |
+
+## JSON Output
+
+Use `--json` for automation:
+
+```bash
+ctxscope scan --json
+```
+
+Shape:
+
+```json
+{
+  "agent": "all",
+  "target": ".",
+  "files": [],
+  "totalTokens": 0,
+  "warnings": []
+}
+```
+
+## Limitations
+
+- Token counts are estimates: `ceil(character_count / 4)`.
+- v0.1 is discovery-based, not real session tracing.
+- Semantic conflicts are not detected yet. For example, `npm` vs `pnpm` policy conflicts are planned for a future `doctor` command.
+- `diff` and `trace` are future commands.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,491 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync3 } from "fs";
+
+// src/output.ts
+var colorEnabled = process.env.NO_COLOR === void 0 && (process.stdout.isTTY || process.env.FORCE_COLOR !== void 0);
+var colors = {
+  bold: (value) => color("\x1B[1m", value),
+  cyan: (value) => color("\x1B[36m", value),
+  dim: (value) => color("\x1B[2m", value),
+  green: (value) => color("\x1B[32m", value),
+  yellow: (value) => color("\x1B[33m", value)
+};
+function formatHumanScanResult(result) {
+  const sections = [
+    colors.bold(colors.cyan("ctxscope scan")),
+    formatMeta(result),
+    formatFiles(result),
+    formatSummary(result),
+    formatWarnings(result)
+  ];
+  return sections.filter(Boolean).join("\n\n");
+}
+function formatJsonScanResult(result) {
+  return JSON.stringify({
+    agent: result.agent,
+    target: result.target,
+    files: result.files,
+    totalTokens: result.totalTokens,
+    warnings: result.warnings
+  }, null, 2);
+}
+function formatWarning(warning) {
+  return `${colors.yellow(warning.severity.toUpperCase())} ${colors.yellow(warning.code)}  ${warning.path}
+  ${colors.dim(warning.message)}`;
+}
+function formatMeta(result) {
+  return [
+    `${colors.dim("Agent")}   ${result.agent}`,
+    `${colors.dim("Target")}  ${result.target}`
+  ].join("\n");
+}
+function formatFiles(result) {
+  if (result.files.length === 0) {
+    return `${colors.bold("Files")} ${colors.dim("(0)")}
+  No context files found.`;
+  }
+  const pathWidth = Math.max("Path".length, ...result.files.map((file) => file.path.length));
+  const tokenWidth = Math.max("Tokens".length, ...result.files.map((file) => formatTokenCell(file.tokens, file.skippedBinary).length));
+  const header = [
+    colors.dim("Path".padEnd(pathWidth)),
+    colors.dim("Tokens".padStart(tokenWidth)),
+    colors.dim("Agents")
+  ].join("  ");
+  const rows = result.files.map((file) => [
+    file.path.padEnd(pathWidth),
+    formatTokenCell(file.tokens, file.skippedBinary).padStart(tokenWidth),
+    file.agents.join(", ")
+  ].join("  "));
+  return `${colors.bold("Files")} ${colors.dim(`(${result.files.length})`)}
+${header}
+${rows.join("\n")}`;
+}
+function formatSummary(result) {
+  const warningLabel = result.warnings.length === 0 ? colors.green("0 warnings") : colors.yellow(`${result.warnings.length} warnings`);
+  return `${colors.bold("Summary")}
+  ${formatNumber(result.files.length)} files, ~${formatNumber(result.totalTokens)} tokens, ${warningLabel}`;
+}
+function formatWarnings(result) {
+  if (result.warnings.length === 0) {
+    return "";
+  }
+  return `${colors.bold("Warnings")} ${colors.dim(`(${result.warnings.length})`)}
+${result.warnings.map(formatWarning).join("\n")}`;
+}
+function formatTokenCell(tokens, skippedBinary) {
+  return skippedBinary ? "binary" : `~${formatNumber(tokens)}`;
+}
+function formatNumber(value) {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function color(code, value) {
+  return colorEnabled ? `${code}${value}\x1B[0m` : value;
+}
+
+// src/scan.ts
+import { statSync as statSync2 } from "fs";
+import { dirname as dirname2, relative as relative2, resolve as resolve3 } from "path";
+
+// src/agents.ts
+var AGENT_ORDER = ["codex", "opencode", "claude", "generic"];
+function agentsForPath(relativePath) {
+  const normalized = normalizePath(relativePath);
+  const fileName = basename(normalized);
+  const agents = /* @__PURE__ */ new Set();
+  if (normalized.startsWith(".opencode/")) {
+    agents.add("opencode");
+    if (fileName === "SKILL.md") {
+      agents.add("generic");
+    }
+    return AGENT_ORDER.filter((agent) => agents.has(agent));
+  }
+  if (fileName === "AGENTS.md") {
+    agents.add("codex");
+    agents.add("opencode");
+    agents.add("claude");
+    agents.add("generic");
+  }
+  if (fileName === "CLAUDE.md") {
+    agents.add("claude");
+    agents.add("generic");
+  }
+  if (fileName === "SKILL.md") {
+    agents.add("generic");
+    if (normalized.startsWith(".opencode/skills/")) {
+      agents.add("opencode");
+    }
+  }
+  if (normalized.startsWith(".cursor/rules/")) {
+    agents.add("generic");
+  }
+  if (normalized === ".github/copilot-instructions.md") {
+    agents.add("generic");
+  }
+  return AGENT_ORDER.filter((agent) => agents.has(agent));
+}
+function matchesAgentFilter(agents, filter) {
+  return filter === "all" || agents.includes(filter);
+}
+function normalizePath(path) {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function basename(path) {
+  const parts = path.split("/");
+  return parts[parts.length - 1] ?? path;
+}
+
+// src/files.ts
+import { readdirSync, statSync } from "fs";
+import { relative, resolve } from "path";
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([".git", "dist", "node_modules"]);
+function listFiles(targetPath) {
+  const absoluteTarget = resolve(targetPath);
+  const stat = statSync(absoluteTarget);
+  if (stat.isFile()) {
+    return [absoluteTarget];
+  }
+  if (!stat.isDirectory()) {
+    return [];
+  }
+  const files = [];
+  walk(absoluteTarget, files);
+  return files.sort((a, b) => relative(process.cwd(), a).localeCompare(relative(process.cwd(), b)));
+}
+function walk(directory, files) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = resolve(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRECTORIES.has(entry.name)) {
+        walk(absolutePath, files);
+      }
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+}
+
+// src/token.ts
+import { readFileSync } from "fs";
+function estimateFileTokens(path) {
+  const buffer = readFileSync(path);
+  if (looksBinary(buffer)) {
+    return { tokens: 0, skipped: true };
+  }
+  const content = buffer.toString("utf8");
+  return {
+    tokens: estimateTextTokens(content),
+    skipped: false
+  };
+}
+function estimateTextTokens(content) {
+  return Math.ceil(content.length / 4);
+}
+function looksBinary(buffer) {
+  if (buffer.includes(0)) {
+    return true;
+  }
+  const sampleSize = Math.min(buffer.length, 1024);
+  if (sampleSize === 0) {
+    return false;
+  }
+  let suspiciousBytes = 0;
+  for (let index = 0; index < sampleSize; index += 1) {
+    const byte = buffer[index];
+    const isCommonTextByte = byte === 9 || byte === 10 || byte === 13 || byte >= 32 && byte <= 126 || byte >= 128;
+    if (!isCommonTextByte) {
+      suspiciousBytes += 1;
+    }
+  }
+  return suspiciousBytes / sampleSize > 0.3;
+}
+
+// src/warnings.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { dirname, resolve as resolve2 } from "path";
+var OVERSIZED_TOKEN_LIMIT = 2500;
+var MARKER_PATTERN = /\b(TODO|FIXME|OBSOLETE)\b/i;
+var MARKDOWN_LINK_PATTERN = /(?<!!)\[[^\]\n]+\]\(([^)]+)\)/g;
+function collectWarnings(files) {
+  const warnings = [];
+  const headings = /* @__PURE__ */ new Map();
+  for (const input of files) {
+    warnings.push(...collectFileWarnings(input));
+    collectHeadings(input, headings);
+  }
+  warnings.push(...collectDuplicateHeadingWarnings(headings));
+  return warnings.sort((a, b) => {
+    const pathComparison = a.path.localeCompare(b.path);
+    return pathComparison === 0 ? a.code.localeCompare(b.code) : pathComparison;
+  });
+}
+function collectFileWarnings(input) {
+  const warnings = [];
+  const { file } = input;
+  if (file.skippedBinary) {
+    return warnings;
+  }
+  const content = readFileSync2(input.absolutePath, "utf8");
+  if (file.tokens > OVERSIZED_TOKEN_LIMIT) {
+    warnings.push({
+      code: "CTX001",
+      severity: "warn",
+      path: file.path,
+      message: `larger than ${OVERSIZED_TOKEN_LIMIT} estimated tokens`
+    });
+  }
+  if (content.trim().length === 0) {
+    warnings.push({
+      code: "CTX004",
+      severity: "warn",
+      path: file.path,
+      message: "empty context file"
+    });
+  }
+  if (MARKER_PATTERN.test(content)) {
+    warnings.push({
+      code: "CTX005",
+      severity: "warn",
+      path: file.path,
+      message: "contains TODO, FIXME, or obsolete markers"
+    });
+  }
+  warnings.push(...collectStaleLinkWarnings(input.absolutePath, file.path, content));
+  warnings.push(...collectRepeatedParagraphWarnings(file.path, content));
+  return warnings;
+}
+function collectHeadings(input, headings) {
+  var _a;
+  if (input.file.skippedBinary) {
+    return;
+  }
+  const content = readFileSync2(input.absolutePath, "utf8");
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const heading = (_a = match[2]) == null ? void 0 : _a.trim().toLowerCase();
+    if (!heading) {
+      continue;
+    }
+    const paths = headings.get(heading) ?? [];
+    paths.push(input.file.path);
+    headings.set(heading, paths);
+  }
+}
+function collectDuplicateHeadingWarnings(headings) {
+  const warnings = [];
+  for (const [heading, paths] of headings.entries()) {
+    const uniquePaths = [...new Set(paths)];
+    if (uniquePaths.length < 2) {
+      continue;
+    }
+    for (const path of uniquePaths) {
+      warnings.push({
+        code: "CTX002",
+        severity: "warn",
+        path,
+        message: `heading "${heading}" appears in ${uniquePaths.length} context files`
+      });
+    }
+  }
+  return warnings;
+}
+function collectStaleLinkWarnings(absolutePath, displayPath, content) {
+  var _a, _b;
+  const warnings = [];
+  const directory = dirname(absolutePath);
+  for (const match of content.matchAll(MARKDOWN_LINK_PATTERN)) {
+    const href = (_a = match[1]) == null ? void 0 : _a.trim();
+    if (!href || shouldSkipLink(href)) {
+      continue;
+    }
+    const pathOnly = ((_b = href.split("#")[0]) == null ? void 0 : _b.split("?")[0]) ?? "";
+    if (!pathOnly || !existsSync(resolve2(directory, pathOnly))) {
+      warnings.push({
+        code: "CTX003",
+        severity: "warn",
+        path: displayPath,
+        message: `links to missing file: ${href}`
+      });
+    }
+  }
+  return warnings;
+}
+function collectRepeatedParagraphWarnings(displayPath, content) {
+  const paragraphs = content.split(/\n\s*\n/).map((paragraph) => paragraph.trim().replace(/\s+/g, " ")).filter((paragraph) => paragraph.length >= 40);
+  const seen = /* @__PURE__ */ new Set();
+  for (const paragraph of paragraphs) {
+    if (seen.has(paragraph)) {
+      return [{
+        code: "CTX006",
+        severity: "warn",
+        path: displayPath,
+        message: "contains a repeated paragraph"
+      }];
+    }
+    seen.add(paragraph);
+  }
+  return [];
+}
+function shouldSkipLink(href) {
+  return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("#");
+}
+
+// src/scan.ts
+function scanContext(target, agent) {
+  const root = getScanRoot(target);
+  const absoluteFiles = listFiles(target);
+  const discoveredFiles = absoluteFiles.map((absolutePath) => {
+    const path = normalizeRelativePath(relative2(root, absolutePath));
+    const agents = agentsForPath(path);
+    if (agents.length === 0 || !matchesAgentFilter(agents, agent)) {
+      return null;
+    }
+    const estimate = estimateFileTokens(absolutePath);
+    return {
+      path,
+      agents,
+      tokens: estimate.tokens,
+      skippedBinary: estimate.skipped
+    };
+  }).filter((file) => file !== null).sort((a, b) => a.path.localeCompare(b.path));
+  const absoluteByPath = new Map(absoluteFiles.map((absolutePath) => [
+    normalizeRelativePath(relative2(root, absolutePath)),
+    absolutePath
+  ]));
+  const warningInputs = discoveredFiles.map((file) => ({ file, absolutePath: absoluteByPath.get(file.path) })).filter((input) => input.absolutePath !== void 0);
+  return {
+    agent,
+    target,
+    files: discoveredFiles,
+    totalTokens: discoveredFiles.reduce((total, file) => total + file.tokens, 0),
+    warnings: collectWarnings(warningInputs)
+  };
+}
+function getScanRoot(target) {
+  const absoluteTarget = resolve3(target);
+  const stat = statSync2(absoluteTarget);
+  return stat.isDirectory() ? absoluteTarget : dirname2(absoluteTarget);
+}
+function normalizeRelativePath(path) {
+  const normalized = path.replaceAll("\\", "/");
+  return normalized === "" ? "." : normalized;
+}
+
+// src/types.ts
+var SUPPORTED_AGENTS = ["all", "codex", "opencode", "claude", "generic"];
+
+// src/cli.ts
+function getVersion() {
+  try {
+    const packageJson = JSON.parse(
+      readFileSync3(new URL("../package.json", import.meta.url), "utf8")
+    );
+    return packageJson.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function printHelp() {
+  console.log(`ctxscope ${getVersion()}
+
+Inspect and lint coding-agent context files.
+
+Usage:
+  ctxscope --help
+  ctxscope --version
+  ctxscope scan [path] [--agent <agent>] [--json]
+
+Commands:
+  scan                 Discover coding-agent context files for a path.
+
+Options:
+  --agent <agent>      Agent profile: all, codex, opencode, claude, generic.
+                       Default: all.
+  --json               Print machine-readable JSON.
+  -h, --help           Show this help message.
+  -v, --version        Show the package version.
+`);
+}
+function fail(message) {
+  console.error(`ctxscope: ${message}`);
+  console.error("Run `ctxscope --help` for usage.");
+  process.exit(1);
+}
+function parseAgent(value) {
+  if (!value) {
+    fail("missing value for --agent");
+  }
+  if (!SUPPORTED_AGENTS.includes(value)) {
+    fail(`unsupported agent '${value}'. Expected one of: ${SUPPORTED_AGENTS.join(", ")}`);
+  }
+  return value;
+}
+function parseScanOptions(args) {
+  const options = {
+    agent: "all",
+    json: false,
+    target: "."
+  };
+  let targetSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--agent") {
+      options.agent = parseAgent(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--agent=")) {
+      options.agent = parseAgent(arg.slice("--agent=".length));
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      fail(`unknown option '${arg}'`);
+    }
+    if (targetSet) {
+      fail(`unexpected extra path '${arg}'`);
+    }
+    options.target = arg;
+    targetSet = true;
+  }
+  return options;
+}
+function runScan(options) {
+  const result = scanContext(options.target, options.agent);
+  if (options.json) {
+    console.log(formatJsonScanResult(result));
+    return;
+  }
+  console.log(formatHumanScanResult(result));
+}
+function main(argv) {
+  const [command, ...args] = argv;
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(getVersion());
+    return;
+  }
+  if (command === "scan") {
+    runScan(parseScanOptions(args));
+    return;
+  }
+  fail(`unknown command '${command}'`);
+}
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@x6txy/ctxscope",
+  "version": "0.1.0",
+  "description": "Inspect and lint coding-agent context files",
+  "type": "module",
+  "keywords": [
+    "agents",
+    "ai",
+    "codex",
+    "claude",
+    "opencode",
+    "cli",
+    "context",
+    "lint"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x6txy/ctxscope.git"
+  },
+  "bugs": {
+    "url": "https://github.com/x6txy/ctxscope/issues"
+  },
+  "homepage": "https://github.com/x6txy/ctxscope#readme",
+  "bin": {
+    "ctxscope": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "prepack": "pnpm build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}