🦅 Hawkeye

Architectural intelligence for AI coding agents. One call gives your AI editor full context about a file — dependencies, blast radius, cycles, health — before it writes a single line.

The Problem

AI coding agents edit files without knowing the architecture. They:

• Break imports they didn't know existed
• Refactor classes used by 20 other modules
• Create circular dependencies
• Miss that a "simple change" cascades through 34 files

Hawkeye fixes this. It gives the AI the same architectural awareness a senior engineer has — in one deterministic, token-efficient JSON call.

Setup for AI Editors (MCP)

Hawkeye exposes 12 tools via Model Context Protocol. Install and configure in under 60 seconds:

1. Install

pip install hawkeye-analyzer

This installs everything: MCP server, Python/JavaScript/TypeScript analysis.

2. Add to your editor's MCP config

Antigravity / Gemini (~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "hawkeye": {
      "command": "hawkeye-mcp",
      "args": []
    }
  }
}

No --project needed — the agent calls hawkeye_analyze(project_path) dynamically with whatever workspace is active. Works for any project without config changes.

Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "hawkeye": {
      "command": "hawkeye-mcp",
      "args": []
    }
  }
}

Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hawkeye": {
      "command": "hawkeye-mcp",
      "args": ["--project", "/path/to/your/project"]
    }
  }
}

Cursor (.cursor/mcp.json in project root):

{
  "mcpServers": {
    "hawkeye": {
      "command": "hawkeye-mcp",
      "args": ["--project", "."]
    }
  }
}

Windsurf / Other MCP clients — same pattern. The server uses stdio transport.

Two modes: Pass --project /path to pre-analyze on startup (faster first query, locked to one project). Or pass no args and call hawkeye_analyze() on demand (works for any project, ~5s on first use). Multi-project caching is supported — switching projects doesn't require re-analysis.

3. Done

The AI editor now has access to 12 architectural intelligence tools. The most important one:

hawkeye_file_context("src/core/engine.py")

Returns everything the agent needs in one call (v0.6 compact format):

{
  "file": "core/engine.py",
  "loc": 340,
  "arch_role": "orchestrator",
  "health": "elevated",
  "cc": 36,
  "cog": 66,
  "ca": 2,
  "ce": 6,
  "I": 0.75,
  "deps": [
    "core/scanner.py",
    "core/analyzer.py",
    "core/graph.py"
  ],
  "dependents": [
    "cli.py",
    "server/mcp.py"
  ],
  "transitive_impact": 12,
  "edit_cost": {
    "files": 2,
    "cascade": 12,
    "tokens": 4280,
    "risk": "medium"
  },
  "insights": ["high_cyclomatic", "wide_transitive_reach"],
  "risk": "hub",
  "churn": "hot"
}

Design Principles

Hawkeye is built specifically for AI agent consumption:

Token Budget

Compare this to dumping raw import statements or grep results — Hawkeye gives the AI structured, pre-analyzed architectural data at a fraction of the token cost.

MCP Tools Reference

After calling hawkeye_analyze(project_path) once, all other tools are available:

Recommended Agent Workflow

1. hawkeye_analyze("/path/to/project")     — scan once on startup
2. hawkeye_file_context("file_to_edit.py") — before every edit
3. hawkeye_impact("file.py", "ClassName")  — before refactoring a symbol
4. hawkeye_cycles()                         — after creating new imports

Interpreting the Output

Insight Codes

Machine-readable labels derived deterministically from metrics. No natural language, no ambiguity:

Risk Profiles

Single-token classification of a module's structural role:

Health Labels

Five-level composite assessment (monotonic severity):

Note: health reflects effective health, adjusted for architectural role. Core modules cap at elevated (complexity is structural, not pathological). Raw metric-based health is available as raw_health in full mode.

CLI for Humans

Hawkeye also works as a standalone CLI:

pip install hawkeye-analyzer

# Full project analysis
hawkeye analyze ./myproject

# Interactive dependency graph in your browser
hawkeye show ./myproject

# Metrics deep-dive with per-function complexity
hawkeye metrics ./myproject --sort health --functions

# Symbol blast radius
hawkeye impact ./myproject src/engine.py -s Engine

# CI gate — fails on rule violations or import cycles
hawkeye check ./myproject --no-cycles

# AI-ready JSON context
hawkeye context ./myproject src/engine.py

# Git hotspots — complexity × churn
hawkeye hotspots ./myproject
hawkeye hotspots ./myproject --days 30 --limit 10

Output Formats

Configuration

Place a hawkeye.toml in your project root. Hawkeye auto-discovers it by walking up from the project directory.

.hawkeyeignore

For quick exclusions without editing TOML, create a .hawkeyeignore file in your project root:

# Tests and fixtures
*.tests.*
*.test_*
conftest

# Generated code
*.generated.*
*.pb2

Each non-blank, non-comment line is treated as a glob exclude pattern. Patterns are merged with any exclude_patterns from hawkeye.toml.

Minimal hawkeye.toml

[project]
name = "MyProject"

[scan]
exclude_patterns = ["*.tests.*", "*.test_*"]  # Keep test modules out of coupling analysis

Architecture Rules

# Enforce layered architecture
[rules.layers]
order = ["models", "services", "api", "cli"]
direction = "downward"

