convez.ai
AgenteDesenvolvimento WebIntermediário
mixkrass

Agent Context Compressor

mixkrass/agent-context-compressor

Mapa estrutural comprimido de codebase para agentes de IA com até 90% menos tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Compressor AST de codebase TypeScript/JavaScript que gera um mapa estrutural otimizado para agentes de IA. Remove corpos de funções e inicializadores enquanto preserva assinaturas, tipos e JSDoc, economizando até 90% de tokens de contexto.

Instalação

$npx convez-ai mixkrass/agent-context-compressor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Alimentar agentes de IA (Claude, GPT-4, Gemini) com estrutura completa do projeto economizando tokens
  • Gerar dependency graphs em Mermaid para visualizar arquitetura
  • Criar summaries de codebase para documentação e onboarding

Veredito

Ferramenta prática e bem executada para o problema real de context window em agentes de IA. Implementação limpa em Node.js puro, sem dependências externas pesadas, com suporte a múltiplos formatos de saída. Utilidade imediata para quem trabalha com Claude Code ou GPT em projetos grandes.

README

A tradução para o português deste README ainda está na fila.

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

OptionAliasDescriptionDefault
-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-jsdocExclude JSDoc and other comments from output.false
--exports-onlyInclude only exported declarations and strip private/protected class members.false
--max-depth <depth>Maximum folder depth to scan.Infinity
--no-gitignoreDo not respect .gitignore rules.false
--dep-treeBuild a visual dependency graph (Mermaid for MD, arrows for text).false
--relative-linksGenerate 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

Ver o original no GitHub

Bom para

Relacionados