### Install Loomgraph for New Customers

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Instructions for initial installation using the demo package and setup commands.

```bash
tar xzf loomgraph-demo-{customer}-v0.8.0.tar.gz
cd loomgraph-demo-{customer}-v0.8.0
./quickstart.sh

# 然后在 Claude Code 中执行：
# /loomgraph-setup
# loomgraph index .
```

--------------------------------

### Setup development environment

Source: https://github.com/dreamlx/loomgraph/blob/main/CONTRIBUTING.md

Commands to clone the repository, create a virtual environment using uv, and install development dependencies.

```bash
git clone https://github.com/dreamlx/LoomGraph.git
cd LoomGraph
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
```

--------------------------------

### Ollama Provider Setup

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/migration-v0.10.md

Quick setup for the default Ollama provider.

```bash
ollama pull nomic-embed-text
# embedding.enabled: true is enough; defaults work
```

--------------------------------

### Configure MCP server

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Commands to install MCP configuration or start the server for AI agent integration.

```bash
loomgraph mcp <subcommand>
```

--------------------------------

### Query Suggestions

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Example of using the --suggest-next flag to guide Claude's iteration process without enforcing a rigid workflow.

```bash
loomgraph query "登录流程" --suggest-next

# 返回:
# Response: LoginController 处理登录请求...
#
# 💡 建议下一步查询:
#   1. loomgraph graph "AuthService" (被调用)
#   2. loomgraph find "TokenService" (依赖)
#   3. loomgraph query "Token 验证机制" (相关主题)
```

--------------------------------

### Configuration File Example

Source: https://github.com/dreamlx/loomgraph/blob/main/CLAUDE.md

Example of a .loomgraph.yaml configuration file for customizing embedding and LLM providers.

```yaml
# .loomgraph.yaml
embedding:
  enabled: true                 # off by default; turn on for semantic search
  provider: ollama              # ollama | openai | voyage | glm | custom
  api_url: "http://localhost:11434/v1"
  model: "nomic-embed-text"
  dimension: 768

llm:
  provider: ollama              # ollama | glm | openrouter | vllm
  api_url: "http://localhost:11434"
  model: "gemma3:12b-it-qat"
```

--------------------------------

### LoomGraph configuration example

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-003-update-strategy.md

Example configuration for the post-commit hook within the .loomgraph.yaml file.

```yaml
hooks:
  post_commit:
    mode: auto          # auto | sync | async | disabled
    max_files_sync: 3   # auto 模式下，≤3 files = sync
    log_file: ~/.loomgraph/hooks/post-commit.log
```

--------------------------------

### Install LoomGraph CLI

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Installs the base LoomGraph CLI tool without additional dependencies.

```bash
pipx install loomgraph
```

--------------------------------

### Install LoomGraph with Semantic Search

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Installs the LoomGraph package with optional built-in semantic search capabilities using a local CPU model.

```bash
pipx install "loomgraph[embed]"
```

--------------------------------

### Local Development Commands

Source: https://github.com/dreamlx/loomgraph/blob/main/CLAUDE.md

Commands for setting up the virtual environment, installing dependencies, running tests, and performing code checks.

```bash
# 创建虚拟环境
uv venv && source .venv/bin/activate

# 安装依赖
uv pip install -e ".[dev]"

# 运行测试
pytest tests/ -v --cov=src/loomgraph

# 代码检查
ruff check src/ tests/
mypy src/
```

--------------------------------

### Local Development Setup Commands

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/SYSTEM_DESIGN.md

Commands to initialize the local Ollama service required for LoomGraph development.

```bash
# 唯一前置：本地 Ollama（可选 embedding）
ollama serve
ollama pull gemma3:12b-it-qat
```

--------------------------------

### Upgrade Loomgraph for Existing Customers

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Instructions for upgrading existing installations using the upgrade package.

```bash
tar xzf loomgraph-upgrade-{customer}-v0.8.0.tar.gz
cd loomgraph-upgrade-{customer}-v0.8.0
./upgrade.sh

# 重启 Claude Code 后新功能自动可用
```

--------------------------------

### Install Language Grammars

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Installs specific tree-sitter grammar extras required for indexing non-default languages.

```bash
pipx install "loomgraph[typescript]"    # TypeScript / TSX
pipx install "loomgraph[javascript]"    # JavaScript / JSX
pipx install "loomgraph[swift]"
pipx install "loomgraph[java]"
pipx install "loomgraph[objc]"          # Objective-C (.h / .m; .mm not supported)
```

--------------------------------

### Local Ollama embedding setup

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Instructions and configuration for using a local Ollama instance for embeddings.

```bash
# Install once: https://ollama.com
ollama pull nomic-embed-text
```

```yaml
embedding:
  enabled: true
  provider: ollama
  api_url: http://localhost:11434/v1
  model: nomic-embed-text
  dimension: 768
```

--------------------------------

### Install Git Hooks

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Command to install Git hooks for automatic knowledge graph updates on commit.

```bash
loomgraph hooks install
# 之后每次 git commit 会自动更新知识图谱
```

--------------------------------

### Run the benchmark pipeline

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/benchmarks/dogfood.md

Commands to install dependencies, index repositories, perform round-trip data migration, and query the resulting database for entity counts.

