mkctx - Make Context

<picture> <source media="(prefers-color-scheme: dark)" srcset="./black-favicon.svg"> <source media="(prefers-color-scheme: light)" srcset="./white-favicon.svg"> </picture>

A powerful command-line tool that generates comprehensive markdown context files from your project code, perfect for AI prompts and code analysis.

✨ Features

• 🚀 Multi-platform - Works on Windows, macOS, and Linux
• 📝 Smart Ignoring - Respects custom ignore patterns and common system files
• ⚙️ Configurable - Customize source directories, output locations, and comments
• ✏️ Custom Naming - Specify custom filenames for your outputs or use the default 'context'
• 🎯 AI-Friendly - Outputs code in markdown format ideal for AI prompts
• 🎨 Syntax Highlighting - Proper language detection for code blocks
• 🔄 Dynamic Mode - Interactive path selection when needed
• 📊 Context Statistics - Token estimation and file analysis

📦 Installation

npm install -g mkctx

Requirements

• Node.js 18.0+

🚀 Quick Start

Interactive Mode (Recommended)

mkctx

This opens an interactive menu where you can:

1. Generate context from config file or dynamically
2. View context statistics
3. Choose output formats and save with a custom name

Create Configuration File

mkctx config

Show Help

mkctx help

📋 Usage

╔════════════════════════════════════════╗
║     📄 mkctx - Make Context            ║
╚════════════════════════════════════════╝

? What would you like to do?
  ❯ 📁 Generate from config file
    🔍 Generate dynamically (choose path)
    ⚙️  View configuration
    ❌ Exit

After generating context:

📊 Context Summary:
   Files: 42
   Lines: 3,847
   Size: 156.23 KB
   Est. tokens: ~39,058

? Select output format:
  ❯ 📦 All formats (MD, JSON, TOON, XML)
    📝 Markdown (.md)
    🔧 JSON (.json) - Simple array
    🎒 TOON (.toon) - Token-optimized
    📄 XML (.xml)

? Enter a name for the output files: (context)

Note: Simply press Enter to use the default name context.

⚙️ Configuration

Project Configuration (mkctx.config.json)

{
  "src": "./src",
  "ignore": "*.log, temp/, node_modules/, .git/, dist/, build/",
  "output": "./mkctx",
  "first_comment": "/* Project Context */",
  "last_comment": "/* End of Context */"
}

🔧 CLI Options

mkctx                    # Interactive mode (recommended)
mkctx config             # Create configuration file
mkctx help               # Show help message
mkctx version            # Show version

📂 Ignore Patterns

mkctx supports several pattern types:

• Wildcards: *.log, *.test.js, *.spec.ts
• Directories: temp/, dist/, build/
• Glob patterns: **/.cache/, **/node_modules/
• Exact match: config.local.json

Default System Ignores

These are always ignored automatically:

• .git, .svn, .hg
• node_modules, __pycache__
• .DS_Store, Thumbs.db
• .vscode, .idea
• Binary files, images, archives

📄 Output Format

The generated file contains your project code. When saving, you can specify a filename (e.g., my_project_docs.md) or use the default.

/* Project Context */

## Project Structure

```
📁 src/
📁 src/components/
📁 src/utils/

42 files total
```

## Source Files

### src/index.ts

```typescript
import { App } from './app';

const app = new App();
app.start();
```

### src/utils/helpers.ts

```typescript
export function helper() {
  return true;
}
```

/* End of Context */

🎨 Supported Languages

mkctx automatically detects and applies proper syntax highlighting for:

💡 Use Cases

• 🤖 AI Code Analysis - Feed your codebase to ChatGPT, Claude, or other AI tools
• 📚 Code Understanding - Share project overview for quick understanding
• 👥 Code Reviews - Share project overview with reviewers
• 🎓 Onboarding - Help new developers understand the project
• 📝 Documentation - Generate a snapshot of your codebase with custom naming

🖥️ Platform Support

🔧 Troubleshooting

Command Not Found

If mkctx is not found after installation:

1. Make sure npm global bin is in your PATH
2. Try: npm bin -g to see where global packages are installed
3. Restart your terminal

Permission Errors (Unix)

sudo npm install -g mkctx

Or fix npm permissions: https://docs.npmjs.com/resolving-eacces-permissions-errors

📋 Changelog

v4.0.0

• ✏️ Added interactive filename selection when saving (defaults to "context")
• 🎨 Improved UI/UX for file saving workflow

v3.0.0

• 🎯 Simplified to focus on context generation
• 🗑️ Removed Ollama chat integration
• ⚡ Faster startup and smaller footprint
• 🧹 Cleaner codebase

v2.x

• Ollama AI chat integration (removed in v3)
• Interactive chat interface

v1.x

• Initial Go-based implementation

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

📄 License

MIT License - see LICENSE file for details.