Ai-txt NPM | npm.io

@slpixe/ai-md (JSR) | ai-txt (NPM)

npm

A CLI tool to aggregate your codebase into a single Markdown file for easier review with AI models.

Available on:

JSR: jsr.io/@slpixe/ai-md
NPM: npmjs.com/package/ai-txt

Overview

ai-md scans your project directory, applies default and custom ignore patterns, and merges files into a formatted Markdown output. It handles text, binary, and SVG files appropriately.

Features

Recursively aggregates files from folders.
Supports default and custom ignore patterns.
Removes extra whitespace by default (except for whitespace-dependent languages). Use the -w, --keep-whitespace flag to preserve original whitespace.
Includes notes for binary and SVG files.
Concurrency support for faster processing.

Usage

You can run the CLI tool using these methods:

Using JSR (recommended):

# Using npx with JSR
npx jsr run @slpixe/ai-md

# Using JSR CLI directly
jsr run @slpixe/ai-md

Using npm:

# Run directly with NPM
npx ai-txt

# Install globally
npm install -g ai-txt
ai-md  # Command name remains ai-md for consistency

This generates a codebase.md file containing your aggregated codebase.

Options

-i, --input <paths...>: Input file(s) or directory(ies) (default: current directory)
-o, --output <file>: Output Markdown file (default: codebase.md)
--no-default-ignores: Disable default ignore patterns
-w, --keep-whitespace: Preserve original whitespace. By default, extra whitespace is removed (except in whitespace-sensitive files).
--show-output-files: Display names of included files
--ignore-file <file>: Specify a custom ignore file (default: .aidigestignore)
--ignore <pattern>: Add ignore patterns via command line (can be used multiple times)
--concurrent: Enable concurrency for file processing
--dry-run: Perform a dry run without writing the output file
--help: Show this help message

Examples

Basic usage:

# Using NPM package
npx ai-txt

# Using JSR package
npx jsr run @slpixe/ai-md

With specific options and custom inputs:

npx ai-md --show-output-files -i /src/Components -i README.md

Using CLI ignore patterns:

# Ignore specific files and patterns
npx ai-md --ignore "a.ts" --ignore "*.css" --ignore "./folder-b"

# Combine with other ignore methods
npx ai-md --ignore "*.test.ts" --ignore-file custom.ignore --no-default-ignores

Ignore Patterns

You can specify patterns to exclude files and directories in multiple ways:

Default Ignores: Built-in patterns for common files to exclude (enabled by default, can be disabled with --no-default-ignores).
Custom Ignore File: Place a .aidigestignore file in your project root (or specify with --ignore-file). The syntax works similarly to .gitignore.
CLI Ignore Patterns: Use the --ignore option one or more times to specify patterns directly in the command. Supports file names, directory paths, and glob patterns:
```
npx ai-md --ignore "*.test.ts" --ignore "./dist" --ignore "config.json"
```

Whitespace Removal

By default, ai-md removes extra whitespace from files to reduce token counts for AI models. Files written in whitespace-sensitive languages (e.g., Python, YAML) are exempt from this process. If you prefer to keep the original formatting and whitespace, use the -w or --keep-whitespace flag when running the command.

Binary and SVG File Handling

Binary files and SVG images are included with a short note about their file type rather than full content, ensuring that file structure is maintained without unnecessary bulk.

Development

To run locally with full CLI options, use:
```
npm run start
```
If built (after npm run build), you can run:
```
npx ai-md
```

For local testing with a specific build directory and custom inputs, run:

npx --prefix ~/{ai-md-directory} ai-md --keep-whitespace --show-output-files -i /src/Components -i README.md

If you encounter permission issues, you might need to set execution permissions:
```
chmod +x dist/index.js
```
For testing, execute:
```
npm test
```
To build the project before publishing:
```
npm run build
```

Package Updates

For manual dependency updates:

# Check available updates
npx npm-check-updates

# Interactive mode (recommended)
npx npm-check-updates -i

# Update all dependencies
npx npm-check-updates -u && npm install

Alternatively, enable Renovate in your repository for automated dependency updates: 1. Install Renovate App from GitHub Marketplace 2. Add to your repository 3. Renovate will automatically create a PR with its base configuration