genctx (Generate Context)

The AI Context Generator for Modern Developers.

genctx consolidates your entire codebase into a single, high-signal Markdown file optimized for Large Language Models (LLMs). It intelligently formats your project structure and source code, stripping noise to ensure AI models (like ChatGPT, Claude, Gemini) get the most relevant context with the fewest tokens.

🌟 Why genctx?

• Token Efficiency: Save money and context window space. genctx can automatically strip comments and empty lines.
• Project Structure: Provides a clear directory tree so the AI understands file relationships.
• Smart Filtering: Respects .gitignore and automatically excludes build artifacts (node_modules, dist, etc.).
• Zero Config Start: Just run it. It works out of the box for most projects.
• Detailed Control: Fully configurable via genctx.config.json for advanced users.

🚀 Quick Start

Run instantly in any project folder using npx:

npx genctx

This generates genctx.context.md in your current directory. Drag and drop this file into your AI chat window.

Installing Globally (Optional)

If you use it frequently, install it globally:

npm install -g genctx
genctx

🛠️ Usage & Examples

Basic Run

Generate context for the current directory, respecting .gitignore and default excludes.

npx genctx

Process a Single File

Generate context for just one file (useful for targeted debugging).

npx genctx --include src/main.js

Optimize for Tokens

Strip all comments and empty lines to fit a large codebase into a small context window.

npx genctx --remove-comments --remove-empty-lines

Focus on Specific Folders

Only include the src and config directories.

npx genctx --include src config

Use a Tech Stack Preset

Apply standard exclude patterns for a specific language ecosystem (e.g., ignoring .env, coverage, __pycache__).

npx genctx --preset nodejs
npx genctx --preset python

Programmatic API (Node.js)

You can use genctx inside your own build scripts or tools.

const { generate } = require('genctx');

await generate({
  include: ['src/**/*.ts'],
  exclude: ['**/*.test.ts'],
  outputFile: 'docs/context.md',
  options: {
    removeComments: true,
    removeEmptyLines: true
  }
});

Need to clean raw code strings?
genctx is designed for files and directories. If you need to strip comments from raw strings or code blocks, check out clean-context.

⚙️ Configuration

While CLI flags are great for quick runs, you can persist your settings in a configuration file.

Initialize a config file:

npx genctx --init

This creates genctx.config.json:

{
  "include": ["**/*"],
  "exclude": [
    "node_modules", ".git", ".env", "dist", "build"
  ],
  "outputFile": "genctx.context.md",
  "options": {
    "removeComments": false,
    "removeEmptyLines": false,
    "maxFileSizeKB": 2048,
    "useGitignore": true
  }
}

CLI Options

| Option | Alias | Description | | :--- | :--- | :--- | | --version | -v | Show current version. | | --help | -h | Show usage information. | | --output | -o | Output filename. | | --include | -i | Add include glob patterns. | | --remove-comments | | Strip code comments to save tokens. | | --remove-empty-lines | | Remove empty vertical whitespace. |

🛡️ Smart Binary Detection

genctx doesn't just rely on file extensions. It performs content inspection (reading the first 512 bytes) to detect binary files. This prevents accidental inclusion of compiled binaries, obscure media formats, or corrupted files that could break your LLM context window.

💡 Advanced: Whitelist Strategy

The include option works as a strict whitelist. This allows you to cherry-pick specific files even if they might otherwise be ignored by a broad rule (as long as they are not explicitly in exclude).

Scenario: You want to verify a single binary file but ignore the rest of the bin/ folder.

{
  "include": [
    "src/**/*",
    "bin/genctx"
  ],
  "exclude": ["node_modules"]
}

🔒 Privacy by Default

genctx automatically excludes sensitive and high-noise files to ensure your context is clean and secure.

• Security: *.pem, *.key, *.cert, *.pfx, id_rsa are hard-excluded.
• Binaries: Images, Videos, Archives, PDFs, and Executables are ignored.
• System: .DS_Store, .git, Logs, and Lockfiles are skipped.
• Overrides: You can force-include any of these by explicitly adding them to include (e.g., include: ["src/logo.png"]).

📦 Presets

Presets apply additive exclusion rules and default extensions for specific technologies.

| Preset | Adds Exclusions | Adds Extensions | |---|---|---| | nodejs | coverage, .env, npm-debug.log | .mjs, .cjs | | python | __pycache__, .venv, venv, *.pyc, requirements.txt | .py | | java | target, .mvn, *.jar, *.war | .java, .xml | | android | gradle, *.apk, *.aab | .kt, .kts, .gradle | | go | *.exe, *.bin, go.sum | .go | | rust | target, Cargo.lock | .rs | | dotnet | bin, obj, *.sln | .cs | | ...and more | Includes swift, ruby, php, c_cpp, r | |

Use multiple presets if your project is full-stack:

npx genctx --preset nodejs --preset python

🤝 Contributing

We welcome contributions! Whether it's adding a new preset, fixing a bug, or improving documentation.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

{ github.com/mgks }