Skip to main content

​
What is DevGraph?

DevGraph builds a hybrid project graph from your repo. It scans folders, files, and mixed repo assets, preserves devgraph-* blocks as the authoritative service layer, and emits a graph that works for humans, CLIs, Studio, and coding agents. One command gives you service metadata, file-level structure, and graph analysis surfaces that stay grounded in the repo.

​
Key Features

Hybrid Build

Build a graph from directories, files, and globs with service and file nodes in one output.

Service Layer

Use devgraph-service, devgraph-api, and devgraph-env blocks to define authoritative service metadata.

Graph Analysis

Review GRAPH_REPORT.md and use devgraph query for focused architecture retrieval.

Agent Handoffs

Generate skills that guide agents through graph questions, focused queries, and Markdown handoff briefs.

Studio

Explore service and file nodes interactively with filters for community, provenance, and ownership.

​
Generated Outputs

When you run devgraph build, DevGraph writes the following files to .devgraph/:
FileDescription
graph.jsonMachine-readable output containing top-level services, apis, and knowledgeGraph
summary.mdHuman-readable service overview
GRAPH_REPORT.mdHybrid graph analysis with god nodes, surprising connections, bridge nodes, and coverage gaps
agents/*.mdPer-service context files for coding assistants
system.mmdMermaid diagram of the build pipeline and service relationships
codemap.mmdMermaid 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

​
How Blocks Fit In

devgraph-* blocks still matter. They are not a separate build mode. They are the authoritative service layer inside the hybrid graph:
  • devgraph-service defines service identity, commands, dependencies, and optional owned paths
  • devgraph-api attaches routes to services
  • devgraph-env attaches environment variables to services
The rest of the build pipeline adds file nodes and graph relationships around that service layer.

​
Agent Context

devgraph agents --format skills writes a .skills/ directory for AI coding tools. It includes:
  • querying-architecture for graph-aware commands and references
  • service-specific skills for commands, APIs, owned paths, and dependencies
  • orchestrating-devgraph-context for multi-agent handoffs based on GRAPH_REPORT.md and devgraph query
The orchestration skill uses graph-derived questions and a Markdown handoff template so another agent can continue with known context, evidence, decisions, and open questions.

​
Next Steps

Quickstart

Build your first hybrid graph and inspect the outputs.

CLI Commands

Learn the build, query, Studio, and agent workflows.

Agent Skills

Generate repo-grounded skills and handoff briefs for coding agents.