grid-analyzer 0.1.1

Understand any codebase in minutes with local-first AI

GRID Analyzer

Understand any codebase in minutes with local-first AI

GRID Analyzer is a privacy-first command-line tool that uses local AI models to help you understand unfamiliar codebases. Index, query, and visualize relationships—all without sending your code to external APIs.

✨ Features

• 🔒 Privacy-First: All analysis happens locally. Your code never leaves your machine.
• 🚀 Fast Indexing: Analyze large codebases (100K+ files) in minutes
• 💬 Natural Language Queries: Ask questions in plain English
• 🗺️ Visual Mapping: Generate interactive relationship graphs
• 🎯 Pattern Detection: Automatically detect architectural patterns
• 🔍 Multi-Language Support: Python, JavaScript, TypeScript, Java, C++, Go, Rust, and more
• 📦 Zero Configuration: Works out of the box

🚀 Quick Start

Installation

pip install grid-analyzer

Running GRID Analyzer

Option 1: Direct command (recommended)

grid --help
grid analyze /path/to/codebase

Option 2: Python module (if grid command not found)

python -m grid_analyze_cli --help
python -m grid_analyze_cli analyze /path/to/codebase

Note: If the grid command isn't found, ensure Python's Scripts directory is in your PATH, or use the python -m grid_analyze_cli syntax which always works.

Basic Usage

# 1. Index your codebase
grid analyze /path/to/codebase

# 2. Ask questions
grid query "Where is user authentication handled?"
grid query "What files connect to the database?"
grid query "How does the payment system work?"

# 3. Generate visual map
grid map --output relationships.html

📖 Documentation

Commands

analyze - Index a codebase

grid analyze <directory> [options]

Options:
  --language LANG       Primary language (auto-detected if not specified)
  --exclude PATTERN     Exclude patterns (can be repeated)
  --output DIR          Output directory (default: .grid)
  -v, --verbose         Verbose output

Examples:

# Analyze current directory
grid analyze .

# Analyze with exclusions
grid analyze ~/projects/myapp --exclude "*.test.js" --exclude "dist"

# Specify primary language
grid analyze . --language python

query - Ask questions about your code

grid query "<question>" [options]

Options:
  --format FORMAT       Output format: text, json, markdown (default: text)
  --limit N             Maximum results (default: 10)

Examples:

# Ask natural language questions
grid query "Where is the API authentication middleware?"
grid query "What functions handle file uploads?"
grid query "Show me all database models"

# Get JSON output for scripting
grid query "list all API endpoints" --format json

# Limit results
grid query "find error handlers" --limit 5

map - Generate relationship graphs

grid map --output <file> [options]

Options:
  --output FILE         Output file (.svg, .pdf, .html, .json)
  --style STYLE         Graph style: default, compact, detailed
  --focus MODULE        Focus on specific module or file

Examples:

# Generate interactive HTML visualization
grid map --output codebase.html

# Focus on specific module
grid map --output auth-system.html --focus "src/auth"

# Export as JSON for custom processing
grid map --output graph.json

config - Manage configuration

grid config <action> [key] [value]

Actions:
  show          Show all configuration
  get KEY       Get specific value
  set KEY VAL   Set configuration value
  reset         Reset to defaults

Examples:

# View configuration
grid config show

# Change settings
grid config set max_file_size_mb 20
grid config set use_color true

# Reset to defaults
grid config reset

license - Manage license

grid license <action> [key]

Actions:
  activate KEY  Activate paid license
  show          Show license information
  deactivate    Deactivate license

Examples:

# Activate Professional license
grid license activate GRID-PRO-XXXXXXXXXXXX

# Check current tier
grid license show

# Deactivate and return to Free tier
grid license deactivate

💰 Pricing

Tier	Price	Max Files	Features
Free	$0	10,000	Local analysis, basic queries
Professional	$20/mo	Unlimited	Advanced queries, relationship mapping
Team	$100/mo	Unlimited	Collaboration, shared indexes, SSO
Enterprise	Contact us	Unlimited	On-premise, custom training, SLA

👉 Upgrade at: https://grid-analyzer.com/pricing

🔧 Advanced Usage

Integrate with CI/CD

# Generate codebase report in CI pipeline
grid analyze . --output /artifacts/grid-index
grid map --output /artifacts/architecture.html
grid query "list all TODO comments" --format json > /artifacts/todos.json

Export Data

# Export relationship data
grid map --output graph.json

# Query results as JSON
grid query "find all API endpoints" --format json > endpoints.json

Configuration File

GRID Analyzer stores configuration in ~/.grid/config.json:

{
  "language": "auto",
  "exclude_patterns": [
    "*.git",
    "node_modules",
    "venv"
  ],
  "max_file_size_mb": 10,
  "use_color": true,
  "check_updates": true
}

🎯 Use Cases

1. Onboarding New Developers

# Create onboarding documentation
grid analyze .
grid map --output architecture.html
grid query "what are the main components?" > onboarding-guide.md

2. Code Reviews

# Understand changes in context
grid analyze /path/to/feature-branch
grid query "what does this PR change?"
grid map --focus "src/changed-module"

3. Debugging Legacy Code

# Find relevant code quickly
grid query "where are database connections created?"
grid query "what handles the payment webhook?"
grid map --focus "src/payments" --output payment-flow.html

4. Documentation Generation

# Auto-generate architecture docs
grid analyze .
grid map --output docs/architecture.html --style detailed
grid query "list all public APIs" --format markdown > docs/api.md

5. Security Audits

# Find security-sensitive code
grid query "where is user input sanitized?"
grid query "what files handle authentication?"
grid query "find all SQL query builders"

6. Refactoring Planning

# Understand dependencies before refactoring
grid map --focus "legacy-module" --output dependencies.html
grid query "what depends on the old API?"

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/yourusername/grid-analyzer.git
cd grid-analyzer
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .

📝 License

MIT License - see LICENSE file for details.

🐛 Bug Reports

Found a bug? Open an issue with:

• Steps to reproduce
• Expected vs actual behavior
• GRID version (grid --version)
• Operating system

💬 Support

• 📖 Documentation: https://docs.grid-analyzer.com
• 💬 Discord: https://discord.gg/grid-analyzer
• 📧 Email: [e-mail]
• 🐦 Twitter: @grid_analyzer

🙏 Acknowledgments

Built with:

• Local AI models (no external API calls)
• AST parsing for code analysis
• Graph visualization with D3.js
• Privacy-first architecture

---

Made with ❤️ by the GRID Team

Website • Documentation • Twitter