```bash
# Install
pipx install loomgraph
pipx install ai-codeindex==0.27.0

# Direct-index baseline
loomgraph index /path/to/loomgraph -w loomgraph-bench:main
loomgraph index /path/to/codeindex -w codeindex-bench:master

# Round-trip
codeindex graph-export --root /path/to/loomgraph -o /tmp/lg.ndjson
loomgraph import-export /tmp/lg.ndjson -w loomgraph-bench:imported --clear

codeindex graph-export --root /path/to/codeindex -o /tmp/ci.ndjson
loomgraph import-export /tmp/ci.ndjson -w codeindex-bench:imported --clear

# Stats
sqlite3 ~/.loomgraph/loomgraph-bench:main.db \
  "SELECT COUNT(*) AS entities FROM entities, (SELECT COUNT(*) AS r FROM relations)"
```

--------------------------------

### Install and Configure LoomGraph MCP Server

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/MCP_DESIGN.md

Steps to install the loomgraph package, index a repository, register the MCP server with Claude Code, and initialize project-level tool guidance.

```bash
# 1. install
pipx install loomgraph

# 2. index a repo (one-time setup; needs codeindex)
pipx install ai-codeindex
loomgraph index .

# 3. register for this project's current Claude Code user (no JSON editing)
claude mcp add --scope local loomgraph -- loomgraph mcp serve
claude mcp get loomgraph

# 4. opt in to project-level tool-selection guidance (writes CLAUDE.md)
loomgraph init

# 5. restart Claude Code — done.
# Tools auto-discovered: loomgraph_find / loomgraph_graph / ...
```

--------------------------------

### Loomgraph CLI Quick Start Commands

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Common commands for indexing repositories, performing structural and semantic searches, and analyzing code topology.

```bash
# Index a repo (uses codeindex under the hood for parsing)
loomgraph index .

# Ask for a read-only, Claude Code-first navigation plan
loomgraph orient --task-kind cross-file

# Optional but recommended for Claude Code projects: add the project-level
# rule describing when structural navigation is preferable to text lookup.
loomgraph init

# Structural search — fuzzy match on entity names
loomgraph find "UserService"

# Semantic search — by meaning, not name ([embed] extra or an embedding provider)
loomgraph search "where is authentication handled"

# Walk the call graph
loomgraph graph "UserService.login" --depth 2

# Topology smells (orphans, hubs, god functions) + resolution trust signal
loomgraph topology

# Change-impact analysis from a git diff
loomgraph impact HEAD --depth 2

# Cross-module dependency map
loomgraph deps
```

--------------------------------

### Perform Semantic Search

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Examples of using structured search and semantic query commands.

```bash
# 结构化搜索
loomgraph find "UserService" --with-relations

# 语义问答
loomgraph query "用户认证的流程是什么？"
```

--------------------------------

### CLI Topology Command Usage

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-009-graph-topology-debt-analysis.md

Examples of using the new --module parameter to perform scoped topology analysis.

```bash
loomgraph topology                    # 全局分析
loomgraph topology --module cli       # 只分析 cli 模块 (source_prefix 过滤)
loomgraph topology --module core      # 只分析 core 模块
```

--------------------------------

### Index command with reference snapshots

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Examples of using the --at-ref flag to create independent snapshot workspaces from specific git references.

```bash
loomgraph index --at-ref v1.2
loomgraph index /path/to/repo --at-ref v1.2 --workspace customer:v1.2
```

--------------------------------

### Commit Message Example

Source: https://github.com/dreamlx/loomgraph/blob/main/CLAUDE.md

Example of a compliant commit message following the project's conventions.

```text
feat(chunking): implement Python AST parser with tree-sitter

- Add tree-sitter-python binding
- Support function and class extraction
- Preserve docstrings in chunks

Closes #12
```

--------------------------------

### Index command success output

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Example of a successful JSON output from the index command.

```json
{
  "success": true,
  "data": {
    "mode": "cold_rebuild",
    "workspace": "myproj:main",
    "repo_path": "/path/to/repo",
    "cleared": true,
    "entities_created": 1250,
    "relations_created": 3400,
    "embedded": 1250,
    "store_stats": {"entities": 1250, "relations": 3400},
    "duration_seconds": 45.2
  }
}
```

--------------------------------

### Inject Grammars into Existing Installation

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Commands to add grammar packages to an existing pipx virtual environment.

```bash
pipx inject loomgraph tree-sitter-typescript
tree-sitter-javascript
```

--------------------------------

### Pinning to v0.9.3

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/migration-v0.10.md

Use this command to install the previous minor version if you need to maintain compatibility with the LightRAG path.

```bash
pipx install "loomgraph==0.9.3"
```

--------------------------------

### loomgraph topology CLI usage

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-009-graph-topology-debt-analysis.md

Examples of running the topology analysis command with default settings, custom thresholds, or specific workspaces.

```bash
# 完整拓扑分析
loomgraph topology

# 调整阈值
loomgraph topology --hub-threshold 5 --god-threshold 5

# 指定 workspace
loomgraph topology -w my-project
```

--------------------------------

### Manon Black-box Query

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Example of a black-box query process that lacks transparency and control.

```bash
manon_deep_query("登录流程")
# 用户等待 60 秒...
# 不知道内部做了什么
# 如果超时，整个过程浪费
# 无法调整方向
```

--------------------------------

### CLI usage for loomgraph query

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-008-search-architecture-redesign.md

Examples of using the loomgraph query command with various modes and workspace specifications.

