code2llm 0.5.23

High-performance Python code flow analysis with optimized TOON format - CFG, DFG, call graphs, and intelligent code queries

code2llm - Generated Analysis Files

This directory contains the complete analysis of your Python project generated by code2llm. Each file serves a specific purpose for understanding, refactoring, and documenting your codebase.

📁 Generated Files Overview

When you run code2llm ./ -f all, the following files are created:

🎯 Core Analysis Files

File	Format	Purpose	Key Insights
analysis.toon	TOON	🔥 Health diagnostics - Complexity, god modules, coupling	43 critical functions, 0 god modules
project.toon	TOON	🧠 Project logic - Compact module view from code2logic	Generated via code2logic integration

🤖 LLM-Ready Documentation

File	Format	Purpose	Use Case
context.md	Markdown	📖 LLM narrative - Architecture summary	Paste into ChatGPT/Claude for code analysis

🚀 Quick Start Commands

Basic Analysis

# Quick health check (TOON format only)
code2llm ./ -f toon

# Generate all formats (what created these files)
code2llm ./ -f all

# LLM-ready context only
code2llm ./ -f context

Performance Options

# Fast analysis for large projects
code2llm ./ -f toon --strategy quick

# Memory-limited analysis
code2llm ./ -f all --max-memory 500

# Skip PNG generation (faster)
code2llm ./ -f all --no-png

Large Repository Analysis (Hierarchical Chunking)

For large repositories, automatic hierarchical chunking ensures each output file stays under 256KB:

# Auto-chunking when estimated output >256KB
code2llm ./ -f toon,evolution,code2logic --verbose

# Force chunking with custom size limit
code2llm ./ -f toon --chunk --chunk-size 256

# Analyze only specific subproject (matches level-1 or level-2 names)
code2llm ./ -f toon --only-subproject src
code2llm ./ -f toon --only-subproject src.core

# Skip specific directories
code2llm ./ -f toon --skip-subprojects tests examples docs

# Customize chunking parameters
code2llm ./ -f toon --chunk --max-files-per-chunk 50 --chunk-size 512

Hierarchical Splitting Strategy:

1. Level 0: Entire project (if small enough, <256KB)
2. Level 1: Top-level directories (src/, tests/, examples/)
3. Level 2: Subdirectories if parent >256KB (src.core/, src.utils/)
4. Level 3: File chunks if still too large

Example Output Structure:

./project/
  ├── src/                    # Level 1: src/ fits in 256KB
  │   ├── analysis.toon       # (~200KB)
  │   └── evolution.toon
  ├── src_core/               # Level 2: src/core/ was too big
  │   ├── analysis.toon       # (~180KB)
  │   └── evolution.toon
  ├── src_utils_part1/        # Level 3: split by file count
  │   └── analysis.toon         # (~150KB)
  ├── tests/                  # Level 1: tests/
  │   └── analysis.toon
  ├── examples/               # Level 1: examples/
  │   └── analysis.toon
  ├── analysis.toon           # Merged summary (all levels)
  └── evolution.toon          # Full refactoring queue

Size Estimation:

• ~3KB per Python file in TOON format
• Auto-detect chunking when: file_count × 3KB > 256KB
• Example: 100 files ≈ 300KB → triggers chunking

Benefits:

• Each output file <256KB (easy for LLMs to process)
• Natural code boundaries (module/submodule level)
• Incremental analysis possible
• Parallel processing ready

Refactoring Focus

# Get refactoring recommendations
code2llm ./ -f evolution

# Focus on specific code smells
code2llm ./ -f toon --refactor --smell god_function

# Data flow analysis
code2llm ./ -f flow --data-flow

📖 Understanding Each File

analysis.toon - Health Diagnostics

Purpose: Quick overview of code health issues Key sections:

• HEALTH: Critical issues (🔴) and warnings (🟡)
• REFACTOR: Prioritized refactoring actions
• COUPLING: Module dependencies and potential cycles
• LAYERS: Package complexity metrics
• FUNCTIONS: High-complexity functions (CC ≥ 10)
• CLASSES: Complex classes needing attention

Example usage:

# View health issues
cat analysis.toon | head -30

# Check refactoring priorities
grep "REFACTOR" analysis.toon

evolution.toon - Refactoring Queue

Purpose: Step-by-step refactoring plan Key sections:

• NEXT: Immediate actions to take
• RISKS: Potential breaking changes
• METRICS-TARGET: Success criteria

Example usage:

# Get refactoring plan
cat evolution.toon

# Track progress
grep "NEXT" evolution.toon

flow.toon - Data Flow Analysis

Purpose: Understand data movement through the system Key sections:

• PIPELINES: Data processing chains
• CONTRACTS: Function input/output contracts
• SIDE_EFFECTS: Functions with external impacts

Example usage:

# Find data pipelines
grep "PIPELINES" flow.toon

# Identify side effects
grep "SIDE_EFFECTS" flow.toon

map.toon - Structural Map

Purpose: High-level architecture overview Key sections:

• MODULES: All modules with basic stats
• IMPORTS: Dependency relationships
• SIGNATURES: Public API functions

Example usage:

