devgraph build - DevGraph

Usage

devgraph build [paths...] [options]

Arguments

Argument	Description	Default
`paths`	Files, directories, or globs to scan	current workspace

If you omit paths, DevGraph scans the current workspace root.

Options

Option	Description
`--compare <path>`	Compare the current graph output against a previous `graph.json`
`--out-dir <dir>`	Output directory for generated files
`--help`	Show help

What Build Does

devgraph build is the canonical hybrid pipeline:

Collect inputs from files, directories, or globs
Apply default ignores and .devgraphignore
Classify and extract deterministic graph data
Merge service metadata from devgraph-* blocks with file-level graph structure
Analyze the graph and emit reports plus diagrams

devgraph-service blocks remain the authoritative service layer. The rest of the build adds file nodes and typed graph edges around that layer.

Ignore Rules

DevGraph applies default exclusions such as:

.git/
.devgraph/
node_modules/
dist/
build/
.next/
coverage outputs
obvious generated artifacts

You can add a repo-local .devgraphignore file with .gitignore syntax to exclude more paths.

Incremental Cache

Build stores file extraction state in .devgraph/cache/manifest.json. The cache is keyed by file path, file hash, and extractor version so unchanged files can be skipped on later builds.

Examples

Build the current repo:

devgraph build .

Build selected paths:

devgraph build apps packages docs/**/*.md

Build and compare against an earlier graph:

devgraph build . --compare .devgraph/graph.json

Output

Build writes the following files to .devgraph/:

File	Description
`graph.json`	Machine-readable output containing top-level `services`, `apis`, and `knowledgeGraph`
`summary.md`	Human-readable service overview
`GRAPH_REPORT.md`	Hybrid graph analysis with god nodes, surprising connections, bridge nodes, and coverage gaps
`agents/*.md`	Per-service context files for coding assistants
`system.mmd`	Mermaid diagram of the build pipeline and service relationships
`codemap.mmd`	Mermaid diagram of owned paths and file relationships

At a high level, graph.json contains:

top-level services
top-level apis
knowledgeGraph.nodes
knowledgeGraph.edges
knowledgeGraph.communities
knowledgeGraph.analysis

devgraph query for focused graph retrieval
devgraph studio for interactive graph exploration
devgraph agents for generated AI context files and orchestration skills

​Usage

​Arguments

​Options

​What Build Does

​Ignore Rules

​Incremental Cache

​Examples

​Output

​Related Commands