🎮 gdep — Game Codebase Analysis Tool

Analyze game client codebases directly from your terminal and AI Agent.

Supports Unity · Cocos2d-x · Unreal Engine 5 · .NET C# · Generic C++.

GitHub · MCP Setup · CI/CD Integration

Read this in other languages: 한국어 · 日本語 · 简体中文 · 繁體中文

📦 Installation

Prerequisites

Item	Version	Purpose
Python	3.11+	CLI · MCP server
.NET Runtime	8.0+	C# / Unity project analysis

pip install gdep

After installation, the gdep command is available globally.

For the MCP server (Claude Desktop / Cursor integration), also install:
npm install -g gdep-mcp

🚀 Quick Start

1. Detect Project

gdep detect {path}

2. Analyze Structure

gdep scan {path} --circular --top 15

┌─ scan results ───────────────────────────────────────┐
│ Files: 312  |  Classes: 847  |  Dead Code: 12        │
└──────────────────────────────────────────────────────┘
── Top Classes by Coupling
  1  CombatManager   23
  2  DataManager     18
── Circular Dependencies
  ↻ CombatCore → CombatUnit → CombatCore

3. Initialize AI Agent Context

# Creates .gdep/AGENTS.md — auto-read by Claude / Cursor / Gemini
gdep init {path}

🎯 Command Reference