```bash
# 基础用法：自然语言问题
loomgraph query "How does the authentication flow work?"

# 指定查询模式
loomgraph query "What modules handle payment?" --mode local
loomgraph query "What are the main architectural patterns?" --mode global
loomgraph query "How is error handling implemented?" --mode hybrid

# 指定 workspace
loomgraph query "What are the core modules?" -w my-project
```

--------------------------------

### LoomGraph Transparent Query Workflow

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Example of a transparent query workflow where the user and Claude can see and adjust the iteration steps.

```bash
# Claude 第 1 步
loomgraph query "登录流程"
# 用户看到: LoginController 的说明

# Claude 第 2 步（用户可见）
loomgraph graph "LoginController"
# 用户看到: 调用关系图

# 用户可以随时:
# - 提供额外信息
# - 调整查询方向
# - 中断不需要的探索
```

--------------------------------

### GitHub Actions CI/CD Integration

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-012-technical-debt-analysis-format.md

Example of running a debt analysis and enforcing a threshold check within a GitHub Actions workflow.

```yaml
# GitHub Actions 集成
- name: Debt Analysis
  run: loomgraph debt --format json > debt.json
- name: Check Threshold
  run: |
    SCORE=$(jq '.overall_health.total_score' debt.json)
    if [ $SCORE -lt 70 ]; then exit 1; fi
```

--------------------------------

### Manage Git hooks

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Installs or uninstalls post-commit hooks to trigger automatic updates.

```bash
loomgraph hooks <subcommand>
```

--------------------------------

### Update .loomgraph.yaml Configuration

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/migration-v0.10.md

Example showing the transition from v0.10.0 configuration to the new v0.11.0 structure, including the new enabled flag and renamed api_url key.

```yaml
# Replace this (v0.10.0)
embedding:
  provider: jina
  base_url: http://internal.example.invalid
  model: jinaai/jina-embeddings-v2-base-code

# With this (v0.11.0)
embedding:
  enabled: false      # or: true to keep semantic embedding active
  provider: ollama    # or openai / voyage / glm / custom
  api_url: http://localhost:11434/v1
  model: nomic-embed-text
  dimension: 768
```

--------------------------------

### Update Loomgraph to version 0.2.4

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Commands to activate the virtual environment and install the package from the current directory.

```bash
cd /path/to/loomgraph-package
source ~/.loomgraph-venv/bin/activate
pip install .
```

--------------------------------

### User Project GitHub Action Integration

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-003-update-strategy.md

Example configuration for a user project to consume the reusable LoomGraph workflow.

```yaml
name: Update Knowledge Graph

on: [push]

jobs:
  update-graph:
    uses: dreamlx/LoomGraph/.github/workflows/incremental-update.yml@main
    with:
      lightrag_endpoint: ${{ secrets.LIGHTRAG_URL }}
      embedding_endpoint: ${{ secrets.EMBEDDING_URL }}
```

--------------------------------

### Trends Analysis Output

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-015-git-knowledge-graph-integration.md

Example output showing the trend analysis for an entity over 6 months.

```text
UserService.authenticate
├─ 2025-10: out_degree=15
├─ 2025-11: out_degree=18
├─ 2025-12: out_degree=22
├─ 2026-01: out_degree=28
├─ 2026-02: out_degree=32
└─ 2026-03: out_degree=35  ⚠️ Trend: +133% in 6 months (rotting)

Recommendation: Refactor NOW (still salvageable)
```

--------------------------------

### Git version check for compatibility

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-010-technical-design.md

Verifies that the installed Git version is at least 2.0 by parsing the output of git --version.

```python
def _check_git_version(self) -> None:
    """检查 Git 版本（>= 2.0）."""
    try:
        result = subprocess.run(
            ["git", "--version"],
            capture_output=True,
            text=True,
            check=True,
        )
        # 解析版本号（git version 2.39.1）
        version_str = result.stdout.split()[2]
        major_version = int(version_str.split(".")[0])

        if major_version < 2:
            raise GitError(f"Git version {version_str} too old. Require >= 2.0")

    except Exception as e:
        raise GitError(f"Git not found or version check failed: {e}")
```

--------------------------------

### AI Agent Parsing

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-012-technical-debt-analysis-format.md

Example of how an AI agent can parse the generated debt report to identify critical issues.

```python
# Claude Code Skills 可解析
report = json.load("debt.json")
p0_issues = [i for i in report["issues"] if i["severity"] == "P0"]
# 自动生成重构 PR
```

--------------------------------

### CLI usage for loomgraph find command

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-008-search-architecture-redesign.md

Examples of using the 'find' command with various filters, depth settings, and workspace specifications.

```bash
# 基础用法：按名匹配实体
loomgraph find "AuthService"

# 类型过滤
loomgraph find "auth" --type class

# 带关系上下文（一次到位，BFS depth=1）
loomgraph find "auth" --with-relations

# 扩展到 2 层关系（BFS depth=2）
loomgraph find "auth" --with-relations --depth 2

# 限制结果数
loomgraph find "service" --limit 10

# 指定 workspace
loomgraph find "auth" -w my-project
```

--------------------------------

### Check LoomGraph and codeindex versions

Source: https://github.com/dreamlx/loomgraph/blob/main/skills/loomgraph-setup/SKILL.md

Verify that LoomGraph and its internal codeindex are installed and accessible within the pinned virtual environment.

```bash
loomgraph version 2>/dev/null || echo '{"error": "loomgraph not installed"}'
loomgraph codeindex --version    # 走 loomgraph 的 pinned venv，不查 PATH
```

