intentgraph 0.4.0

Static code analysis CLI tool optimized for AI agent context windows - Python analysis with intelligent clustering and AI-friendly output

IntentGraph 🧬

Static codebase analysis optimized for AI context windows - Transform Python, JavaScript, and TypeScript codebases into structured, token-efficient intelligence that fits within AI agent token limits.

🎯 What IntentGraph Actually Does

IntentGraph is a static code analysis CLI tool that:

1. Analyzes Python, JavaScript, and TypeScript codebases using full AST parsing (with basic support for Go)
2. Generates dependency graphs with cycle detection and relationship tracking
3. Calculates code metrics (complexity, maintainability, LOC)
4. Produces AI-optimized JSON output in 3 levels (minimal ~10KB, medium ~70KB, full ~340KB)
5. Intelligently clusters large repos into navigable chunks that fit AI context windows

🎪 What's Real vs. What's Framework

✅ Fully Working:

• Python, JavaScript, and TypeScript code analysis with full AST parsing
• Dependency graph generation with cycle detection
• Code complexity and maintainability metrics
• Three-level output system optimized for AI token limits
• Intelligent clustering for large codebases
• CLI with comprehensive options
• Clean Architecture with good test coverage (617+ tests)

🏗️ Framework/Scaffolding (Partial Implementation):

• AI-native interface exists but query execution returns template data
• Natural language query parsing works, but semantic analysis is basic
• Agent context and response optimization structure is in place
• Task-aware optimization templates exist but need real implementation

Bottom Line: IntentGraph is a production-ready multi-language analysis tool (Python, JavaScript, TypeScript) with an AI-friendly output format, plus a well-architected framework for future AI-native capabilities.

⚡ The Problem IntentGraph Solves

AI coding agents hit context limits. A typical codebase can generate 1-2MB of raw analysis data. AI agents have ~200KB context windows.

Solution: IntentGraph pre-analyzes code and generates minimal, structured output that fits any AI context:

• Minimal mode: ~10KB per repository (paths, dependencies, basic metrics)
• Medium mode: ~70KB (+ key symbols, exports, quality scores)
• Full mode: ~340KB (complete analysis with all metadata)

For massive codebases, intelligent clustering breaks them into navigable 15KB chunks with an AI-friendly index.

🚀 Quick Start

Installation

pip install intentgraph

Basic Usage

# Analyze current directory (minimal output)
intentgraph .

# Generate cluster analysis for large repos
intentgraph . --cluster

# Full analysis with all metadata
intentgraph . --level full --output analysis.json

# Multi-language analysis
intentgraph /path/to/repo --lang py,js,ts

Output Example

{
  "files": [
    {
      "path": "src/analyzer.py",
      "language": "python",
      "dependencies": ["src/models.py", "src/utils.py"],
      "imports": ["pathlib", "typing", "ast"],
      "loc": 245,
      "complexity_score": 12
    }
  ],
  "language_summary": {
    "python": {
      "file_count": 42,
      "total_bytes": 125840
    }
  }
}

🔍 Core Features

1. Deep Multi-Language Analysis

Python:

• Full AST parsing for accurate symbol extraction
• Cyclomatic complexity calculation
• Maintainability index scoring
• Function-level dependencies tracking
• Public API detection (exports, __all__, underscore conventions)

JavaScript:

• Full AST parsing with tree-sitter
• ES6+ support (arrow functions, classes, template literals)
• CommonJS and ES module analysis
• Cyclomatic complexity calculation
• Import/export tracking

TypeScript:

• Full AST parsing with TypeScript-specific features
• Interface and type alias extraction
• Generic type parameter handling
• Decorator support
• Import/export analysis (including type imports)

2. Dependency Graph Generation

• File-level dependencies with import tracking
• Cycle detection and reporting
• Graph statistics (connected components, complexity)
• NetworkX backend for advanced graph operations

3. AI-Optimized Output Levels

Minimal (~10KB):

