📸 ScanEx

A powerful CLI tool that automatically discovers and bundles related source code into a single markdown file, perfect for sharing with LLMs like ChatGPT, Claude, or Cursor AI.

ScanEx = Scan and Export - because that's exactly what it does! 🎯

🎯 Why ScanEx?

I wrote this project because I wanted to copy and paste source code quickly to ask LLMs for help.

While coding with Cursor, or when I want to ask something about my implementation on ChatGPT or Google AI Studio, I have to copy related source code way too many times. I have to search and copy a lot of files manually.

So I decided to implement something where I can just point to a file, and it will automatically scan related files and write it out for me.

That's it. Simple problem, simple solution. Now instead of spending 10 minutes copying files, I just run one command and get everything I need. 🎯

✨ Features

• 🔍 Smart Dependency Detection - Uses tree-sitter to analyze actual imports/requires
• 📁 Directory Tree Visualization - Shows your project structure at a glance
• 🚀 Multi-Language Support - Works with 13+ programming languages
• ⚡ Fast & Efficient - Lightning-fast dependency resolution
• 🙈 Respects .gitignore - Automatically excludes ignored files
• 🔧 TypeScript/JavaScript Aliases - Resolves path aliases from tsconfig.json
• 🐚 Unix-friendly - Pipes naturally with other command-line tools
• 📋 Copy-Ready - Perfect for pasting into AI chat interfaces

🚀 Installation

npm install -g scanex

📋 Quick Start

# Analyze current directory and copy to clipboard (macOS)
scanex | pbcopy

# Save analysis to a file
scanex > my-project.md

# Analyze specific files
scanex --input src/main.js > analysis.md

# Analyze directory with custom output
scanex --input src/ --output docs/codebase.md

🎯 Common Use Cases

💬 Sharing Code with AI Assistants

# Quick copy for ChatGPT/Claude
scanex --input src/components/UserForm.tsx | pbcopy

# Analyze a bug and share context
scanex --input src/utils/api.js --exclude "test|spec" > bug-report.md

📚 Documentation & Code Reviews

# Create comprehensive project documentation
scanex --exclude "node_modules|dist|build" > PROJECT_OVERVIEW.md

# Focus on specific modules
scanex --input src/auth/ > auth-module-docs.md

🐛 Bug Reports with Full Context

# Include all related files for a bug report
scanex --input src/problematic-file.js > bug-context.md

🛠️ Usage

Basic Syntax

scanex [options]

Options

| Option | Description | Example | |--------|-------------|---------| | -i, --input <paths> | Comma-separated files or directories to analyze | --input src/main.js,lib/utils.js | | -e, --exclude <pattern> | Regex pattern of paths to ignore | --exclude "test\|spec\|dist" | | -o, --output <file> | Write output to specified file instead of stdout | --output documentation.md | | -V, --version | Display version number | | | --help | Show help information | |

Examples

📁 Directory Analysis

# Analyze entire project
scanex

# Analyze specific directory
scanex --input src/

# Exclude test files and build artifacts  
scanex --exclude "test|spec|dist|build|node_modules"

📄 File Analysis

# Analyze single file and its dependencies
scanex --input src/main.js

# Analyze multiple specific files
scanex --input src/api.js,src/utils.js,src/types.ts

🔧 Advanced Usage

# Unix-style piping
scanex | grep "function" | head -20

# Combine with other tools
scanex --input src/ | wc -l  # Count lines

# Save to custom location
scanex --input backend/ --output docs/backend-analysis.md

🌐 Supported Languages

ScanEx intelligently analyzes dependencies across multiple languages:

| Language | Extensions | Features | |----------|------------|----------| | JavaScript | .js, .mjs, .cjs | ES6 imports, CommonJS requires | | TypeScript | .ts, .tsx | Path aliases, type imports | | React/JSX | .jsx, .tsx | Component imports, hooks | | Python | .py | Import statements, relative imports | | Ruby | .rb | Require statements, gem dependencies | | ERB | .html.erb | Ruby + HTML template analysis | | CSS/SCSS | .css, .scss, .sass, .less, .styl | @import, url() references | | SQL | .sql, .ddl, .dml, .pgsql, .mysql | Include statements, file references | | HTML | .html, .htm | Script/style/link references | | YAML | .yml, .yaml | File references, includes | | JSON | .json | Configuration file analysis | | Markdown | .md | Link and image references | | Shell | .sh, .bash, .zsh, .fish | Source statements, script includes | | Docker | Dockerfile | COPY/ADD instructions |

📊 Output Format

ScanEx generates clean, structured markdown:

<directory_tree>
.
├── src/
│   ├── components/
│   │   ├── Header.tsx
│   │   └── Footer.tsx
│   ├── utils/
│   │   └── api.ts
│   └── main.ts
└── package.json
</directory_tree>

<codebase>

#### `src/main.ts`
```typescript
import { Header } from './components/Header';
import { apiCall } from './utils/api';
// ... rest of the code
```

#### `src/components/Header.tsx`
```tsx
import React from 'react';
// ... component code
```

</codebase>

⚙️ Configuration

TypeScript/JavaScript Path Aliases

ScanEx automatically detects and resolves path aliases from:

• tsconfig.json
• jsconfig.json

Example tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

.gitignore Integration

ScanEx automatically respects .gitignore files at any level in your project, so you don't need to worry about including:

• node_modules/
• Build artifacts (dist/, build/)
• IDE files (.vscode/, .idea/)
• OS files (.DS_Store)

🔧 Advanced Features

Project Root Detection

ScanEx intelligently detects your project root by looking for:

1. Git repository (.git directory)
2. Package files (package.json, pyproject.toml, Cargo.toml, etc.)
3. Fallback to input directory

Smart Dependency Resolution

• Tree-sitter parsing for accurate import detection
• Path alias resolution for TypeScript/JavaScript projects
• Relative import handling across all languages
• Circular dependency detection and handling

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/darkamenosa/scanex.git
cd scanex

# Install dependencies
npm install

# Run locally
node bin/scanex.js --help

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with tree-sitter for accurate code parsing
• Inspired by the need for better AI-human collaboration in coding
• Thanks to the open-source community for language grammar definitions

Made with ❤️ for developers who love AI-assisted coding

ScanEx - Because your AI deserves better context 🚀