Command	Summary	When to Use
`detect`	Auto-detect engine type	Before first analysis
`scan`	Coupling · Cycles · Dead code	Understand structure, before refactor
`describe`	Class detail + full inheritance chain + Blueprint impl + AI summary	Unfamiliar class, code review
`flow`	Method call chain trace (C++→BP boundary)	Bug tracing, flow analysis
`impact`	Change impact reverse-trace	Safety check before refactoring
`method-impact`	Reverse-trace callers of a specific method	Before modifying a method, find all call sites
`path`	Shortest call path between two methods (BFS, C#/Unity only)	Trace how A connects to B
`lint`	Game-specific anti-pattern scan	Quality check before PR
`graph`	Dependency graph export	Documentation, visualization
`diff`	Dependency diff before/after git commit	PR review, CI gate
`init`	Create AI Agent context	First AI coding assistant setup
`context`	Print project context	Copy-paste to AI chat
`hints`	Manage singleton hints	Improve flow accuracy
`config`	LLM configuration	Before using AI summary features

🤝 AI Agent + MCP Integration

gdep provides an MCP server for direct use in Claude Desktop, Cursor, and other MCP-compatible AI agents.

Quick Install via npm (Recommended)

npm install -g gdep-mcp

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "gdep": {
      "command": "gdep-mcp",
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

MCP Tools (30)

Tool	Scenario
`get_project_context`	Call first — full project overview
`wiki_search`	Call before any analysis — keyword search over previously analyzed classes/assets (FTS5 BM25). Instant if cached
`wiki_list`	List all wiki nodes with staleness status
`wiki_get`	Read full cached analysis of a specific wiki node
`wiki_save_conversation`	Save agent conversation summary to wiki — persists session context, decisions, and findings across sessions. Creates `discussed_in` edges to referenced classes
`analyze_impact_and_risk`	Safety check before modifying a class or method (`method_name=` for method-level callers)
`trace_gameplay_flow`	Trace how a feature works (C++→BP). `summary=True` for compact output
`inspect_architectural_health`	Full tech debt diagnosis
`explore_class_semantics`	Understand an unfamiliar class. Default `compact=True` keeps output AI-friendly; `include_source=True` appends source code
`explain_method_logic`	Internal control flow of a single method (Guard/Branch/Loop/Always). `include_source=True` appends method body
`suggest_test_scope`	Which test files to run after modifying a class
`suggest_lint_fixes`	Lint issues with code fix suggestions (dry-run)
`summarize_project_diff`	Architecture-level summary of a git diff
`get_architecture_advice`	Full project diagnosis + LLM-powered advice
`find_method_callers`	Reverse call graph — who calls this method
`find_call_path`	Shortest call path between two methods (A → B, C#/Unity only)
`find_class_hierarchy`	Full inheritance tree — ancestors (parent chain) + descendants (subclass tree)
`read_class_source`	Return actual source code of a class or a specific method. `method_name=` for only that method's body
`find_unused_assets`	Unreferenced assets — Unity GUID scan / UE5 binary path reference scan
`query_project_api`	Search project API by class/method/property name with relevance scoring
`detect_patterns`	Detect design patterns in the codebase (Singleton, Subsystem, GAS, Component, etc.)
`execute_gdep_cli`	Raw access to all CLI features
`find_unity_event_bindings`	Unity Inspector event bindings
`analyze_unity_animator`	Unity Animator state machine
`analyze_ue5_gas`	UE5 GAS system full analysis — confidence header + IS-A asset role breakdown
`analyze_ue5_behavior_tree`	UE5 BehaviorTree structure
`analyze_ue5_state_tree`	UE5 StateTree structure
`analyze_ue5_animation`	UE5 ABP + Montage analysis
`analyze_ue5_blueprint_mapping`	C++ class → Blueprint impl mapping — confidence header

🎮 Supported Engines

Engine	Class Analysis	Flow Analysis	Back-refs	Specialized
Unity (C#)	✅	✅	✅ Prefab/Scene	UnityEvent, Animator
Unreal Engine 5	✅ UCLASS/USTRUCT/UENUM	✅ C++→BP	✅ Blueprint/Map	GAS, BP mapping, BT/ST, ABP/Montage
Cocos2d-x (C++)	✅	✅	-	-
.NET (C#)	✅	✅	-	-
Generic C++	✅	✅	-	-

📋 Lint Rules

Rule ID	Engine	Description
`UNI-PERF-001`	Unity	GetComponent/Find in Update
`UNI-PERF-002`	Unity	new/Instantiate allocation in Update
`UNI-ASYNC-001`	Unity	Coroutine while(true) without yield
`UNI-ASYNC-002`	Unity	FindObjectOfType/Resources.Load inside Coroutine
`UE5-PERF-001`	UE5	SpawnActor/LoadObject in Tick
`UE5-PERF-002`	UE5	Synchronous LoadObject in BeginPlay
`UE5-BASE-001`	UE5	Missing Super:: call
`UE5-GAS-001`	UE5	Missing CommitAbility() in ActivateAbility()
`UE5-GAS-002`	UE5	Expensive queries in GAS Ability
`UE5-GAS-003`	UE5	Excessive BlueprintCallable (>10)
`UE5-GAS-004`	UE5	Missing const on BlueprintPure method
`UE5-NET-001`	UE5	Replicated property without callback
`UE5-BP-001`	UE5	Blueprint references a C++ class not found in source
`UE5-BP-002`	UE5	Blueprint K2 override references a deleted/changed C++ function
`UNI-ASSET-001`	Unity	Prefab script reference broken (.meta GUID mismatch)
`GEN-ARCH-001`	Common	Circular dependency

⚙️ C# Parser (`gdep.dll`)

The C# parser ships as an OS-agnostic single DLL, running identically on Windows · macOS · Linux.

Detection priority: $GDEP_DLL env → publish_dll/gdep.dll → publish/gdep.dll → legacy binary

📚 More

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3.11
Topic
- Software Development :: Libraries

Release files for gdep 0.2.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gdep 0.2.10
File	Size	Uploaded
gdep-0.2.10.tar.gz	4.4 MB	Apr 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gdep 0.2.10
File	Interpreter	ABI	Platform	Reset
gdep-0.2.10-py3-none-any.whl 4.5 MB Apr 12, 2026	Python 3	none	any	Details

Total release size: 8.9 MB

Release files / gdep-0.2.10.tar.gz

Download URL	gdep-0.2.10.tar.gz
Size	4.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`06a9d09ac72fccd99f12d70515a62413f97b4d1e74c1c2b862717451bda6fc02`
BLAKE2b-256 checksum How to use checksums	`89eb44593ebbd577206b86c7e248bef76087eca9a90828a9b3f8922a3ece6446`
Upload date	Apr 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool
Publishing commit: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/tree/c09f94ac2c1435ce56cb8a3cb5b190a6bcff0e98

Workflow

Publishing configuration: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/blob/c09f94ac2c1435ce56cb8a3cb5b190a6bcff0e98/.github/workflows/release.yml
Publishing logs: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/actions/runs/24298809933/attempts/1

Artifact

Subject: gdep-0.2.10.tar.gz
SHA-256 checksum: 06a9d09ac72fccd99f12d70515a62413f97b4d1e74c1c2b862717451bda6fc02 Verifying attestations

Release files / gdep-0.2.10-py3-none-any.whl

Download URL	gdep-0.2.10-py3-none-any.whl
Size	4.5 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`5a645fe9a1b2d9322a589936de57309f7b470a2fb7e21cc9fb03b59ad414ce20`
BLAKE2b-256 checksum How to use checksums	`e4750bdc023ea4a34d406cb2e499a7c22a08324cd03f2239f0c53157362e8314`
Upload date	Apr 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool
Publishing commit: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/tree/c09f94ac2c1435ce56cb8a3cb5b190a6bcff0e98

Workflow

Publishing configuration: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/blob/c09f94ac2c1435ce56cb8a3cb5b190a6bcff0e98/.github/workflows/release.yml
Publishing logs: github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool/actions/runs/24298809933/attempts/1

Artifact

Subject: gdep-0.2.10-py3-none-any.whl
SHA-256 checksum: 5a645fe9a1b2d9322a589936de57309f7b470a2fb7e21cc9fb03b59ad414ce20 Verifying attestations