code2llm 0.5.18

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 (Chunking)

For repositories >100 files, automatic chunking splits analysis into smaller subprojects:

# Auto-chunking when >100 files detected
code2llm ./ -f toon,evolution,code2logic --verbose

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

# Analyze only specific subproject
code2llm ./ -f toon --only-subproject src

# Skip tests and examples
code2llm ./ -f toon --skip-subprojects tests examples

# Customize file limit per chunk
code2llm ./ -f toon --chunk --max-files-per-chunk 50

Chunking Benefits:

• Each subproject analyzed separately (examples/, tests/, src/, etc.)
• Output limited to ~256KB per file (configurable)
• Parallel processing of chunks possible
• Reduced memory usage for large repos

Output Structure:

./project/
  ├── src/                    # Core code analysis
  │   ├── analysis.toon
  │   └── evolution.toon
  ├── tests/                 # Test code analysis
  │   └── analysis.toon
  ├── examples/              # Examples analysis
  │   └── analysis.toon
  ├── analysis.toon          # Merged summary
  └── evolution.toon         # Full refactoring queue

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]