agent-context-compressor

A lightweight and extremely fast TypeScript/JavaScript codebase AST compressor. It scans your files, strips function bodies, constructor bodies, and non-literal variable initializers, and exports a token-efficient codebase map complete with signatures, interface definitions, and JSDoc comments.

Designed specifically to fit an entire codebase's structural map into the context window of AI coding agents (such as Claude Code, GPT-4, Gemini) at a fraction of the token cost.

Why Use This? (AI Coding Agent Benefits)

AI coding agents are highly capable, but feeding them entire source files consumes massive context windows, slows down reasoning, and quickly inflates API costs.

agent-context-compressor solves this by generating a high-density, structural skeleton of your project. Here is why it is extremely useful:

• 📉 Massive Token Savings: Instead of uploading thousands of lines of implementation logic, it outputs only class interfaces and function signatures. This compresses large codebases up to 90%, freeing up the context window for actual reasoning.
• ⚡ Instant API Discovery: The agent instantly sees all methods, properties, types, and dependencies of key modules without having to search or read long files.
• 🔗 Interactive Navigation: Every file section in the Markdown output starts with a clickable file link. This allows coding agents to immediately locate and navigate to the file they need to modify.
• 💡 Preserved Business Logic (JSDoc & Types): Retaining TypeScript types and JSDoc comments ensures the agent understands the business rules, parameters, and intent of the code without getting bogged down by execution details.

Features

• ⚡ Pure Node.js & TypeScript: No native binary modules or Rust/C++ compilation required (unlike Rust/tree-sitter outline tools). Runs instantly with npx.
• 📁 Declaration Mapping: Outputs syntactically valid TypeScript/JavaScript signatures (like .d.ts files) that retain full JSDoc and parameter types, stripping private and protected members in --exports-only mode.
• 🌳 Dependency Graph: Generates a visual mapping of module imports (rendered as a Mermaid flowchart in Markdown and text arrow trees in plain text) to help the agent instantly understand codebase layers.
• 🔗 Relative Links: Generates relative links (e.g. [src/file.ts](./src/file.ts)) instead of absolute pathways, perfect for rendering on GitHub/GitLab.
• 🔍 Gitignore Respect: Natively respects .gitignore rules and excludes heavy directories (e.g. node_modules, dist, coverage) by default.
• 🎨 Multiple Output Formats: Supports Markdown (ideal for LLM readability with syntax highlighted blocks), Plain Text, and JSON representation.
• ⚙ Granular Token Control: Save more tokens using --no-jsdoc, --exports-only, and --max-depth.
• 🛠 CLI & Programmatic API: Use it as a global terminal utility or integrate it directly into your own AI agent pipeline.

Example Output

You can see a live example of the compressed codebase map generated by this tool on its own repository: 👉 summary-self.md (features the visual Mermaid dependency graph and the compressed signatures of all source modules).

Installation

Run without installation (recommended)

npx agent-context-compressor -d . -o codebase-summary.md

Install globally

npm install -g agent-context-compressor

This registers both the primary command agent-context-compressor and its shorter alias fs-summary.

CLI Usage

By default, running the tool creates a codebase-summary.md in your target directory. You can use either the full command agent-context-compressor or the shorthand fs-summary:

# Scan current directory and save Markdown output
agent-context-compressor

# Generate summary with visual dependency tree and relative links
agent-context-compressor --dep-tree --relative-links

# Scan a specific directory
agent-context-compressor --dir ./src

# Exclude JSDocs and include only exported declarations (public API) to save tokens
agent-context-compressor --no-jsdoc --exports-only

# Save as plain text or JSON
agent-context-compressor --format text -o codebase-map.txt
agent-context-compressor --format json -o codebase-map.json

# Output directly to stdout (useful for piping into other tools)
agent-context-compressor -o -

CLI Options

| Option | Alias | Description | Default | | :--- | :--- | :--- | :--- | | -d, --dir <path> | | Directory to scan. | . | | -o, --output <path> | | Output file path (use - for stdout). | codebase-summary.md | | -f, --format <format>| | Output format: markdown, text, json. | markdown | | -e, --exclude <globs...>|| Additional glob patterns to exclude. | [] | | -i, --include <globs...>|| Specific glob patterns to include. | **/*.{ts,js,tsx,jsx,...}| | --no-jsdoc | | Exclude JSDoc and other comments from output. | false | | --exports-only | | Include only exported declarations and strip private/protected class members. | false | | --max-depth <depth> | | Maximum folder depth to scan. | Infinity | | --no-gitignore | | Do not respect .gitignore rules. | false | | --dep-tree | | Build a visual dependency graph (Mermaid for MD, arrows for text). | false | | --relative-links | | Generate relative markdown links instead of absolute file:/// URLs. | false |

Programmatic API

You can import and use the library programmatically in your projects:

import { compressContext, formatSummary } from 'agent-context-compressor';

async function main() {
  // 1. Generate the codebase summary metadata
  const summary = await compressContext({
    dir: './src',
    exportsOnly: true,
    noJsdoc: false
  });

  // 2. Format the metadata into Markdown, Text, or JSON
  const markdownContent = formatSummary(summary, 'markdown');
  
  console.log(markdownContent);
}

main();

Types

export interface CompressorOptions {
  dir?: string;
  output?: string;
  format?: 'markdown' | 'text' | 'json';
  exclude?: string[];
  include?: string[];
  noJsdoc?: boolean;
  exportsOnly?: boolean;
  maxDepth?: number;
  noGitignore?: boolean;
}

export interface FileSummary {
  filePath: string;
  language: string;
  content: string;
}

export interface CodebaseSummary {
  files: FileSummary[];
  generatedAt: string;
  scanDir: string;
}

License

MIT