--------------------------------

### MCP Server Query Invocation

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Example of how Claude interacts with LoomGraph via the MCP protocol to maintain flexible, external iteration.

```python
mcp_loomgraph_query("登录流程")
# Claude 判断：需要更多信息
mcp_loomgraph_graph("LoginController")
# Claude 判断：足够了，综合回答
```

--------------------------------

### Update Loomgraph to version 0.2.5

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Commands to activate the virtual environment and install the 0.2.5 package, followed by a version verification check.

```bash
cd /path/to/loomgraph-package
source ~/.loomgraph-venv/bin/activate
pip install ./loomgraph-*.whl
loomgraph version  # 应显示 0.2.5
```

--------------------------------

### Run project overview

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Displays a high-level view of the project including entity counts, type distribution, and module summaries.

```bash
loomgraph overview [options]
```

--------------------------------

### Regenerate target-manifest.json

Source: https://github.com/dreamlx/loomgraph/blob/main/evals/deepswe/README.md

Use this command to regenerate the target manifest from a pinned local DeepSWE checkout. Ensure the --deep-swe-root path points to your local installation.

```bash
python evals/deepswe/build-target-manifest.py \
  --deep-swe-root /path/to/deep-swe \
  --output evals/deepswe/target-manifest.json
```

--------------------------------

### Enhanced Single Query Capability

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Example of a single query command that retrieves entities, direct relations, and indirect relations to reduce the number of iterations required by Claude.

```bash
loomgraph find "LoginController" --with-relations --depth 2

# 一次查询返回:
# - 实体本身
# - 直接关系（callers + callees）
# - 间接关系（depth 2）
```

--------------------------------

### 故障排查：路径过滤配置

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/github-action-integration.md

通过在 on.push.paths 中设置路径过滤，避免因无关文件变更触发更新。

```yaml
on:
  push:
    paths:
      - 'src/**'
      - '!**/*.md'
```

--------------------------------

### 执行温更新命令

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/UPDATE_STRATEGY.md

通过 CLI 命令自动检测 Git 变动并执行增量追加更新。

```bash
# 自动检测 git 变动并追加
loomgraph update
```

--------------------------------

### 跨 Workspace 对比 CLI 命令

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-009-workspace-as-knowledge-snapshot.md

用于执行实体/关系差异对比及跨 workspace 相似实体检测的命令。

```bash
# 实体/关系 diff
loomgraph compare --ws1 [customer]-backend:main --ws2 [customer]-backend:feature-auth

# 跨 workspace 相似实体检测
loomgraph similar --entity "AuthService" --across-workspaces
```

--------------------------------

### 温更新 CLI 命令选项

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/UPDATE_STRATEGY.md

展示了执行增量更新以及指定比较基准的 CLI 命令。

```bash
# 增量更新，仅处理变动文件
loomgraph update

# 指定比较基准
loomgraph update --since HEAD~3
```

--------------------------------

### Upgrade Loomgraph via pipx

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/migration-v0.10.md

Command to upgrade the existing Loomgraph installation to the latest version.

```bash
pipx install --upgrade loomgraph
```

--------------------------------

### Skill Directory Structure

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/SYSTEM_DESIGN.md

The directory layout for LoomGraph skills, which are installed into the Claude Code environment.

```text
skills/
├── loomgraph-debt-radar/SKILL.md      # Skill A: 债务雷达
├── loomgraph-sync-advisor/SKILL.md    # Skill B: 智能同步
├── loomgraph-evolution/SKILL.md       # Skill C: 演化观察
├── loomgraph-setup/SKILL.md           # 配置向导
└── loomgraph-init/SKILL.md            # CLAUDE.md 注入
```

--------------------------------

### 故障排查：修正工作目录路径

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/github-action-integration.md

如果遇到文件未找到错误，请检查并修正 working_directory 配置。

```yaml
with:
  working_directory: './your-app'  # 确保路径正确
```

--------------------------------

### Upgrade path for v0.10.0

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Required steps for upgrading to v0.10.0 including cold rebuild of the index.

```bash
pipx install --upgrade ai-codeindex loomgraph
loomgraph index --clear .   # Cold rebuild
loomgraph find "<某类名>"   # 验证
```

--------------------------------

### Generate .codeindex.yaml configuration

Source: https://github.com/dreamlx/loomgraph/blob/main/skills/loomgraph-setup/SKILL.md

Run the codeindex wizard to generate the configuration file. The dry-run command previews changes, while the init command applies them.

```bash
# 先预览会改哪些文件（不实际写，GH #88）
loomgraph codeindex init --dry-run
```

```bash
# 生成 .codeindex.yaml（+ 上述副作用）
loomgraph codeindex init --yes
```

--------------------------------

### Run capability observations CLI command

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/evals/capability-run-matrix-v1.md

Command to execute the eight capability tasks into an adapter-owned directory.

```bash
python evals/run_capability_observations.py \
  --work-root /tmp/loomgraph-capability-v1-work \
  --output /tmp/loomgraph-capability-v1-observations.jsonl
```

--------------------------------

### Configuration migration diff

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/migration-v0.10.md

Comparison showing the transition from the v0.9.x lightrag configuration to the v0.10.0 storage and llm structure.