# See project structure
cat map.toon | head -50

# Find public APIs
grep "SIGNATURES" map.toon

project.toon - Project Logic (Code2Logic)

Purpose: Compact module view generated by code2logic integration Key sections:

• Modules list: All project modules with file sizes
• Imports: Dependency information
• Classes/Functions: Summary counts

When to use: When you need a lightweight project overview combined with code2llm analysis

Example usage:

# View compact project structure
cat project.toon | head -30

# Find largest files
grep -E "^  .*[0-9]{3,}$" project.toon | sort -t',' -k2 -n -r | head -10

prompt.txt - Ready-to-Send LLM Prompt

Purpose: Pre-formatted prompt listing all generated files for LLM conversation Contents:

• Files section: Lists all existing generated files with descriptions
• Missing section: Shows which files weren't generated (if any)
• Task section: Instructions for LLM analysis
• Requirements section: Guidelines for suggested changes

Example usage:

# View the prompt
cat prompt.txt

# Copy to clipboard and paste into ChatGPT/Claude
cat prompt.txt | pbcopy  # macOS
cat prompt.txt | xclip -sel clip  # Linux

context.md - LLM Narrative

Purpose: Ready-to-paste context for AI assistants Key sections:

• Overview: Project statistics
• Architecture: Module breakdown
• Entry Points: Public interfaces
• Patterns: Design patterns detected

Example usage:

# Copy to clipboard for LLM
cat context.md | pbcopy  # macOS
cat context.md | xclip -sel clip  # Linux

# Use with Claude/ChatGPT for code analysis

Visualization Files (*.mmd, *.png)

Purpose: Visual understanding of code structure Files:

• flow.mmd - Detailed control flow with complexity colors
• calls.mmd - Simple call graph
• compact_flow.mmd - High-level module view
• *.png - Pre-rendered images

Example usage:

# View diagrams
open flow.png  # macOS
xdg-open flow.png  # Linux

# Edit in Mermaid Live Editor
# Copy content of .mmd files to https://mermaid.live

🔍 Common Analysis Patterns

1. Code Health Assessment

# Quick health check
code2llm ./ -f toon
cat analysis.toon | grep -E "(HEALTH|REFACTOR)"

2. Refactoring Planning

# Get refactoring queue
code2llm ./ -f evolution
cat evolution.toon

# Focus on specific issues
code2llm ./ -f toon --refactor --smell god_function

3. LLM Assistance

# Generate context for AI
code2llm ./ -f context
cat context.md

# Use with Claude: "Based on this context, help me refactor the god modules"

4. Team Documentation

# Generate all docs for team
code2llm ./ -f all -o ./docs/

# Create visual diagrams
open docs/flow.png

📊 Interpreting Metrics

Complexity Metrics (CC)

• 🔴 Critical (≥5.0): Immediate refactoring needed
• 🟠 High (3.0-4.9): Consider refactoring
• 🟡 Medium (1.5-2.9): Monitor complexity
• 🟢 Low (0.1-1.4): Acceptable
• ⚪ Basic (0.0): Simple functions

Module Health

• GOD Module: Too large (>500 lines, >20 methods)
• HUB: High fan-out (calls many modules)
• FAN-IN: High incoming dependencies
• CYCLES: Circular dependencies

Data Flow Indicators

• PIPELINE: Sequential data processing
• CONTRACT: Clear input/output specification
• SIDE_EFFECT: External state modification

🛠️ Integration Examples

CI/CD Pipeline

#!/bin/bash
# Analyze code quality in CI
code2llm ./ -f toon -o ./analysis
if grep -q "🔴 GOD" ./analysis/analysis.toon; then
    echo "❌ God modules detected"
    exit 1
fi

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
code2llm ./ -f toon -o ./temp_analysis
if grep -q "🔴" ./temp_analysis/analysis.toon; then
    echo "⚠️  Critical issues found. Review before committing."
fi
rm -rf ./temp_analysis

Documentation Generation

# Generate docs for README
code2llm ./ -f context -o ./docs/
echo "## Architecture" >> README.md
cat docs/context.md >> README.md

📚 Next Steps

1. Review analysis.toon - Identify critical issues
2. Check evolution.toon - Plan refactoring priorities
3. Use context.md - Get LLM assistance for complex changes
4. Reference visualizations - Understand system architecture
5. Track progress - Re-run analysis after changes

🔧 Advanced Usage

Custom Analysis

# Deep analysis with all insights
code2llm ./ -m hybrid -f all --max-depth 15 -v

# Performance-optimized
code2llm ./ -m static -f toon --strategy quick

# Refactoring-focused
code2llm ./ -f toon,evolution --refactor

Output Customization

# Separate output directories
code2llm ./ -f all -o ./analysis-$(date +%Y%m%d)

# Split YAML into multiple files
code2llm ./ -f yaml --split-output

# Separate orphaned functions
code2llm ./ -f yaml --separate-orphans

---

Generated by: code2llm ./ -f all --readme
Analysis Date: 2026-03-03
Total Functions: 700
Total Classes: 97
Modules: 83

For more information about code2llm, visit: https://github.com/tom-sapletta/code2llm

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - [e-mail]