Skip to main content

​
Installation

Install DevGraph globally or run it directly with bunx: 
pnpm add -g devgraph

​
1. Add service blocks where they help

devgraph build scans your repo by default. Blocks are optional, but they are the authoritative service layer when you want named services, commands, APIs, environment variables, or explicit owned paths. Example: 
```devgraph-service
name: api
type: node
paths:
  - services/api
commands:
  dev: pnpm dev
  build: pnpm build
depends:
  - database
```

```devgraph-api
service: api
routes:
  GET /health: Health check
  GET /api/users: List users
  POST /api/users: Create user
```

```devgraph-env
service: api
vars:
  PORT: "3000"
  DATABASE_URL: postgresql://localhost:5432/mydb
```

​
2. Build the graph

devgraph build .
You can also pass specific directories, files, or globs: 
devgraph build apps packages docs/**/*.md

​
3. Check outputs

Outputs are generated in .devgraph/: 
.devgraph/
  |- graph.json
  |- summary.md
  |- GRAPH_REPORT.md
  |- agents/
    |- api.md
  |- system.mmd
  |- codemap.mmd
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

​
4. Query the graph

Use devgraph query when you want a focused answer from the built graph: 
devgraph query "which files belong to api?"
devgraph query "what documents auth?" --budget 250 --dfs
The output is a bounded text subgraph with node labels, relations, provenance, and source paths.

​
5. Visualize with Studio

Launch the interactive graph viewer: 
devgraph studio
Studio opens at http://localhost:9111 and shows:
  • service and file nodes
  • search plus graph filters
  • community, provenance, and ownership views
  • node detail panels with evidence and neighbors

​
6. Generate agent skills

Generate reusable skills for AI coding tools: 
devgraph agents --format skills
This writes .skills/ with architecture, service, and orchestration skills. The orchestration skill tells agents how to use GRAPH_REPORT.md, run focused devgraph query prompts, and produce a Markdown handoff brief for another agent.

​
Next Steps

Build Command

Learn about .devgraphignore, --compare, and hybrid outputs.

Query Command

Use graph retrieval instead of broad file search.

Agent Skills

Generate architecture, service, and orchestration context for AI agents.