ctxrun

ctxrun analyzes your codebase and generates a smart, LLM-optimized CONTEXT.md — with architecture diagnostics, health scoring, and pattern-aware file grouping.

Built for developers who use AI assistants (Claude, ChatGPT, Codex, Cursor) and want them to truly understand their project.

Why ctxrun

Most tools analyze code for humans — linters, coverage reports, dependency graphs.

ctxrun analyzes code for AI. It answers the question: "what does an LLM need to understand this project?"

• Filters noise so your context window isn't wasted on package-lock.json
• Groups repetitive files so 50 campaign components don't flood the context
• Scores architecture so the AI knows what to trust and what to flag
• Works with any stack — detected from manifests, not hardcoded rules

How it works

1. Scans your project files, ignoring noise (node_modules, vendor, build artifacts)
2. Extracts signals — file structure, languages, frameworks, coupling, type safety
3. Runs diagnostics — evaluates modularity, boundaries, test coverage, and more
4. Groups files by pattern — collapses repetitive files into representative samples
5. Outputs context — generates a human-readable CONTEXT.md and a structured CONTEXT.toon optimized for next-gen AI tools.

Installation

Use via npx (recommended):

npx ctxrun

or install globally:

npm install -g ctxrun

Usage

Run in any project directory:

npx ctxrun

Commands

| Command | Description | |---|---| | ctxrun | Generates CONTEXT.md and CONTEXT.toon for the current project | | ctxrun --summary | Lightweight mode — signatures only, no full file content | | ctxrun -c | Generates and copies context to clipboard | | ctxrun multi --dir <path> | Portfolio snapshot across multiple projects |

# Analyze all projects in a workspace
ctxrun multi --dir ~/projects

Output

Every run produces:

• Project Structure — full directory tree
• Health Score — 0 to 10, with confidence rating
• Architecture Diagnostics — strengths, risks, and opportunities
• Smart File Content — files grouped by pattern, capped by type
• TOON Export — A structured, compressed version of your context for TOON-compatible AI agents.

📂 FILES FOUND: 439
📦 FILES ANALYZED: 439
🔇 Noise filtered: 69 files removed from output
📄 FILES IN OUTPUT: 370
📊 Health Score: 9/10 (🟢 Healthy)
🔎 Confidence: 1
🧠 Summary: The system shows a very healthy architecture.
🗂  Pattern groups: 33 groups detected
   245 files collapsed into 33 representative samples
✅ Context written to CONTEXT.md
✅ TOON Context written to CONTEXT.toon

Using with AI assistants

Once CONTEXT.md is generated, drop it into any AI assistant:

# Claude / ChatGPT / Codex
> Here is my project context: [paste CONTEXT.md]
> Now help me refactor the authentication module.

# Cursor
Add CONTEXT.md to your context window before starting a session.

# TOON-compatible Agents
Provide the CONTEXT.toon file directly for structured, high-density context.

Configuration

Create a .ctxrunrc file in your project root:

{
  "include": ["custom-file.md"],
  "ignore": ["temp/**", "legacy/**"],
  "maxSizeKb": 300
}

| Option | Type | Default | Description | |---|---|---|---| | include | string[] | [] | Extra files to always include | | ignore | string[] | [] | Additional glob patterns to ignore | | maxSizeKb | number | 300 | Warning threshold for output size |

[!NOTE] By default, ctxrun already ignores: node_modules/, vendor/, dist/, *.lock, *.tsbuildinfo, and common build artifacts. Use .ctxrunrc only for additional customizations.

License

ISC © chachachavito