codegraph-gen 0.2.0__tar.gz

codegraph_gen-0.2.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.3
+Name: codegraph-gen
+Version: 0.2.0
+Summary: AST-based codebase knowledge graph generator in Markdown
+Keywords: knowledge-graph,ast,codebase,markdown,tree-sitter,visualization,static-analysis,ai-agent,obsidian
+Author: twn39
+Author-email: twn39 <twn39@163.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: networkx>=3.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: tree-sitter-python
+Requires-Dist: tree-sitter-javascript
+Requires-Dist: tree-sitter-typescript
+Requires-Dist: tree-sitter-go
+Requires-Dist: tree-sitter-rust
+Requires-Dist: tree-sitter-swift
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tree-sitter-c>=0.24.2
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Requires-Dist: tree-sitter-kotlin>=1.1.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/twn39/codegraph
+Project-URL: Repository, https://github.com/twn39/codegraph
+Project-URL: Issues, https://github.com/twn39/codegraph/issues
+Description-Content-Type: text/markdown
+
+# codegraph
+
+`codegraph` 是一个面向 AI Agent（如 Antigravity、Codex、Claude Code 等）的静态代码知识图谱生成工具。它能够静态解析多语言 codebase，通过社区发现算法自动进行组件聚类，并导出为由标准 Markdown 文件组成的关联图谱库（Obsidian-like vault），极大地辅助 AI Agent 在本地进行精准的架构理解、逻辑导航与深度洞察分析。
+
+与基于图形化 Canvas 渲染的知识图谱不同，`codegraph` 采用全 Markdown 的扁平结构存储。它专门为 LLM 设计，摒弃了昂贵且复杂的数据库依赖，让 AI Agent 可以通过标准文件读取与路径导航（Relative Links）轻松周游整个代码库。
+
+---
+
+## 🚀 核心特性
+
+- **多语言 AST 解析**：基于 `tree-sitter`，原生支持 **Python, JavaScript, TypeScript, Go, Rust, Swift**。
+- **语义边解析与绑定**：静态解析跨文件的函数/方法调用（`calls`）、类型继承/接口实现（`inherits`/`implements`）以及文件导入关系（`imports`）。
+- **逻辑组件自动聚类**：利用贪心模块度社区发现算法（Louvain Modularity Clustering）将紧密耦合的文件和符号自动聚类为 **Component（逻辑组件）**，并根据组件核心节点智能命名。
+- **架构脆弱性分析**：自动识别 **God Nodes（度数最高的核心抽象）**，并静态检测文件级别的 **循环导入依赖（Circular Imports）**。
+- **Agent 友好交互协议**：生成离线 Agent 提示词文件 `AGENT_PROMPT.md` 与规则文件 `AGENTS.md`，实现零 API 成本的 Agent 驱动型架构洞察分析。
+
+---
+
+## 📦 架构概览
+
+```mermaid
+graph TD
+    A[工作区源码 Workspace] --> B[detect: 语言识别与过滤]
+    B --> C[parser: Tree-Sitter AST 符号提取]
+    C --> D[builder: NetworkX 语义图组装与绑定]
+    D --> E[cluster: 社区模块度聚类命名]
+    E --> F[analyze: 上帝节点与循环导入分析]
+    F --> G[export: 导出至 .codegraph/]
+    G --> H[AGENT_PROMPT.md / AGENTS.md / README.md / nodes / components]
+```
+
+---
+
+## 🛠️ 安装指南
+
+推荐使用 [uv](https://github.com/astral-sh/uv) 管理项目依赖与虚拟环境：
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd codegraph
+
+# 同步依赖并激活虚拟环境
+uv sync
+source .venv/bin/activate
+
+# 全局安装 (推荐)
+uv tool install --force --no-cache .
+```
+
+### 2. 注入 AI Agent 斜杠命令集成
+
+`codegraph` 支持一键将 `/codegraph` 自定义斜杠命令注册到您的 AI Agent（如 Codex 或 Antigravity）的全局配置中：
+
+```bash
+# 为 Codex / Antigravity 注入 /codegraph 全局斜杠命令
+codegraph install --platform codex
+```
+
+注册完成后，在对应的 Agent 终端中，您只需输入 `/codegraph` 即可全自动运行整个图谱的提取、分析与回写流程。
+
+---
+
+## 📖 使用方法
+
+### 1. 构建代码图谱
+
+在项目根目录下运行 `codegraph build`，默认会扫描当前文件夹并将图谱输出至 `.codegraph/` 目录下：
+
+```bash
+# 扫描当前目录并生成图谱
+codegraph build .
+
+# 指定自定义输出目录
+codegraph build . --output my_vault/
+
+# 排除指定文件夹
+codegraph build . --exclude extra_folder/ --exclude docs/
+```
+
+### 2. 导出 vault 目录结构
+
+输出的 `.codegraph/` 是一个自包含的 Markdown 知识图谱数据库，结构如下：
+
+```
+.codegraph/
+├── README.md               # 图谱主索引，包含统计、Mermaid 组件依赖图、上帝节点、循环依赖及 AI 架构洞察
+├── AGENT_PROMPT.md         # 供外部 AI Agent 读取的架构分析提示词模版
+├── AGENTS.md               # 外部 AI Agent 协同工作规则与导航指南
+├── components/             # 聚类生成的逻辑组件详情（如 Component_3_BaseParser_.md）
+└── nodes/                  # 所有物理文件和符号的详情（包含定义签名、双向调用链与 Mermaid 拓扑）
+```
+
+---
+
+## 🤖 与 AI Agent（Codex / Antigravity / Claude Code）协同分析
+
+`codegraph` 的核心设计思想是**离线构建，Agent 分析**。这避免了在 CLI 中直接硬编码大模型 API，降低了使用成本，并充分利用了你当前对话中功能更强、带有上下文读取能力的外部 Agent。
+
+### 步骤 1：生成本地图谱
+
+运行以下命令，为你的 codebase 生成静态图谱底座：
+```bash
+codegraph build .
+```
+
+### 步骤 2：在 Agent 中一键触发分析
+
+打开你的 AI Agent（如 Codex、Antigravity 或 Claude Code 终端），直接向它发送以下指令：
+
+> 💡 **分析指令**：
+> `请读取并遵循 .codegraph/AGENT_PROMPT.md 中的提示要求，对本项目进行深度架构分析，然后将中文分析报告写入 .codegraph/README.md 文件的 “AI 架构深度洞察” 章节中。`
+
+Agent 将自动利用其文件读写能力：
+1. 读取 `.codegraph/AGENT_PROMPT.md` 获取元数据和 Mermaid 关系。
+2. 进行推理，并在 `.codegraph/README.md` 的 `## AI 架构深度洞察` 章节中生成专业的中文架构报告。
+
+### 步骤 3：日常问答与逻辑导航
+
+AI Agent 能够非常聪明地利用该图谱来导航庞大的 codebase。当你想问代码结构时，指示它利用图谱即可：
+- *“哪个组件依赖了 BaseParser？”* -> Agent 会读取 `components/` 下的组件文件。
+- *“调用这个函数的入口在什么地方？”* -> Agent 会查看 `nodes/` 下对应节点文件的 `Incoming Calls`。
+
+---
+
+## 📜 规则设置（自动感知）
+
+如需让 AI Agent 在进入仓库时自动使用 `.codegraph`，你可以在根目录下创建 `CLAUDE.md` 或在 `README.md` 中引用 `.codegraph/AGENTS.md` 中的规则。
+例如在 `CLAUDE.md` 中写入：
+```markdown
+- Before answering architecture or codebase questions, read .codegraph/README.md for god nodes and community structure.
+- Navigate .codegraph/components/ and .codegraph/nodes/ instead of reading raw code files directly.
+- After modifying code files, run `codegraph build .` to keep the graph current.
+```

codegraph_gen-0.2.0/README.md

@@ -0,0 +1,134 @@
+# codegraph
+
+`codegraph` 是一个面向 AI Agent（如 Antigravity、Codex、Claude Code 等）的静态代码知识图谱生成工具。它能够静态解析多语言 codebase，通过社区发现算法自动进行组件聚类，并导出为由标准 Markdown 文件组成的关联图谱库（Obsidian-like vault），极大地辅助 AI Agent 在本地进行精准的架构理解、逻辑导航与深度洞察分析。
+
+与基于图形化 Canvas 渲染的知识图谱不同，`codegraph` 采用全 Markdown 的扁平结构存储。它专门为 LLM 设计，摒弃了昂贵且复杂的数据库依赖，让 AI Agent 可以通过标准文件读取与路径导航（Relative Links）轻松周游整个代码库。
+
+---
+
+## 🚀 核心特性
+
+- **多语言 AST 解析**：基于 `tree-sitter`，原生支持 **Python, JavaScript, TypeScript, Go, Rust, Swift**。
+- **语义边解析与绑定**：静态解析跨文件的函数/方法调用（`calls`）、类型继承/接口实现（`inherits`/`implements`）以及文件导入关系（`imports`）。
+- **逻辑组件自动聚类**：利用贪心模块度社区发现算法（Louvain Modularity Clustering）将紧密耦合的文件和符号自动聚类为 **Component（逻辑组件）**，并根据组件核心节点智能命名。
+- **架构脆弱性分析**：自动识别 **God Nodes（度数最高的核心抽象）**，并静态检测文件级别的 **循环导入依赖（Circular Imports）**。
+- **Agent 友好交互协议**：生成离线 Agent 提示词文件 `AGENT_PROMPT.md` 与规则文件 `AGENTS.md`，实现零 API 成本的 Agent 驱动型架构洞察分析。
+
+---
+
+## 📦 架构概览
+
+```mermaid
+graph TD
+    A[工作区源码 Workspace] --> B[detect: 语言识别与过滤]
+    B --> C[parser: Tree-Sitter AST 符号提取]
+    C --> D[builder: NetworkX 语义图组装与绑定]
+    D --> E[cluster: 社区模块度聚类命名]
+    E --> F[analyze: 上帝节点与循环导入分析]
+    F --> G[export: 导出至 .codegraph/]
+    G --> H[AGENT_PROMPT.md / AGENTS.md / README.md / nodes / components]
+```
+
+---
+
+## 🛠️ 安装指南
+
+推荐使用 [uv](https://github.com/astral-sh/uv) 管理项目依赖与虚拟环境：
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd codegraph
+
+# 同步依赖并激活虚拟环境
+uv sync
+source .venv/bin/activate
+
+# 全局安装 (推荐)
+uv tool install --force --no-cache .
+```
+
+### 2. 注入 AI Agent 斜杠命令集成
+
+`codegraph` 支持一键将 `/codegraph` 自定义斜杠命令注册到您的 AI Agent（如 Codex 或 Antigravity）的全局配置中：
+
+```bash
+# 为 Codex / Antigravity 注入 /codegraph 全局斜杠命令
+codegraph install --platform codex
+```
+
+注册完成后，在对应的 Agent 终端中，您只需输入 `/codegraph` 即可全自动运行整个图谱的提取、分析与回写流程。
+
+---
+
+## 📖 使用方法
+
+### 1. 构建代码图谱
+
+在项目根目录下运行 `codegraph build`，默认会扫描当前文件夹并将图谱输出至 `.codegraph/` 目录下：
+
+```bash
+# 扫描当前目录并生成图谱
+codegraph build .
+
+# 指定自定义输出目录
+codegraph build . --output my_vault/
+
+# 排除指定文件夹
+codegraph build . --exclude extra_folder/ --exclude docs/
+```
+
+### 2. 导出 vault 目录结构
+
+输出的 `.codegraph/` 是一个自包含的 Markdown 知识图谱数据库，结构如下：
+
+```
+.codegraph/
+├── README.md               # 图谱主索引，包含统计、Mermaid 组件依赖图、上帝节点、循环依赖及 AI 架构洞察
+├── AGENT_PROMPT.md         # 供外部 AI Agent 读取的架构分析提示词模版
+├── AGENTS.md               # 外部 AI Agent 协同工作规则与导航指南
+├── components/             # 聚类生成的逻辑组件详情（如 Component_3_BaseParser_.md）
+└── nodes/                  # 所有物理文件和符号的详情（包含定义签名、双向调用链与 Mermaid 拓扑）
+```
+
+---
+
+## 🤖 与 AI Agent（Codex / Antigravity / Claude Code）协同分析
+
+`codegraph` 的核心设计思想是**离线构建，Agent 分析**。这避免了在 CLI 中直接硬编码大模型 API，降低了使用成本，并充分利用了你当前对话中功能更强、带有上下文读取能力的外部 Agent。
+
+### 步骤 1：生成本地图谱
+
+运行以下命令，为你的 codebase 生成静态图谱底座：
+```bash
+codegraph build .
+```
+
+### 步骤 2：在 Agent 中一键触发分析
+
+打开你的 AI Agent（如 Codex、Antigravity 或 Claude Code 终端），直接向它发送以下指令：
+
+> 💡 **分析指令**：
+> `请读取并遵循 .codegraph/AGENT_PROMPT.md 中的提示要求，对本项目进行深度架构分析，然后将中文分析报告写入 .codegraph/README.md 文件的 “AI 架构深度洞察” 章节中。`
+
+Agent 将自动利用其文件读写能力：
+1. 读取 `.codegraph/AGENT_PROMPT.md` 获取元数据和 Mermaid 关系。
+2. 进行推理，并在 `.codegraph/README.md` 的 `## AI 架构深度洞察` 章节中生成专业的中文架构报告。
+
+### 步骤 3：日常问答与逻辑导航
+
+AI Agent 能够非常聪明地利用该图谱来导航庞大的 codebase。当你想问代码结构时，指示它利用图谱即可：
+- *“哪个组件依赖了 BaseParser？”* -> Agent 会读取 `components/` 下的组件文件。
+- *“调用这个函数的入口在什么地方？”* -> Agent 会查看 `nodes/` 下对应节点文件的 `Incoming Calls`。
+
+---
+
+## 📜 规则设置（自动感知）
+
+如需让 AI Agent 在进入仓库时自动使用 `.codegraph`，你可以在根目录下创建 `CLAUDE.md` 或在 `README.md` 中引用 `.codegraph/AGENTS.md` 中的规则。
+例如在 `CLAUDE.md` 中写入：
+```markdown
+- Before answering architecture or codebase questions, read .codegraph/README.md for god nodes and community structure.
+- Navigate .codegraph/components/ and .codegraph/nodes/ instead of reading raw code files directly.
+- After modifying code files, run `codegraph build .` to keep the graph current.
+```

codegraph_gen-0.2.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "codegraph-gen"
+version = "0.2.0"
+description = "AST-based codebase knowledge graph generator in Markdown"
+readme = "README.md"
+authors = [
+    { name = "twn39", email = "twn39@163.com" }
+]
+license = { text = "MIT" }
+keywords = [
+    "knowledge-graph",
+    "ast",
+    "codebase",
+    "markdown",
+    "tree-sitter",
+    "visualization",
+    "static-analysis",
+    "ai-agent",
+    "obsidian",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "networkx>=3.0",
+    "tree-sitter>=0.23.0",
+    "tree-sitter-python",
+    "tree-sitter-javascript",
+    "tree-sitter-typescript",
+    "tree-sitter-go",
+    "tree-sitter-rust",
+    "tree-sitter-swift",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "pydantic>=2.0.0",
+    "tree-sitter-c>=0.24.2",
+    "tree-sitter-cpp>=0.23.4",
+    "tree-sitter-kotlin>=1.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.15.16",
+    "ty>=0.0.44",
+]
+
+[project.urls]
+Homepage = "https://github.com/twn39/codegraph"
+Repository = "https://github.com/twn39/codegraph"
+Issues = "https://github.com/twn39/codegraph/issues"
+
+[project.scripts]
+codegraph = "codegraph_gen.__main__:main"
+codegraph-gen = "codegraph_gen.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

codegraph_gen-0.2.0/src/codegraph_gen/__main__.py

@@ -0,0 +1,311 @@
+from pathlib import Path
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    BarColumn,
+    MofNCompleteColumn,
+)
+
+from codegraph_gen.config import CodegraphConfig, DEFAULT_EXCLUSIONS
+
+console = Console()
+
+
+@click.group()
+def cli():
+    """codegraph - Build a Markdown knowledge graph of your codebase for AI analysis."""
+    pass
+
+
+@cli.command()
+@click.argument(
+    "src_dir",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=Path(".codegraph"),
+    help="Directory where the Markdown vault will be written.",
+)
+@click.option(
+    "--exclude",
+    "-e",
+    multiple=True,
+    type=str,
+    help="Additional folder names/patterns to exclude from scanning.",
+)
+@click.option(
+    "--parallel/--no-parallel",
+    default=True,
+    help="Enable/disable parallel parsing (using multiprocessing).",
+)
+@click.option(
+    "--workers",
+    "-w",
+    type=int,
+    default=None,
+    help="Number of worker processes to use for parallel parsing.",
+)
+@click.option(
+    "--cache/--no-cache",
+    default=True,
+    help="Enable/disable incremental parsing cache.",
+)
+def build(
+    src_dir: Path,
+    output: Path,
+    exclude: list[str],
+    parallel: bool,
+    workers: int | None,
+    cache: bool,
+):
+    """Parses the codebase in SRC_DIR and exports the Markdown graph vault."""
+    console.print("[bold blue]Starting codegraph analysis...[/bold blue]")
+
+    # 1. Prepare configuration
+    exclusions = set(DEFAULT_EXCLUSIONS)
+    if exclude:
+        exclusions.update(exclude)
+
+    import os
+
+    if not parallel:
+        max_workers = 1
+    elif workers is not None:
+        max_workers = workers
+    else:
+        max_workers = os.cpu_count() or 4
+
+    config = CodegraphConfig(
+        workspace_dir=src_dir.resolve(),
+        output_dir=output.resolve(),
+        exclusions=exclusions,
+        max_workers=max_workers,
+        use_cache=cache,
+    )
+
+    from codegraph_gen.engine import CodegraphEngine, PipelineStage
+
+    engine = CodegraphEngine(config)
+
+    # Run pipeline with click progress bar
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Initializing...", total=None)
+
+        def progress_callback(stage: PipelineStage, current_item, idx, total):
+            if stage == PipelineStage.DISCOVERING:
+                progress.update(task, description="Discovering source files...")
+            elif stage == PipelineStage.PARSING:
+                if total > 0:
+                    progress.update(task, total=total)
+                progress.update(
+                    task,
+                    description=f"Parsing {current_item.name if current_item else ''}",
+                    completed=idx,
+                )
+            elif stage == PipelineStage.BUILDING:
+                progress.update(task, description="Building reference graph...")
+            elif stage == PipelineStage.CLUSTERING:
+                progress.update(task, description="Clustering components...")
+            elif stage == PipelineStage.ANALYZING:
+                progress.update(task, description="Analyzing graph metrics...")
+            elif stage == PipelineStage.RENDERING:
+                progress.update(task, description="Rendering Markdown vault...")
+            elif stage == PipelineStage.WRITING:
+                progress.update(task, description="Writing files to disk...")
+            elif stage == PipelineStage.COMPLETED:
+                progress.update(task, description="Done!")
+
+        result = engine.run_pipeline(progress_callback=progress_callback)
+
+    G = result.graph
+    if G.number_of_nodes() == 0:
+        console.print("[bold yellow]Completed build, but graph is empty.[/bold yellow]")
+        return
+
+    files_count = len(result.files)
+    symbols_count = G.number_of_nodes() - files_count
+
+    console.print(f"Found [green]{files_count}[/green] supported files to analyze.")
+    console.print(
+        f"Assembled graph with [green]{G.number_of_nodes()}[/green] nodes and [green]{G.number_of_edges()}[/green] edges."
+    )
+    console.print(f"  - Files: {files_count}")
+    console.print(f"  - Symbols (Classes/Functions/Methods): {symbols_count}")
+
+    console.print(
+        "[bold green]Success! Codebase knowledge graph built successfully.[/bold green]"
+    )
+
+    table = Table(title="Logical Components Summary")
+    table.add_column("Component Name", style="cyan", no_wrap=True)
+    table.add_column("Cohesion (Density)", style="magenta")
+    table.add_column("Size (Nodes)", style="green")
+
+    for cid, members in result.components.items():
+        table.add_row(
+            result.component_names[cid],
+            str(result.cohesion_scores[cid]),
+            str(len(members)),
+        )
+
+    console.print(table)
+    console.print(
+        f"\nView the main graph entrypoint at: [bold underline]{config.absolute_output_dir}/README.md[/bold underline]"
+    )
+    console.print(
+        f"💡 [bold yellow]AI Insight Tip:[/bold yellow] Ask your AI Agent (e.g. Antigravity, Claude Code, Codex) to read [bold]{config.absolute_output_dir}/AGENT_PROMPT.md[/bold] and write the architectural report directly to [bold]{config.absolute_output_dir}/README.md[/bold].\n"
+    )
+
+
+@cli.command()
+@click.option(
+    "--platform",
+    "-p",
+    default="codex",
+    type=click.Choice(["codex", "antigravity"]),
+    help="The AI agent platform to integrate with.",
+)
+def install(platform: str):
+    """Installs the codegraph slash command into your AI Agent's global config."""
+    console.print(
+        f"[bold blue]Installing codegraph integration for {platform}...[/bold blue]"
+    )
+
+    # 1. Resolve skills directory based on target platform
+    if platform == "codex":
+        skills_dir = Path.home() / ".codex" / "skills" / "codegraph"
+    elif platform == "antigravity":
+        skills_dir = Path.home() / ".gemini" / "config" / "skills" / "codegraph"
+    else:
+        skills_dir = Path.home() / ".codex" / "skills" / "codegraph"
+
+    # 2. Skill file content
+    skill_content = """---
+name: codegraph
+description: "Build a Markdown codebase knowledge graph using codegraph, perform logical component clustering, analyze god nodes/circular dependencies, and write deep architectural insights to .codegraph/README.md."
+trigger: /codegraph
+---
+
+# /codegraph
+
+Build a codebase knowledge graph using `codegraph` for any folder, cluster symbols into logical components, detect god nodes and cycles, and perform a deep architectural analysis to write insights directly to the `.codegraph/README.md` vault.
+
+## Usage
+
+```
+/codegraph                                            # Run the full build & AI analysis pipeline on the current directory
+/codegraph <path>                                     # Run the pipeline on a specific subfolder/path
+/codegraph --exclude <pattern>                        # Build and exclude specific folders/patterns
+```
+
+## What You Must Do When Invoked
+
+If the user invoked `/codegraph` with no path, do not ask the user for a path. Instead of scanning the entire project root directory `.` (which may include non-essential scripts, docs, or huge subfolders), you MUST prioritize targeting the primary source directory (e.g. `src/`, `lib/`, `app/`) and test directory (e.g. `tests/`, `test/`).
+- If specific source or test folders are found, run the build targeting those folders, or build the root `.` but exclude other non-code/non-test directories (e.g., `docs/`, `scripts/`, `examples/`) using the `--exclude` flag to keep the graph focused on code and tests.
+- Otherwise, default to `.` (current directory).
+
+Follow these steps in order. Do not skip any steps.
+
+### Step 1 - Ensure codegraph is installed
+
+Check and locate the `codegraph` executable. To support virtual environments, resolve the binary in the following priority order:
+1. Local virtual environment: `.venv/bin/codegraph` or `venv/bin/codegraph`
+2. Global command: `codegraph` (installed globally or via uv tool)
+
+You can use this shell logic to resolve the executable:
+```bash
+if [ -f ".venv/bin/codegraph" ]; then
+    CODEGRAPH_BIN=".venv/bin/codegraph"
+elif [ -f "venv/bin/codegraph" ]; then
+    CODEGRAPH_BIN="venv/bin/codegraph"
+else
+    if ! command -v codegraph >/dev/null 2>&1; then
+        uv tool install codegraph
+    fi
+    CODEGRAPH_BIN="codegraph"
+fi
+echo "Using codegraph binary: $CODEGRAPH_BIN"
+```
+
+### Step 2 - Build the Knowledge Graph
+
+Run the resolved `$CODEGRAPH_BIN` on the specified directory:
+```bash
+$CODEGRAPH_BIN build INPUT_PATH
+# Or with additional exclude arguments if provided by the user
+```
+*(Replace `INPUT_PATH` with the resolved target path, e.g. `.`)*
+
+If the command fails or errors out, capture the terminal stderr/logs, display them to the user with a helpful explanation, and ask them if they want to exclude specific directories or fix the errors. Do not fail silently.
+
+### Step 3 - Perform Deep Architectural Analysis
+
+Once the graph is built successfully:
+1. Read the newly generated `<path>/.codegraph/AGENT_PROMPT.md` file using your file reading tools.
+2. Read the project statistics, communities, god nodes, and cycle warnings from it.
+3. Perform a deep, professional architectural review of the codebase (using **English** as the report language), combined with deep insight analysis of the code implementation of existing features.
+4. Focus your review on:
+   - **System Architecture Evaluation**: Explain the design patterns, modularity level, and alignment between physical directories and logical components in the codebase.
+   - **Core Abstractions & Boundary Evaluation**: Deeply analyze God Nodes to determine which ones are core support and which ones have excessive responsibilities (God Object / Fat Class) that may lead to high risk.
+   - **Potential Bottlenecks & Architectural Refactoring Recommendations**: Point out high-coupling risk points and negative impacts of circular dependencies, and provide specific, actionable refactoring optimization plans (e.g., decoupling, extracting interfaces, dependency inversion).
+5. Read the existing `<path>/.codegraph/README.md` first. If there's an existing `## AI Architectural Insights` section, merge your new findings with it rather than silently overwriting and discarding previous edits.
+6. Write the completed report into `<path>/.codegraph/README.md` under the `## AI Architectural Insights` section, replacing any placeholder instructions.
+
+### Step 4 - Present Summary to the User
+
+Finally, reply to the user in English, summarizing:
+- The graph statistics (number of files, symbols, edges).
+- The logical component summary (with sizes and cohesion scores).
+- A brief bulleted summary of your key architectural findings and recommendations.
+- Clickable markdown links pointing to:
+  - The main entrypoint: `[README.md](file:///<absolute_path_to_vault>/README.md)`
+  - The agent guidelines: `[AGENTS.md](file:///<absolute_path_to_vault>/AGENTS.md)`
+  - The detailed components folder: `[components/](file:///<absolute_path_to_vault>/components/)`
+"""
+
+    try:
+        skills_dir.mkdir(parents=True, exist_ok=True)
+        skill_file = skills_dir / "SKILL.md"
+        skill_file.write_text(skill_content, encoding="utf-8")
+        console.print(
+            f"[bold green]Successfully installed /codegraph slash command to: [underline]{skill_file}[/underline][/bold green]"
+        )
+    except Exception as e:
+        console.print(f"[bold red]Failed to write skill configuration: {e}[/bold red]")
+
+
+@cli.command()
+def info():
+    """Prints tool info and supported languages."""
+    try:
+        from importlib.metadata import version
+
+        ver = version("codegraph")
+    except Exception:
+        ver = "0.2.0"
+    console.print(f"[bold]codegraph v{ver}[/bold]")
+    console.print(
+        "Supported languages: Python, JavaScript, TypeScript, Go, Rust, Swift"
+    )
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()