```yaml
# v0.9.x
lightrag:
  api_url: http://internal.example.invalid
  api_timeout: 30.0

# v0.10.0 — replace with
storage:
  backend: sqlite
  db_path: ~/.loomgraph/{workspace}.db
llm:
  provider: ollama
  api_url: http://localhost:11434
  model: gemma3:12b-it-qat
```

--------------------------------

### Skill A Workflow Steps

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-007-entropy-reduction-skills.md

The sequential steps for generating a technical debt audit report using codeindex and LoomGraph CLI commands.

```text
Step 1: codeindex tech-debt ./src --format json
        → 文件级问题 (God Class, 超大文件, 高噪音比)

Step 2: loomgraph deps --depth 2
        → 模块级依赖图 (循环依赖, 高耦合模块)

Step 3: loomgraph overview
        → 模块功能概览 (识别职责不清的模块)

Step 4: LLM 综合分析
        → 汇总 Step 1-3 的数据
        → 生成优先级排序 + 重构建议
        → 输出 Markdown 报告
```

--------------------------------

### Minimal local configuration

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

A basic configuration using a local SQLite backend with semantic search disabled.

```yaml
storage:
  backend: sqlite
  db_path: "~/.loomgraph/{workspace}.db"
embedding:
  enabled: false   # turn on later for vec0 semantic search
```

--------------------------------

### Execute Indexing Command

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Run the index command to process a repository path.

```bash
# 一键完成所有步骤
loomgraph index /path/to/repo
```

--------------------------------

### DebtAnalyzer CLI Integration

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-015-git-knowledge-graph-integration.md

Command to run the debt analysis with Git metrics enabled.

```bash
loomgraph debt \
  --codeindex-data debt.json \
  --with-git \				# 启用 Git 分析
  --git-since "3 months"      # 时间窗口
```

--------------------------------

### loomgraph_branch_diff Response Example

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/MCP_DESIGN.md

The response structure for the branch diff tool, which provides details on provisioned workspaces and the resulting diff entities.

```jsonc
{
  "base": {"ref": "main", "workspace": "repo:main", "provisioned": "reused"},
  "head": {"ref": "feature", "workspace": "repo:feature", "provisioned": "created"},
  "diff": {"entities_added": [], "entities_removed": []},
  "duration_seconds": 0.42
}
```

--------------------------------

### Verify generated configuration

Source: https://github.com/dreamlx/loomgraph/blob/main/skills/loomgraph-setup/SKILL.md

Display the contents of the generated .codeindex.yaml file to ensure it matches the project structure.

```bash
cat .codeindex.yaml
```

--------------------------------

### Development and Testing Commands

Source: https://github.com/dreamlx/loomgraph/blob/main/CLAUDE.md

Commands for running unit tests, full test suites with coverage, and performing static analysis using ruff and mypy.

```bash
# 运行特定测试
pytest tests/unit/test_mapper.py -v

# 运行所有测试
pytest tests/ -v --cov=src/loomgraph

# 代码检查（CI 范围）
ruff check src/ tests/
mypy src/
```

--------------------------------

### Build and run with codegraph backend

Source: https://github.com/dreamlx/loomgraph/blob/main/evals/deepswe/README.md

Builds a pinned Linux bundle and executes the treatment smoke test using the codegraph backend.

```bash
evals/deepswe/build-codegraph-bundle.sh /tmp/codegraph-linux-x64.tar.gz
LOOMGRAPH_BACKEND=codegraph \
CODEGRAPH_BUNDLE=/tmp/codegraph-linux-x64.tar.gz \
evals/deepswe/run-omp-smoke.sh treatment ts-pattern-match-each
```

--------------------------------

### Error Recovery Workflow

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Demonstrates a step-by-step recovery process when an index command fails due to missing dependencies.

```bash
# 如果 index 失败,AI 可以分步调试
$ loomgraph index /repo
{"success": false, "error": {"code": "CODEINDEX_NOT_FOUND", ...}}

# AI 根据错误信息安装依赖
$ pip install ai-codeindex

# 重新执行
$ loomgraph index /repo
{"success": true, ...}
```

--------------------------------

### 触发工作流测试

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/guides/github-action-integration.md

通过 git 命令提交代码以触发配置好的 GitHub Action。

```bash
git add .
git commit -m "test: trigger knowledge graph update"
git push
```

--------------------------------

### Skill A workflow steps

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-009-graph-topology-debt-analysis.md

Comparison of the original and enhanced Skill A (debt-radar) analysis steps.

```text
Step 1: codeindex tech-debt    → 文件级债务
Step 2: loomgraph deps         → 模块依赖
Step 3: loomgraph overview     → 模块概览
Step 4: loomgraph workspace    → 统计信息
Step 5: LLM 综合分析           → 报告
```

```text
Step 1: codeindex tech-debt    → 文件级债务        (不变)
Step 2: loomgraph deps         → 模块依赖          (不变)
Step 3: loomgraph overview     → 模块概览          (不变)
Step 4: loomgraph workspace    → 统计信息          (不变)
Step 5: loomgraph topology     → 图谱拓扑分析      (新增)
Step 6: loomgraph check        → 索引新鲜度        (新增)
Step 7: LLM 综合分析           → 增强版报告        (改进)
```

--------------------------------

### Cold Rebuild API Workflow

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-003-update-strategy.md

The sequence of operations for a full graph rebuild, starting with clearing the graph and ending with a full data insertion.