{
  "path": "analyzer.py",
  "dependencies": ["models.py"],
  "imports": ["ast", "pathlib"],
  "loc": 245,
  "complexity_score": 12
}

Medium (~70KB) adds:

• Key symbols (classes, major functions)
• Export information
• Maintainability scores
• File purpose inference

Full (~340KB) includes:

• All symbols with signatures and docstrings
• Function-level dependencies
• Design patterns detected
• Complete metadata

4. Intelligent Clustering

For repos exceeding AI token limits even with minimal output:

intentgraph . --cluster --cluster-mode analysis --cluster-size 15KB

Output Structure:

.intentgraph/
├── index.json          # Navigation map with recommendations
├── domain.json         # Core business logic cluster
├── adapters.json       # External interfaces cluster
└── application.json    # Application services cluster

Three Clustering Modes:

• analysis: Dependency-based grouping (understand code structure)
• refactoring: Feature-based grouping (make targeted changes)
• navigation: Size-optimized grouping (explore large repos)

The index.json provides AI-friendly navigation:

{
  "cluster_recommendations": {
    "understanding_codebase": ["domain", "application"],
    "finding_bugs": ["domain", "utilities"],
    "adding_features": ["application", "adapters"]
  },
  "clusters": [
    {
      "cluster_id": "domain",
      "file_count": 8,
      "total_size_kb": 12.4,
      "primary_concerns": ["data_models", "business_rules"],
      "complexity_score": 15
    }
  ]
}

🤖 AI Integration Framework

IntentGraph includes a framework for AI-native interaction. The structure is in place, but semantic query execution is still evolving:

from intentgraph import connect_to_codebase

# Framework exists for AI agent context
agent = connect_to_codebase("/path/to/repo", {
    "task": "bug_fixing",
    "token_budget": 30000
})

# Natural language query parsing works
results = agent.query("Find high complexity files")

# Returns structured response (currently template-based)
print(results["strategy"])  # Shows analysis strategy used
print(results["confidence"])  # Confidence level

Current State:

• ✅ Query parsing and intent detection
• ✅ Agent context management
• ✅ Token budget tracking
• ✅ Response optimization templates
• 🏗️ Semantic query execution (uses file-based filtering)
• 🏗️ Deep code understanding from natural language

For Production: Use the CLI mode for reliable analysis. The AI interface provides a foundation for future enhancements.

📊 Language Support

Language	Status	Features
Python	✅ Full	Complete AST parsing, complexity metrics, symbols, dependencies
JavaScript	✅ Full	Full AST parsing, ES6+, complexity, imports/exports
TypeScript	✅ Full	Full AST with TS features, interfaces, generics, decorators
Go	🟡 Basic	File-level dependencies only

Enhanced analysis coming for: Go, Rust, Java, C#

⚙️ Command Line Options

intentgraph [OPTIONS] REPOSITORY_PATH

Analysis Options:
  -o, --output FILE           Output file (- for stdout)
  --level [minimal|medium|full] Analysis detail level [default: minimal]
  --lang TEXT                 Languages to analyze (py,js,ts,go)
  --include-tests            Include test files in analysis
  --format [pretty|compact]  JSON output format
  --show-cycles              Print dependency cycles and exit with code 2
  --workers INTEGER          Parallel workers [default: CPU count]
  --debug                    Enable debug logging

Clustering Options:
  --cluster                  Enable cluster mode for large codebases
  --cluster-mode [analysis|refactoring|navigation]
                             Clustering strategy [default: analysis]
  --cluster-size [10KB|15KB|20KB]
                             Target cluster size [default: 15KB]
  --index-level [basic|rich] Index detail level [default: rich]

🏗️ Architecture

IntentGraph follows Clean Architecture principles:

┌─────────────────┐
│   CLI Layer     │  ← typer, rich console
├─────────────────┤
│ Application     │  ← Orchestration, services
├─────────────────┤
│   Domain        │  ← Core models, business logic
├─────────────────┤
│ Infrastructure  │  ← Parsers, git, I/O
└─────────────────┘

