CedarMapper: Advanced Repository Analysis for LLM Consumption

CedarMapper is a powerful CLI tool for code analysis and repository visualization that generates comprehensive project analytics for LLM consumption. Perfect for developer tools workflows, this directory analysis solution provides code statistics and code overview capabilities with multi-key sorting and structured YAML output.

✨ Key Features: Repository Analysis & Code Statistics

🎯 Structured YAML Output with front matter for programmatic consumption
📊 Advanced Analytics Columns: node depth, file/directory counts, average statistics
🔄 13-Key Advanced Sorting: comprehensive multi-key sorting capabilities
✂️ Git-Style Line Limiting: top-N results with familiar -N syntax
⚡ Performance Optimized: Linux tool integration and conditional computation
🌳 Rich Tree Views: numbered indentation and prefix separation
🔍 Binary File Detection: intelligent content analysis and caching

🚀 Quick Start: CLI Tool Installation & Usage

Installation

pip install cedarmapper

Basic Usage

# Basic repository overview
cedarmapper ls .

# Advanced analytics with all new columns
cedarmapper ls src/ --tree --node-depth --file-count --dir-count --avg-words --avg-size

# Structured YAML output for LLM consumption
cedarmapper ls src/render/ --yaml

# Find largest directories quickly
cedarmapper ls . --sort "-sf" --max-depth 3

# Top 10 largest files (git-style syntax)
cedarmapper ls . -10 --sort "-s"

🎯 Structured YAML Output: LLM-Optimized Data Format

Generate machine-readable repository analysis with comprehensive metadata:

$ cedarmapper ls src/cedarmapper/render/ --yaml

Output:

---
metadata:
  command: cedarmapper ls --yaml
  timestamp: '2025-11-28T15:39:55.681996'
  root_path: /home/ecc/IdeaProjects/cedarmapper/src/cedarmapper/render
summary:
  total_files: 12
  total_directories: 1
  total_bytes: 84846
  total_words: 3824
  binary_files: 6
  text_files: 6
---
entries:
- name: render
  path: ./
  type: dir
  size_bytes: 84846
  mtime: '2025-11-28T15:17:22.909272'
  depth: 0
  word_count: 3824
  file_count: 0
  dir_count: 0
  avg_words_per_file: 0
  avg_size_per_file: 0
- name: flat.py
  path: flat.py
  type: file
  size_bytes: 7847
  mtime: '2025-11-28T15:14:42.546386'
  depth: 1
  word_count: 703
  is_binary: false
- name: utils.py
  path: utils.py
  type: file
  size_bytes: 10546
  mtime: '2025-11-28T15:17:16.915884'
  depth: 1
  word_count: 989
  is_binary: false
# ... more entries

Perfect for:

LLM repository analysis workflows
Automated documentation generation
CI/CD pipeline integration
Code review automation

📊 Advanced Analytics: Project Statistics & Directory Analysis

Display comprehensive statistics about your repository structure:

$ cedarmapper ls src/ --tree --node-depth --file-count --dir-count --avg-words --avg-size --max-depth 2

Output:

  Words         Size Depth  Files  Dirs    Avg-W     Avg-S            Modified Path
    0      0     1                       6852       149893 2025-11-28T15:20:49 src/
    0      1     4     12.0   149,893    6852       149893 2025-11-28T15:20:49 └── cedarmapper/
    0      2     1    823.0    16,772    1646        33545 2025-11-28T15:20:49    ├── cli/
    0      6     1    637.3    14,141    3824        84846 2025-11-28T15:17:22    ├── render/
    0      4     1    342.5     7,783    1370        31131 2025-11-28T15:08:10    ├── core/
------- ------------ ----- ------ ----- -------- --------- ------------------- --------------------
   6852       149893                                       2025-11-28T15:20:49 TOTAL

Columns Explained:

Depth: Node depth in directory tree
Files: Number of files in directory
Dirs: Number of subdirectories
Avg-W: Average words per file (text files only)
Avg-S: Average size per file in bytes

🔄 13-Key Advanced Sorting

Comprehensive multi-key sorting for any analysis need:

Sort Keys Reference