# Block specific imports
[[rules.forbidden]]
from = "api.*"
to = ["cli.*", "scripts.*"]

# Module groups must be independent (transitive — catches indirect paths too)
[[rules.independence]]
modules = ["auth", "billing", "notifications"]

# Only auth may import secrets
[[rules.protected]]
modules = ["core.secrets", "core.tokens"]
allowed_importers = ["auth.*"]

# Sibling services must not form cycles
[[rules.acyclic_siblings]]
ancestor = "services"

Framework Detection

Hawkeye automatically detects framework entry points — symbols decorated with @app.get(), @pytest.fixture, @celery_app.task, etc. These are excluded from unused symbol detection to eliminate false positives.

The built-in registry covers pytest, FastAPI, Flask, Django, Celery, Click, SQLAlchemy, and standard library decorators. Add project-specific patterns in your TOML config:

[scan.framework_decorators]
add = ["my_framework.endpoint", "register_handler"]  # merged with defaults
# replace = true    # set true to fully override defaults

Threshold Tuning

By default, Hawkeye uses adaptive percentile thresholds that calibrate to each project's complexity distribution. A module is only critical if it's in the top 5% of its project — not by arbitrary universal constants.

To disable percentiles and use fixed thresholds:

[thresholds]
use_percentiles = false   # Fall back to static thresholds
profile = "strict"         # "default", "strict", or "relaxed"
cc_critical = 40           # Override individual values
loc_critical = 600

Percentile floors prevent tiny projects from having meaningless criticals:

[thresholds]
cc_floor_critical = 30    # Minimum CC for "critical" even if P95 is lower
cc_floor_high = 15
cog_floor_critical = 30
cog_floor_high = 15

Note: When use_percentiles = true (default), these static values serve as fallback floors. The actual thresholds are computed from your project's CC/Cog distribution.

How It Works

Source files (Py/JS/TS) → Language-specific parsing → Import resolution → Dependency graph
                                                                      ↓
                    Symbol registry ← Symbol extraction     Graph algorithms
                         ↓                                        ↓
                  Symbol-level impact              Coupling metrics (Ca/Ce/I/A/D)
                  Hotspot detection                Complexity metrics (CC/Cog)
                  Dead code detection (fw-aware)   Cycle detection (Tarjan's SCC)
                                                   Import classification
                                                   Health classification
                                                   Insight derivation
                                                         ↓
                                              Deterministic JSON output

• Single AST pass per file — no re-parsing, no multiple traversals
• Tarjan's SCC for cycle detection — O(V+E), mathematically optimal
• Import classification — distinguishes runtime, TYPE_CHECKING, and deferred imports for intelligent cycle triage
• BFS reachability for transitive impact — cached per session
• Brandes' algorithm for betweenness centrality — O(VE), identifies architectural bridges
• Robert C. Martin's metrics — Ca, Ce, Instability, Abstractness, Distance
• SonarSource spec for cognitive complexity — nesting-weighted, not just branch counting
• LOC = code lines only — blank lines and # comment lines are excluded. A file with 1,800 raw lines may report ~1,400 LOC. This is the more useful metric for complexity assessment

Data Storage

All analysis data lives in RAM only. There is no database, no cache file, no .hawkeye/ directory. The MCP server holds the dependency graph, metrics, and symbol registry in-process for the duration of the session. When the server stops (editor closes), all data is discarded. Next session re-analyzes from scratch — which takes ~5 seconds for a 300-module project.

Performance

Project Structure

src/hawkeye/
├── engine.py           # Central orchestrator (CC=36, 261 LOC)
├── context.py          # AI context builder (stateless, pure functions)
├── config.py           # TOML config with walk-up discovery
├── cli/                # CLI subpackage
│   ├── __init__.py     # Parser + main() entry point
│   ├── commands.py     # 7 command handlers
│   ├── _helpers.py     # Engine creation + UTF-8 setup
│   └── __main__.py     # python -m support
├── core/
│   ├── models.py       # Leaf: ModuleInfo + utilities (I=0.125)
│   ├── scanner.py      # File discovery
│   ├── analyzer.py     # AST imports + symbols + complexity
│   ├── graph.py        # Directed graph + algorithms
│   ├── metrics.py      # Ca/Ce/I/A/D + health scoring
│   ├── cycles.py       # Tarjan's SCC + severity + kind
│   ├── rules.py        # 5 architecture rule types
│   ├── insights.py     # Deterministic insight derivation
│   ├── git_history.py  # Git churn, hotspots, rename tracking
│   └── symbols.py      # Cross-file symbol resolution
├── languages/          # Multi-language support
│   ├── base.py         # Adapter protocol
│   ├── registry.py     # Adapter factory
│   ├── python/         # Python adapter
│   ├── javascript/     # JavaScript adapter
│   ├── typescript/     # TypeScript adapter
│   └── shared/         # Tree-sitter JS/TS parsing engine
├── server/
│   └── mcp.py          # 12 MCP tools
└── visualizer/
    ├── html_renderer.py    # Interactive D3.js graph
    ├── dot_renderer.py     # Graphviz DOT
    ├── text_renderer.py    # Terminal tables
    └── json_renderer.py    # Structured JSON

62 modules, 10,302 LOC, 0 import cycles. 350 tests across 12 test files. Python 3.10+.

License

MIT — see LICENSE for details.