genctx | npm package

genctx is a command-line interface designed to solve a critical problem in modern, AI-assisted software development: providing clean, relevant, and comprehensive context to Large Language Models (LLMs).

As development workflows become increasingly automated, AI agents and CI/CD pipelines need a reliable way to understand a project’s architecture and code. Pasting individual files is inefficient, and providing the entire repository includes irrelevant noise (build artifacts, dependencies, etc.) that degrades AI performance.

genctx bridges this gap by intelligently scanning your project based on a persistent configuration file. It generates a single, portable markdown file that contains:

1. A summary of the configuration used.
2. A clean, easy-to-read directory tree.
3. The complete contents of all relevant files, formatted in code blocks.

This approach ensures that any automated system—or developer—gets a high-signal, low-noise snapshot of the project, leading to better AI responses and more reliable automation.

Installation

npx genctx [options]

If you prefer to have the command available system-wide, you can install it globally via npm:

npm install -g genctx

Your First Context File

npx genctx -p nodejs

npx genctx

Configuration

The genctx.json file is the heart of the tool, ensuring reproducible context generation. All CLI flags that modify the configuration will update this file.

{
  "excludePaths": [
    ".DS_Store",
    ".git/",
    "node_modules"
  ],
  "includeExtensions": [
    ".js",
    ".json",
    ".md"
  ],
  "includePaths": [
    ".github/"
  ],
  "maxFileSizeKB": 500,
  "outputFile": "context.md",
  "useGitignore": true,
  "presets": [
    "nodejs"
  ]
}

Configuration Keys:

• excludePaths: An array of file names, directory names, or glob patterns to exclude.
• includeExtensions: An array of file extensions to include in the context.
• includePaths: An array of specific files or directories to forcefully include, even if they would normally be ignored (e.g., hidden directories like .github/).
• maxFileSizeKB: The maximum size (in kilobytes) for any single file to be included.
• outputFile: The name of the markdown file to be generated.
• useGitignore: A boolean (true or false) that determines whether to read your project’s .gitignore file.
• presets: An array of strings listing the presets that have been applied.

Presents

Presets are additive configurations that provide sensible defaults for common technologies by extending the excludePaths and includeExtensions lists.

You can apply a preset with the -p or --preset flag.

# Apply the Go and Python presets
npx genctx -p go python

Below is a list of all available presets and the settings they add.

Web & General

• nodejs: Excludes coverage/, .env. Includes .mjs, .cjs.
• python: Excludes __pycache__/, .venv/, venv/, *.pyc, .env, requirements.txt. Includes .py.

Mobile

• android: Excludes captures/, *.apk, *.aab, *.iml, gradle/, gradlew, gradlew.bat, local.properties. Includes .java, .kt, .kts, .xml, .gradle, .pro.
• swift: Excludes .swiftpm/, Packages/, DerivedData/, *.xcodeproj, *.xcworkspace. Includes .swift.

Backend & Systems

• java: Excludes target/, .mvn/, *.jar, *.war, logs/. Includes .java, .xml, .properties, .pom.
• go: Excludes *.exe, *.bin, go.sum. Includes .go.
• rust: Excludes target/, Cargo.lock. Includes .rs.
• ruby: Excludes tmp/, log/, Gemfile.lock. Includes .rb.
• php: Excludes composer.lock. Includes .php.
• dotnet: Excludes bin/, obj/, *.sln, *.csproj. Includes .cs.
• c_cpp: Excludes *.o, *.out, *.a, *.so, Makefile, CMakeLists.txt. Includes .c, .h, .cpp, .hpp.

Data Science

• r: Excludes .Rhistory, .RData. Includes .r, .R.

CLI References

All command-line flags are designed to modify the genctx.json configuration file.