Key	Description	Example
`w`	Word count	`--sort -w` (most words first)
`s`	File size	`--sort -s` (largest first)
`d`	Modification date	`--sort -d` (newest first)
`i`	Node depth	`--sort i` (shallowest first)
`n`	File/directory name	`--sort n` (alphabetical)
`p`	Full path	`--sort p` (path alphabetical)
`f`	File count (dirs only)	`--sort -f` (most files first)
`r`	Directory count (dirs only)	`--sort -r` (most subdirs first)
`a`	Average words per file	`--sort -a` (highest avg first)
`z`	Average size per file	`--sort -z` (largest avg first)
`b`	Binary flag (files only)	`--sort b` (text files first)

Advanced Sorting Examples

# Find directories with most files, then by size
cedarmapper ls . --sort "-sf" --max-depth 3

# Complex multi-key: depth asc, size desc, date asc
cedarmapper ls . --sort "i-sd" -15

# Find content-heavy files (text files, most words first)
cedarmapper ls . --sort "wb" --max-depth 4

# Quick repository overview: depth, then size descending
cedarmapper ls . --sort "i-s" -10

✂️ Git-Style Line Limiting

Get top-N results with familiar git-style syntax:

# Show top 10 largest items
cedarmapper ls . -10 --sort "-s"

# Tree view with limited results
cedarmapper ls . --tree -10 --max-depth 1

Output:

Words         Size            Modified Path
  94294     14947634 2025-11-28T15:25:22 cedarmapper/
   5222       278743 2025-11-28T15:25:22 ├── .git/
   6852       149893 2025-11-28T15:20:49 ├── src/
    163         6775 2025-11-28T15:19:37 ├── .pytest_cache/
   3820        49719 2025-11-28T15:19:37 ├── coverage.xml
  44960       791406 2025-11-28T15:19:37 ├── htmlcov/
      -        98304 2025-11-28T15:19:36 ├── .coverage
    333         3136 2025-11-28T15:05:48 ├── pyproject.toml
   7066        60627 2025-11-28T14:59:57 ├── planning/
   4601       225001 2025-11-27T21:13:44 ├── tests/
------- ------------ ------------------- --------------------
  94294     14947634 2025-11-28T15:25:22 TOTAL

⚡ Performance Features: High-Speed Directory Analysis

Linux Tool Integration

CedarMapper automatically leverages Linux tools for maximum performance:

file command for intelligent binary detection
wc command for ultra-fast word counting
stat command for rapid file size analysis

Conditional Computation

Only compute what you need for optimal performance:

Count calculations only when count columns are displayed
Average calculations only when average columns are requested
Depth computation only when needed for sorting

Performance Examples

# Fast analysis (skip word counting)
cedarmapper ls . --skip-word-count

# Quick overview with word counts enabled
cedarmapper ls . --show-word-count

# Analysis targeting specific directories
cedarmapper ls src/ --max-depth 2 --file-count --dir-count

🔧 Practical Workflows: Real-World Developer Tools Usage

Repository Overview for LLMs

# Complete structured analysis for AI consumption
cedarmapper ls . --yaml > repo_overview.yaml

# Quick project statistics
cedarmapper ls . --node-depth --file-count --dir-count --avg-words --avg-size

Code Review Preparation

# Find recently changed, large files
cedarmapper ls . --sort "-sd" -20

# Identify code-heavy directories
cedarmapper ls . --sort "-af" --max-depth 3

# Binary file analysis
cedarmapper ls . --sort "b" --max-depth 4

Documentation Analysis

# Focus on content-rich directories
cedarmapper ls docs/ --sort "-aw" --max-depth 2

# Average file size analysis for documentation planning
cedarmapper ls docs/ --avg-size --avg-words --tree

Performance Auditing

# Identify largest files and directories
cedarmapper ls . --sort "-s" -10

# Find directories with many files
cedarmapper ls . --sort "-f" --max-depth 3

# Analyze file size distribution
cedarmapper ls . --sort "z" --avg-size --max-depth 2

📊 Feature Comparison: CedarMapper vs Other Code Analysis Tools

Feature	CedarMapper	`tree`	`fd/find`	`llm-repo-tools`
LLM-Optimized	✅	❌	❌	✅
YAML Output	✅	❌	❌	✅
Word Counting	✅	❌	❌	✅
Binary Detection	✅	❌	❌	✅
13 Sort Keys	✅	❌	❌	3-6
Statistical Columns	✅	❌	❌	❌
Line Limiting	✅	❌	✅	❌
Linux Tool Integration	✅	❌	❌	❌
Conditional Computation	✅	❌	❌	❌
Multi-Key Sorting	✅	❌	❌	Limited

