Static Analysis Setup for Claude Code

For Claude Code Agents: This README is your entry point for guiding users through static analysis setup.

Purpose

This package sets up fast, AI-friendly code navigation tools for large codebases:

• GNU Global - Symbol indexing and cross-referencing (10-100x faster than grep)
• Cscope - Call graph analysis (who calls what)
• LSP - Language Server Protocol for AST-accurate analysis
• Query Scripts - Simple interfaces for Claude to use these tools

Target User

Developers who want Claude to efficiently analyze large codebases using pre-indexed databases instead of slow grep/find operations.

Setup Flow (For Claude Agents)

When a user points you to this README and asks to set up static analysis, follow this workflow:

Phase 1: Environment Detection

1. Check OS and package manager
2. Detect existing tools: global --version, cscope --version, clangd --version
3. Report what's installed and what's missing

Phase 2: Tool Installation

For each missing tool, guide user through installation:

• GNU Global: Run install/install-global.sh
• Cscope: Run install/install-cscope.sh
• LSP (clangd): Run install/install-lsp.sh (optional)

Wait for user confirmation after each installation completes.

Phase 3: Repository Selection

Ask user:

• Which repositories to index? (can be multiple)
• Full paths to each repository
• Confirm repositories exist and are readable

Phase 4: Database Generation

For each repository:

1. Run scripts/setup-static-analysis.sh <repo-path>
2. Report database sizes and generation time
3. Verify databases created: GTAGS, GRTAGS, GPATH, cscope.out

Phase 5: Git Configuration

For each repository:

1. Read templates/git-exclude.template
2. Append patterns to <repo>/.git/info/exclude
3. Verify static analysis databases won't be committed

Phase 6: Claude Configuration

Option A: Repository-Level (Recommended)

1. Check if <repo>/CLAUDE.md exists
2. If exists: Append static analysis section from templates/CLAUDE.md.template
3. If not exists: Create from template
4. Copy templates/STATIC_ANALYSIS_TOOLS.md to <repo>/docs/ or <repo>/.claude/

Option B: User-Level (Global)

1. Check if ~/.claude/CLAUDE.md exists
2. Append or create with template
3. Place STATIC_ANALYSIS_TOOLS.md in ~/.claude/

Ask user which approach they prefer.

Phase 7: Query Script Deployment

For each repository:

1. Copy scripts/static-analysis-query.sh to <repo>/.static-analysis-query.sh
2. Make executable: chmod +x <repo>/.static-analysis-query.sh
3. Add to git exclude (should already be covered by pattern .*)

Phase 8: Verification

Run verification tests:

1. Execute scripts/verify-setup.sh <repo-path>
2. Report results for each tool
3. Ask user to try a manual query

Phase 9: Usage Guide

Show user how to use the tools:

# Quick query (comprehensive)
cd <repo>
./.static-analysis-query.sh function_name

# Individual queries
global -x function_name          # Where defined
global -rx function_name         # Where called
cscope -d -L -3 function_name    # Who calls this
cscope -d -L -2 function_name    # What this calls

Explain that Claude agents will automatically use these tools when available.

Files in This Package

Installation Scripts (install/)

• install-tools.sh - Main orchestrator (calls other scripts)
• install-global.sh - GNU Global installation
• install-cscope.sh - Cscope installation
• install-lsp.sh - clangd installation

Database Scripts (scripts/)

• setup-static-analysis.sh - Generate databases for a repository
• static-analysis-query.sh - Unified query interface (template)
• verify-setup.sh - Test suite for validating setup

Templates (templates/)

• CLAUDE.md.template - Claude configuration with static analysis
• git-exclude.template - Git exclude patterns
• STATIC_ANALYSIS_TOOLS.md - Comprehensive tool documentation

Configuration (config/)

• settings.json.snippet - Optional Claude Code settings

Requirements

• OS: Linux (Ubuntu/Debian tested), macOS (with Homebrew)
• Shell: bash or zsh
• Git: For repository management
• Build tools: gcc, make (for building Global/Cscope if needed)

Maintenance

After major code changes:

cd <repo>
gtags -iv              # Incremental update
cscope -b -q -k        # Rebuild cscope

Or regenerate completely:

cd <repo>
~/.../setup-static-analysis.sh $(pwd)

---

Version: 1.0
Last Updated: 2026-08-03
License: MIT
Author: AMD Debugger Team