```text
loomgraph index --clear /repo
    ↓
DELETE /graph/clear (清空全部 11 层)
    ↓
codeindex scan /repo
    ↓
collect_kg_data() + build_chunks() + create_external_stubs()
    ↓
POST /documents/insert_custom_kg (单次，全层写入)
```

--------------------------------

### B3 Topology debt analysis with Git evidence

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/evals/capability-run-matrix-v1.md

Calculates technical debt using Git history over the last 10 years.

```bash
loomgraph debt --with-git --git-since '10 years' -w "$WS"
```

--------------------------------

### Run full test and linting suite

Source: https://github.com/dreamlx/loomgraph/blob/main/CONTRIBUTING.md

Command to execute ruff, mypy, and pytest to ensure code quality and test coverage before pushing changes.

```bash
ruff check src/ tests/ && mypy src/ && pytest tests/
```

--------------------------------

### JSON Output: loomgraph sync response

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-002-git-integration-skills.md

Example JSON response structure for a sync operation, including patch information, conflict analysis, and recommended actions.

```json
{
  "success": true,
  "data": {
    "upstream": "upstream/main",
    "downstream": "customer-a",
    "patch_info": {
      "commits": 3,
      "files_changed": 5,
      "description": "Security fix for auth module"
    },
    "conflict_analysis": {
      "can_auto_merge": false,
      "conflicts": [
        {
          "file": "src/auth/validator.py",
          "lines": "45-60",
          "reason": "上游改了签名，下游加了参数",
          "suggestion": "保留下游参数，合并上游逻辑"
        }
      ]
    },
    "action": {
      "recommended": "manual_merge",
      "pr_draft": "https://github.com/.../pull/new"
    }
  }
}
```

--------------------------------

### Feature 3 Data Flow (v0.11)

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-010-git-metrics-integration.md

Outlines the workflow for monthly debt analysis, historical snapshot storage, and trend analysis using linear regression.

```text
1. 债务分析运行（每月）
   └─> loomgraph debt --with-git
   └─> 生成 report

2. 历史快照保存
   └─> ~/.loomgraph/metrics-history/2026-03-01.json
   └─> {entity_name: {out_degree, in_degree, ...}}

3. 趋势分析
   └─> loomgraph trends --entity "X"
   └─> 读取 6 个月历史数据
   └─> 线性回归 → 趋势判定
```

--------------------------------

### Perform indexing and integrity verification

Source: https://github.com/dreamlx/loomgraph/blob/main/skills/loomgraph-setup/SKILL.md

Run the indexer and verify that entities were created and that the correct directories are being scanned.

```bash
loomgraph index .
```

```bash
loomgraph find "<某个已知实体名>"   # 应能找到
```

```bash
loomgraph codeindex list-dirs       # codeindex 实际会扫描的目录
```

--------------------------------

### CLI Commands: Evolution Tracking

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-002-git-integration-skills.md

CLI commands for tracking module evolution, generating reports, and visualizing fork trees.

```bash
# 追踪模块演化
loomgraph evolution src/auth

# 生成演化报告
loomgraph evolution src/auth --report markdown

# 可视化分叉树
loomgraph evolution src/auth --visualize
```

--------------------------------

### MVP 更新策略 CLI 命令

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-006-mvp-simplification.md

展示了如何通过命令行手动触发索引或配置 cron job 实现每日自动重建。

```bash
# 用户修改代码后，重新运行 index
loomgraph index --path /repo

# 或设置 cron job 每日重建
0 2 * * * loomgraph index --path /repo --quiet
```

--------------------------------

### Run module dependency analysis

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Aggregate CALLS, IMPORTS, and INHERITS edges to construct a module-level dependency graph.

```bash
loomgraph deps [options]
```

```json
{
  "success": true,
  "data": {
    "modules": ["src/loomgraph", "scripts", "docs/spikes"],
    "dependencies": [
      {
        "from": "scripts",
        "to": "src/loomgraph",
        "count": 26,
        "types": {"CALLS": 26}
      }
    ]
  }
}
```

--------------------------------

### Upgrade LoomGraph 0.9.0 via Script

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Manual upgrade steps for existing customers using the provided upgrade tarball.

```bash
tar xzf loomgraph-upgrade-{customer}-v0.9.0.tar.gz
cd loomgraph-upgrade-{customer}-v0.9.0
./upgrade.sh

# 重启 Claude Code 后新功能自动可用
```

--------------------------------

### Run Debt Analysis and View Scores

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Commands to execute debt analysis and view multi-dimensional scoring details.

```bash
# 运行债务分析，查看改进后的评分
loomgraph debt --codeindex-data /tmp/debt-report.json

# 查看多维度评分明细
# breakdown: { quality: 84, maintainability: 97, topology: 75 }
```

--------------------------------

### Check index freshness

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Verifies that source_id references in the knowledge graph still point to existing files on disk.

```bash
loomgraph check [options]
```

```json
{
  "success": true,
  "data": {
    "freshness": {
      "total_source_paths": 150,
      "valid": 116,
      "stale": 34,
      "freshness_ratio": 0.773
    },
    "stale_entries": [
      {
        "source_id": "cli/main.py:66-81",
        "file_path": "cli/main.py",
        "reason": "file_not_found",
        "suggestion": "Run 'loomgraph update' or 'loomgraph index --clear .'"
      }
    ],
    "suggestion": "34 source paths are stale. Run 'loomgraph index --clear .' to rebuild."
  }
}
```

--------------------------------

### Manage workspaces

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Commands for listing, inspecting, and deleting workspace snapshots stored as SQLite files.