🛠️ Installation & Development

Installation

# Install from PyPI
pip install cedarmapper

# Development installation
pip install -e ".[dev]"

Development Setup

# Clone repository
git clone https://github.com/your-username/cedarmapper.git
cd cedarmapper

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
make install

Testing

# Run full test suite (55 tests passing)
make test

# Quick tests without coverage
make quick

# Run specific test file
make test-file FILE=tests/test_sort.py

# View coverage report
make coverage-open

Code Quality

# Auto-format code
make format

# Run linting and type checking
make lint

# Full CI pipeline
make ci

📋 Command Reference

Core Options

Option	Short	Description
`--max-depth N`	`-d N`	Limit display depth (0=root only)
`--tree`	`-t`	Tree-like nested output
`--numbered-indent`	`-n`	Numbered depth prefixes
`--tree-only`	`-T`	Show only paths (tree-only mode)
`--short`	`-S`	Tree-only + word count

Analytics Options

Option	Description
`--node-depth`	Show node depth column
`--skip-node-depth`	Hide node depth column
`--file-count`	Show file count column
`--dir-count`	Show directory count column
`--avg-words`	Show average words per file
`--avg-size`	Show average size per file

Performance Options

Option	Description
`--skip-word-count`	Skip word counting for speed
`--show-word-count`	Force word count display
`--follow-symlinks`	Follow symbolic links

Output Options

Option	Description
`--yaml`	`-Y`
`--date-format FORMAT`	Date format: 'seconds', 'day', 's', 'd'
`--skip-date`	Hide date column
`--skip-header`	Hide column headers
`--skip-totals`	Hide totals footer

Sorting & Limiting

Option	Description
`--sort SPEC`	Sort specification (see sort keys)
`--line-limit N`	`-N`

❓ Troubleshooting & FAQ

Common Questions

Q: How do I get a quick overview of my repository?

cedarmapper ls . --node-depth --file-count --dir-count --max-depth 2

Q: How do I find the largest files in my project?

cedarmapper ls . --sort "-s" -10

Q: How do I generate input for an LLM?

cedarmapper ls . --yaml > repo_analysis.yaml

Q: How do I focus on code files only?

cedarmapper ls . --sort "wb" --max-depth 3

Performance Tips

Use --skip-word-count for very large repositories
Apply --max-depth to limit analysis scope
Use line limiting (-N) for quick overviews
Consider YAML output for automated workflows

Linux Tool Requirements

CedarMapper automatically falls back to Python implementations if Linux tools are unavailable:

file command for binary detection
wc command for word counting
stat command for file metadata

📄 License

Apache License 2.0 - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (make test)
Submit a pull request

CedarMapper: Transform repository complexity into clear, actionable insights for AI-powered development workflows.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.claude		.claude
.github/workflows		.github/workflows
planning		planning
src/cedarmapper		src/cedarmapper
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
cedarmapper.iml		cedarmapper.iml
pyproject.toml		pyproject.toml

License

CedarVerse/cedarmapper

Folders and files

Latest commit

History

Repository files navigation

CedarMapper: Advanced Repository Analysis for LLM Consumption

✨ Key Features: Repository Analysis & Code Statistics

🚀 Quick Start: CLI Tool Installation & Usage

Installation

Basic Usage

🎯 Structured YAML Output: LLM-Optimized Data Format

📊 Advanced Analytics: Project Statistics & Directory Analysis

🔄 13-Key Advanced Sorting

Sort Keys Reference

Advanced Sorting Examples

✂️ Git-Style Line Limiting

⚡ Performance Features: High-Speed Directory Analysis

Linux Tool Integration

Conditional Computation

Performance Examples

🔧 Practical Workflows: Real-World Developer Tools Usage

Repository Overview for LLMs

Code Review Preparation

Documentation Analysis

Performance Auditing

📊 Feature Comparison: CedarMapper vs Other Code Analysis Tools

🛠️ Installation & Development

Installation

Development Setup

Testing

Code Quality

📋 Command Reference

Core Options

Analytics Options

Performance Options

Output Options

Sorting & Limiting

❓ Troubleshooting & FAQ

Common Questions

Performance Tips

Linux Tool Requirements

📄 License

🤝 Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 2

Uh oh!

Languages