codeview 1.0.0

A powerful tool to visualize codebases for LLM interactions

CodeView

A powerful tool to visualize codebases for LLM interactions and documentation purposes.

Features

• 🌳 Directory Tree Visualization: Display your codebase structure in a clear, hierarchical format
• 📄 File Content Display: Show the contents of all code files with optional line numbers
• 🔍 Smart Filtering: Include/exclude files and directories with pattern matching
• 🎯 Search Functionality: Find files containing specific patterns
• 📊 Multiple Output Formats: Text, Markdown, and JSON formats
• 🚀 Fast and Lightweight: No external dependencies, uses only Python standard library

Installation

From PyPI

pip install codeview

From Source

git clone https://github.com/ZiadAmerr/codeview.git
cd codeview
pip install -e .

Usage

Basic Usage

Show all code files in the current directory:

codeview

Common Examples

Only show Python and JavaScript files:

codeview -i "*.py" -i "*.js"

Exclude specific directories:

codeview -e node_modules -e .git

Limit directory traversal depth:

codeview -d 2

Search for files containing a specific pattern:

codeview -s "def main"

Include only specific directories:

codeview -p src/models -p src/utils

Output to a markdown file:

codeview -m markdown -o codebase.md

Show line numbers:

codeview -n

All Options

Options:
  -h, --help                 Show this help message
  -i, --include PATTERN      File patterns to include (can be used multiple times)
  -e, --exclude-dir DIR      Directories to exclude (can be used multiple times)
  -x, --exclude-file PATTERN File patterns to exclude (can be used multiple times)
  -d, --max-depth DEPTH      Maximum directory depth to traverse
  -t, --no-tree              Don't show directory tree
  -f, --no-files             Don't show file contents
  -n, --line-numbers         Show line numbers in file contents
  -o, --output FILE          Write output to file instead of stdout
  -s, --search PATTERN       Only include files containing the pattern
  -p, --path DIR             Include specific directory (can be used multiple times)
  -m, --format FORMAT        Output format: text (default), markdown, json

Use Cases

1. LLM Context Preparation

Prepare your codebase for sharing with LLMs like ChatGPT or Claude:

codeview -m markdown -o codebase.md

2. Code Documentation

Generate documentation of your project structure:

codeview -t -m markdown -o structure.md

3. Code Review

Extract specific parts of your codebase for review:

codeview -p src/critical -n -o review.txt

4. Project Analysis

Get a JSON representation for programmatic analysis:

codeview -m json -o analysis.json

Default Behavior

Included File Types

By default, CodeView includes common code file types:

• Python (*.py)
• JavaScript/TypeScript (*.js, *.jsx, *.ts, *.tsx)
• Java (*.java)
• C/C++ (*.c, *.cpp, *.h, *.hpp)
• And many more...

Excluded Directories

By default, CodeView excludes common non-code directories:

• Version control (.git, .svn, .hg)
• Dependencies (node_modules, venv, .venv)
• Build artifacts (dist, build, *.egg-info)
• IDE files (.idea, .vscode)

Python API

You can also use CodeView programmatically:

from pathlib import Path
from codeview import CodebaseScanner, MarkdownFormatter

# Create scanner
scanner = CodebaseScanner(
    root_dir=Path.cwd(),
    include_patterns=["*.py"],
    exclude_dirs=["tests"]
)

# Scan codebase
result = scanner.scan()

# Format output
formatter = MarkdownFormatter()
output = formatter.format(result, show_tree=True, show_files=True)

print(output)

File Status Indicators

CodeView now shows which files will be logged (included in output) and which will be skipped:

Text Format

Directory Structure:
--------------------------------------------------------------------------------
├── [✓] main.py  (LOGGED)
├── [✗] test.txt  (SKIPPED)
└── src/
    ├── [✓] utils.py  (LOGGED)
    └── [✗] backup.bak  (SKIPPED)

Markdown Format

## Directory Structure

- ✅ main.py **LOGGED**
- ❌ test.txt ~~SKIPPED~~
- **src/**
  - ✅ utils.py **LOGGED**
  - ❌ backup.bak ~~SKIPPED~~

JSON Format

{
  "file_count": 2,
  "total_files": 4,
  "files_logged": ["main.py", "src/utils.py"],
  "files_skipped": ["test.txt", "src/backup.bak"],
  "tree": {
    "_files": [
      {"name": "main.py", "included": true, "path": "main.py"},
      {"name": "test.txt", "included": false, "path": "test.txt"}
    ]
  }
}

This makes it easy to see at a glance which files match your filters and will be included in the output.

Colored Output

CodeView supports beautiful colored terminal output to make the information easier to read and parse visually.

Color Features

• Headers: Bright cyan for main headers, blue for subheaders
• Directories: Bold blue for directory names
• Logged Files: Green for files that will be included in output
• Skipped Files: Dimmed gray for files that will be excluded
• Markers: Bright green ✓ for logged, bright red ✗ for skipped
• Statistics: Yellow for numbers, white for labels
• File Paths: Magenta for file paths in content sections
• Line Numbers: Dimmed yellow for line numbers
• Separators: Dimmed gray for visual separators

Color Control

# Default: Auto-detect color support
codeview

# Explicitly disable colors
codeview --no-color

# Force colors even when piping
codeview --force-color | less -R

# Colors are automatically disabled when:
# - Output is redirected to a file (-o option)
# - Output format is markdown or json
# - NO_COLOR environment variable is set
# - Terminal doesn't support ANSI colors

Environment Variables

• NO_COLOR: Set to any value to disable colors
• FORCE_COLOR: Set to any value to force enable colors
• TERM: Used to detect color support (set to 'dumb' to disable)

Example Output

When colors are enabled, you'll see:

• 📁 Bright cyan codebase header
• 📂 Blue directory structure section
• Green ✓ for files that will be logged
• Red ✗ for files that will be skipped
• Magenta file paths in content sections
• Yellow statistics and line numbers

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Ziad Amerr - [e-mail]