```bash
loomgraph workspace <subcommand>
```

--------------------------------

### loomgraph overview CLI 命令示例

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-004-bidirectional-orchestrator.md

展示了如何使用 loomgraph overview 命令生成项目概览，支持通过 --depth 参数控制模块层级。

```bash
# 生成项目概览
loomgraph overview

# 指定深度（顶级 vs 二级模块）
loomgraph overview --depth 1
```

--------------------------------

### Workspace 管理 CLI 命令

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-009-workspace-as-knowledge-snapshot.md

用于列出、查看详情及清理 workspace 的管理命令。

```bash
loomgraph workspace list                    # 列出所有 workspace + 统计
loomgraph workspace info [name]             # 详情 (entity数, relation数, 最后更新)
loomgraph workspace delete <name>           # 清理
```

--------------------------------

### Analyze Technical Debt

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Commands to perform topology analysis and check index freshness.

```bash
# 拓扑分析
loomgraph topology

# 索引新鲜度检查
loomgraph check
```

--------------------------------

### Index command usage

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Basic usage of the index command to perform a one-click index of a repository.

```bash
loomgraph index [<repo_path>] [options]
```

--------------------------------

### Full Indexing CLI Commands

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/UPDATE_STRATEGY.md

Commands for full indexing, either by clearing the database first or using append mode.

```bash
# 全量重建（清空后重建）
loomgraph index --clear <repo_path>

# 全量重建（不清空，追加模式）
loomgraph index --no-clear <repo_path>
```

--------------------------------

### Run LoomGraph query with suggest-next flag

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-011-ai-iteration-strategy.md

Demonstrates the accepted query suggestion feature which provides actionable next steps after a query response.

```bash
loomgraph query "登录流程" --suggest-next

# 返回:
# Response: ...
# 💡 建议下一步:
#   - loomgraph graph "LoginController"
#   - loomgraph find "AuthService"
```

--------------------------------

### Cold Rebuild Command

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/architecture/UPDATE_STRATEGY.md

Performs a full reconstruction of the workspace knowledge base by clearing existing data.

```bash
loomgraph index --clear <repo_path>
```

--------------------------------

### Feature 1-2 Data Flow (v0.10)

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-010-git-metrics-integration.md

Outlines the workflow for Git log extraction, caching, and integration with DebtAnalyzer.

```text
1. Git Log 提取
   └─> git log --since="3 months" --format="%H|%an|%at|%s"
   └─> 解析为 FileMetrics

2. 缓存存储
   └─> ~/.loomgraph/cache/git-metrics.json
   └─> TTL: 1 天

3. DebtAnalyzer Join
   └─> LightRAG entities + Git metrics
   └─> 按 source_id 匹配
   └─> 生成增强的 debt report
```

--------------------------------

### Index a repository with loomgraph

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/benchmarks/dogfood.md

Use this command to index a target repository and assign it to a specific workspace.

```bash
loomgraph index <repo> --workspace <name>
```

--------------------------------

### Epic Documentation File Path

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/AGILE_GUIDE.md

The standard file path convention for storing detailed Epic documentation.

```text
docs/epics/EPIC-NNN-short-title.md
```

--------------------------------

### Configure default workspace for LoomGraph

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/MCP_DESIGN.md

Add the --default-workspace argument to the server configuration to pin a specific workspace at startup.

```json
{
  "mcpServers": {
    "loomgraph": {
      "command": "loomgraph",
      "args": ["mcp", "serve", "--default-workspace", "myproject:main"]
    }
  }
}
```

--------------------------------

### Issue to PR Workflow Steps

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/AGILE_GUIDE.md

The standard lifecycle for managing development from Epic creation to version release.

```text
1. Epic Issue 创建，绑定 Milestone
2. Feature 分支开发: feature/epic-006-cross-workspace
3. PR 描述中写: Closes #11 (Feature Issue) 或在 Epic Issue checklist 勾选
4. Merge PR → Feature Issue 自动关闭
5. 版本发布时 → 关闭 Epic Issue + 关闭 Milestone
```

--------------------------------

### Run LLM Code Interpretation

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Commands to trigger LLM-generated descriptions via the codeindex integration.

```bash
# Requires ai_command in .codeindex.yaml (e.g. claude -p, deepseek, etc.)
loomgraph codeindex scan . --ai     # enrich README_AI.md via LLM (passthrough)
loomgraph codeindex scan-all --ai   # whole tree (passthrough)
```

--------------------------------

### 基于 content_hash 的去重机制 (SQL)

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-006-mvp-simplification.md

在数据库插入时使用 content_hash 进行冲突处理，确保重复运行索引时不会产生冗余数据。

```sql
-- 使用 content_hash 去重，避免重复向量化
INSERT INTO code_chunks (file_path, content_hash, ...)
ON CONFLICT (file_path, content_hash) DO UPDATE SET updated_at = NOW();
```

--------------------------------

### AST 预处理流程

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/adr/ADR-002-lightrag-framework.md

描述了在调用 LightRAG.insert() 之前，通过 Tree-sitter 对源代码进行 AST 解析并提取函数或类块的预处理流程。

```text
源代码 → Tree-sitter AST 解析 → 提取函数/类块 → LightRAG.insert()
```

--------------------------------

### Analyze Git metrics

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Calculates change frequency hotspots, bus factor, and defect magnets for a repository.

