Cross-service dependency graph for polyrepos. One command to answer: "if I change service X, what breaks?"
Most AI coding tools assume you have a monorepo. One codebase, one context, one agent that can see everything.
That's not reality for most companies.
Enterprises run polyrepo architectures -- separate services, separate teams, separate repos. Each codebase is big. Each has its own language, its own patterns, its own conventions. Merging them into a monorepo isn't happening.
So when you use AI coding tools, you hit a wall. You can get help inside one codebase at a time. But the coordination -- decomposing a feature across services, keeping contracts in sync, knowing what breaks when something changes -- that's the hard part. And nothing solves it.
This gets worse with every session. AI agents don't carry state between conversations. So every time you start a new session, the agent re-explores the same codebases to re-derive the same dependency information. In a 5-service polyrepo, that's 20-30 file reads across multiple repos just to understand "who calls whom" -- before any real work starts. That exploration burns through your context window and your token budget, and the agent still misses transitive dependencies because it can only see one repo at a time.
The missing piece is a dependency graph that works across repos, across languages, without manual maintenance. Something that answers: this service exposes these endpoints, these other services consume them, and if you change one, here's what breaks. Pre-computed once, available instantly in every session.
depgraf generates that graph. It scans your polyrepo, auto-detects each service's tech stack, extracts cross-service dependencies from source code via AST analysis, and validates that every consumed endpoint actually exists in the provider's API contract. Output is static JSON committed to your repo. One file read replaces dozens of exploratory searches -- your agent gets complete cross-service context in seconds, not minutes.
# 1. Initialize -- auto-detect stacks in your polyrepo
$ depgraf init --path .
Detected 4 workspaces:
order-service python-fastapi services/order-service
inventory-service python-fastapi services/inventory-service
storefront-app react-typescript apps/storefront
admin-app react-typescript apps/admin
Wrote depgraf.yaml
# 2. Run the full pipeline
$ depgraf sync
[generate] order-service: OpenAPI spec generated (fastapi)
[generate] inventory-service: OpenAPI spec generated (fastapi)
[extract] order-service: 6 consumed endpoints, 3 env vars
[extract] inventory-service: 1 consumed endpoint, 4 env vars
[extract] storefront-app: 8 consumed endpoints, 2 env vars
[extract] admin-app: 4 consumed endpoints, 1 env var
[aggregate] Built dependency graph: 4 nodes, 5 edges
[validate] 11 endpoint checks passed, 0 failed
# 3. Ask "what breaks if I change inventory-service?"
$ depgraf affected inventory-service
Direct consumers of inventory-service:
- order-service (POST /stock/reserve, POST /stock/deduct)
- storefront-app (GET /products, GET /products/{id})
Transitive consumers:
- admin-app (via order-service)# Install (pick one)
cargo install depgraf # from source
brew install depgraf/tap/depgraf # macOS/Linux
npx depgraf # via npm (no install needed)
# Initialize and run
cd your-polyrepo/
depgraf init
depgraf sync| Stack | Indicator | Detection |
|---|---|---|
python-fastapi |
pyproject.toml + fastapi dependency |
Auto |
python-django |
pyproject.toml + django dependency |
Auto |
react-typescript |
package.json + react-router-dom dependency |
Auto |
angular-typescript |
angular.json exists |
Auto |
java-spring |
build.gradle + spring-boot-starter-web |
Auto |
kotlin-ktor |
build.gradle.kts + io.ktor |
Auto |
node-express |
package.json + express dependency |
Auto |
node-nestjs |
package.json + @nestjs/core dependency |
Auto |
Need a stack that isn't listed? Write a stack pack or install a community one with depgraf pack install.
depgraf runs a five-stage pipeline, each stage feeding the next:
Detect --> Generate --> Extract --> Aggregate --> Validate
(stacks) (OpenAPI) (deps) (graph) (cross-check)
Detect identifies each workspace's language and framework from project files. Generate runs framework-native OpenAPI generators (with ast-grep fallback). Extract uses declarative ast-grep rules to find consumed endpoints, env vars, entity schemas, and route tables in source code. Aggregate builds a unified dependency graph with transitive affected_by computation via reverse BFS. Validate cross-checks every consumed endpoint against the provider's OpenAPI spec and reports mismatches.
All output is static JSON committed to the repo. Any tool that reads files -- AI agents, CI pipelines, dashboards -- can consume it.
- Usage Guide -- full CLI reference, config schema, output formats
- Architecture -- pipeline design, ast-grep integration, graph algorithms
- Stack Packs -- how to author and publish stack packs
- Contributing -- dev setup, testing, PR process
- SDD Integration -- using depgraf in a Spec-Driven Development workflow with GitHub Actions
| Version | Focus | Status |
|---|---|---|
| v0.1 | Core extraction + dependency graph | In progress |
| v0.2 | OpenAPI generation + contract validation | Planned |
| v0.3 | CI integration + community packs | Planned |
| v1.0 | Stable rule format, incremental extraction, watch mode | Planned |
See spec/ROADMAP.md for details.