Key Design Patterns:

• Service-oriented application layer
• Dependency injection for testability
• Parser plugin architecture
• NetworkX for graph operations
• ProcessPoolExecutor for parallel analysis

🔧 Development

Setup

git clone https://github.com/Raytracer76/intentgraph.git
cd intentgraph
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

Testing

pytest --cov=intentgraph --cov-report=term-missing

Code Quality

ruff format .           # Format code
ruff check --fix .      # Lint and auto-fix
mypy .                  # Type checking
bandit -r src/          # Security scanning

📖 Use Cases

1. AI Agent Context Preparation

Problem: Large codebase won't fit in AI context window Solution: Use minimal or clustered output

# Generate minimal analysis for AI agent
intentgraph /path/to/large-repo --level minimal --output ai-context.json

# For massive repos, use clustering
intentgraph /path/to/massive-repo --cluster --cluster-mode analysis

2. Code Quality Assessment

Problem: Need to identify technical debt and complexity hotspots Solution: Use full analysis with metrics

intentgraph /path/to/repo --level full --output quality-report.json

3. Dependency Analysis

Problem: Need to understand module relationships and detect cycles Solution: Check for dependency cycles

intentgraph /path/to/repo --show-cycles

4. Large Codebase Navigation

Problem: Repository too large for comprehensive analysis Solution: Use clustering with navigation mode

intentgraph /path/to/large-repo --cluster --cluster-mode navigation

📈 Benchmarks

Repository Size	Files	Analysis Time	Minimal Output	Full Output
Small (< 50 files)	42	2.3s	8KB	180KB
Medium (< 500 files)	287	12.1s	42KB	2.1MB
Large (< 2000 files)	1,654	45.7s	156KB	18.3MB

With clustering, large repos → 3-5 clusters of ~15KB each

🎯 Why Choose IntentGraph

vs GitHub Dependency Graph:

• ✅ Function-level dependencies (not just file-level)
• ✅ Code quality metrics included
• ✅ AI-optimized output (3 levels)
• ✅ Intelligent clustering for large repos
• ✅ Offline analysis

vs SonarQube:

• ✅ AI-friendly JSON output
• ✅ Lightweight CLI tool
• ✅ Token-optimized for AI context windows
• ✅ No server infrastructure required
• ❌ Less comprehensive quality rules (trade-off for simplicity)

vs Tree-sitter:

• ✅ Higher-level semantic analysis (not just syntax)
• ✅ Dependency graph included
• ✅ Pre-optimized for AI consumption
• ✅ Built-in clustering for large repos
• ❌ Fewer languages supported (Python is priority)

🔮 Roadmap

Near Term (v0.3.x):

• Enhanced JavaScript/TypeScript analysis
• Incremental analysis support
• Performance optimizations
• More clustering strategies

Medium Term (v0.4.x):

• Real semantic query execution for AI interface
• Go and Rust language support
• Visual dependency graph generation
• VS Code extension

Long Term (v1.0+):

• Full AI-native autonomous capabilities
• Multi-language unified analysis
• ML-based pattern detection
• Cloud-hosted analysis API

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

Adding Language Support

1. Create parser in src/intentgraph/adapters/parsers/
2. Implement extract_code_structure() method
3. Add tests and examples
4. Submit PR with documentation

Ideas for Contributions

• Enhanced JavaScript/TypeScript parser with full AST analysis
• Go/Rust language support
• Performance optimizations for large repos
• Incremental analysis (only analyze changed files)
• Visual dependency graphs (SVG/PNG generation)

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with Typer for CLI
• Uses grimp for Python dependency analysis
• Powered by Python's ast module
• Graph operations via NetworkX
• Code quality enforcement with Ruff

📞 Support

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and community chat
• Documentation - See /docs directory for detailed guides

---

Made for the AI coding agent era 🤖

IntentGraph helps AI agents understand codebases by providing pre-analyzed, structured intelligence that fits within their context limits. It's a production-ready analysis tool with a vision for autonomous AI integration.