```bash
loomgraph git-metrics [PATH] [options]
```

--------------------------------

### Run topology analysis

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Analyze the knowledge graph topology to detect structural code smells like orphans, hubs, and god functions.

```bash
loomgraph topology [options]
```

--------------------------------

### MVP Full Repository Indexing Strategy

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/DATA_CONTRACT.md

The index_repository function implements a full-rebuild strategy by clearing existing entities for a repository path, scanning files, and re-injecting them into LightRAG.

```python
# loomgraph/core/indexer.py

async def index_repository(repo_path: str, rag: LightRAG) -> IndexResult:
    """MVP 索引策略：全量重建."""

    # Step 1: 获取该仓库的所有已有实体
    existing_entities = await get_entities_by_file_prefix(rag, repo_path)

    # Step 2: 删除旧数据
    if existing_entities:
        await rag.graph_storage.remove_nodes([e["entity_name"] for e in existing_entities])

    # Step 3: 扫描并解析所有文件
    files = scan_code_files(repo_path)
    total_entities = 0
    total_relations = 0

    for file_path in files:
        # 解析
        result = codeindex.parse_file(file_path)
        if result.error:
            continue

        # 向量化
        texts = [s.signature or s.name for s in result.symbols]
        embeddings = await jina_client.embed(texts)
        embedding_map = {s.name: emb for s, emb in zip(result.symbols, embeddings)}

        # 注入
        inject_result = await inject_parse_result(rag, result, embedding_map)
        total_entities += inject_result.entities
        total_relations += inject_result.relations

    return IndexResult(
        repo_path=repo_path,
        files=len(files),
        entities=total_entities,
        relations=total_relations
    )
```

--------------------------------

### 变更影响分析技术实现流程

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-002-git-integration-skills.md

描述了从 Git 变更输入到生成 JSON 报告的技术处理步骤。

```text
输入: git commit / git diff
         ↓
Step 1: 解析变更文件和符号 (git diff --name-only + codeindex)
         ↓
Step 2: 查询知识图谱 (loomgraph graph --direction callers)
         ↓
Step 3: 计算影响范围 (递归查找调用者)
         ↓
Step 4: 风险评估 (LLM 或规则)
         ↓
输出: 影响分析报告 (JSON)
```

--------------------------------

### Graph Analytics Optimization Workflow

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-009-graph-topology-debt-analysis.md

Comparison of the current full-download approach versus the optimized server-side computation approach.

```text
当前:  CLI → GET /graph/entities/all → 500MB JSON → Python 计算 → 结果
优化:  CLI → GET /graph/orphans      → 5KB JSON   → 直接输出
            GET /graph/degree         → 10KB JSON
            GET /graph/stats          → 1KB JSON
```

--------------------------------

### Implementation Schedule: Phase 1 P0

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/epics/completed/EPIC-002-git-integration-skills.md

A two-week development schedule for the P0 implementation phase.

```text
Week 1:
├── Day 1-2: TDD - 编写测试用例
├── Day 3-4: 实现 git diff 解析 + 符号提取
└── Day 5: 集成 loomgraph graph 查询

Week 2:
├── Day 1-2: 影响范围计算算法
├── Day 3: 风险评估规则
├── Day 4: CLI 集成
└── Day 5: 文档 + 验收
```

--------------------------------

### Minimal local configuration for .loomgraph.yaml

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Configuration for running LoomGraph completely locally without external services.

```yaml
storage:
  backend: sqlite
embedding:
  enabled: false
```

--------------------------------

### Summarize pilot runs

Source: https://github.com/dreamlx/loomgraph/blob/main/evals/deepswe/README.md

Run the summarization script after all trials are complete to generate a summary of the pilot results.

```bash
evals/deepswe/summarize-orientation-pilot.py /tmp/loomgraph-orientation-pilot
```

--------------------------------

### Static MCP configuration for compatible hosts

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/MCP_DESIGN.md

Use the --path option with loomgraph mcp install-config to generate or provide this static JSON configuration for hosts.

```json
{
  "mcpServers": {
    "loomgraph": {
      "command": "loomgraph",
      "args": ["mcp", "serve"]
    }
  }
}
```

--------------------------------

### Analyze Complexity Trends

Source: https://github.com/dreamlx/loomgraph/blob/main/customers/CHANGELOG.md

Steps to accumulate snapshots and analyze complexity trends for a specific entity.

```bash
# Step 1: 多次运行 debt 命令积累快照（建议每周运行一次，持续 1-2 个月）
loomgraph debt --with-git

# Step 2: 分析趋势（需要至少 3 次快照）
loomgraph trends --entity "src/auth/user_service.py" --metric complexity --months 6

# 输出示例：
# Trend: INCREASING
# Slope: +3.00/month (+0.100/day), R²: 0.950
#
# ⚠️ Rapid complexity growth detected: +25.0% projected in next month.
# Current: 45, Forecast: 56. Consider refactoring to prevent further deterioration.
```

--------------------------------

### Check version

Source: https://github.com/dreamlx/loomgraph/blob/main/docs/api/CLI_DESIGN.md

Displays the current version of the LoomGraph CLI.

```bash
loomgraph version
```

--------------------------------

### Run Capability Manifest

Source: https://github.com/dreamlx/loomgraph/blob/main/README.md

Executes the deterministic Track A assertions defined in the capability manifest, failing if any referenced test is renamed or regresses.

```bash
python evals/run_capability_manifest.py
```