RepoGraph Protocol

Machine-readable context for human and AI developers.

RepoGraph turns a repository into a structured knowledge graph — modules, layers, dependencies, APIs, risks, ownership, and architecture rules — so developers, CI, and AI tools work from trusted context, not guesses.

Animated preview. Record a terminal demo with docs/assets/RECORD_DEMO.md.

---

Install

Requires Node.js 20+

npm install -g @repographprotocol/cli@0.5.0
repograph --version

One-off (no global install):

npx @repographprotocol/cli@0.5.0 --help

Use 0.5.0 or later. Requires .NET SDK for full C# / EF analysis (Roslyn ships inside the CLI bundle). @repographprotocol/cli@0.2.0 has a known runtime issue on global install; prefer 0.2.1+.

---

Quick start (60 seconds)

cd your-repo
repograph init --template clean-architecture-csharp-angular
repograph validate
repograph scan
repograph sync
repograph check
repograph export --format cursor

Step	What you get
init	.repograph/*.yml — modules, layers, rules, AI hints
scan	graph.json, Mermaid diagram, context pack
sync	Updates ownership, risk, glossary from scan + CODEOWNERS
check	Fails CI when architecture rules break
export	Cursor rules / markdown for AI assistants

Full guide: docs/quickstart.md

---

Examples

Three real examples are included — pick the stack closest to yours:

Example	Stack	Highlights
clean-architecture-csharp-angular	.NET + Angular	Layer violations, Roslyn-ready
nodejs-layered-api	TypeScript API	api → services → domain
dotnet-modular-monolith	.NET modular	Catalog + Orders modules

cd examples/nodejs-layered-api
repograph scan && repograph check

Index: examples/README.md

---

GitHub Actions

Add to pull requests:

name: RepoGraph

on:
  pull_request:
    branches: [main]

jobs:
  repograph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: baasith6/RepoGraph-Protocol/action@v0.5.0
        with:
          fail-on: error
          comment-pr: true

---

CLI commands

Command	Description
repograph init	Create .repograph and starter config
repograph validate	Validate YAML against JSON Schema
repograph doctor	Health check for RepoGraph setup
repograph scan	Scan repo and generate graph
repograph sync	Scan + sync ownership, risk, glossary
repograph check	Enforce architecture rules
repograph diff	Compare graphs between git refs
repograph explain	Explain project, module, or file
repograph list	List modules, layers, or violations
repograph visualize	Mermaid dependency diagrams
repograph stats	Repository metrics
repograph export	json, markdown, mermaid, cursor, claude, copilot
repograph prompt	Task-aware AI context (--mode short|full|strict)
repograph impact	Blast radius for a file change (--json)

---

The .repograph protocol

.repograph/
  project.yml
  modules.yml
  architecture.yml
  rules.yml
  tests.yml
  ai.yml
  api.yml
  database.yml
  risk.yml
  ownership.yml
  glossary.yml
  decisions/
  generated/
    graph.json
    graph.mmd
    context-pack.md
    context-pack.short.md

• AI context guide: docs/ai-context.md
• Spec v0.1: docs/spec/0.1.0.md
• Spec v0.2: docs/spec/0.2.0.md

---

Integrations

MCP (Cursor, Claude, etc.)

See docs/integrations/mcp.md. Tools: repograph_get_graph, repograph_explain, repograph_list_violations, repograph_impact, repograph_prompt, repograph_scan.

VS Code

See docs/integrations/vscode.md — Explorer views and Copy Task Prompt.

Other CI

• Azure DevOps: docs/ci/azure-pipelines-repograph.yml
• GitLab: docs/ci/gitlab-repograph.yml

---

Releases and changelog

We publish GitHub Releases with human-readable notes so you can see what changed without reading the whole repo.

Version	Notes
v0.5.0	EF database.yml, Angular routes, Roslyn in npm CLI
v0.4.0	Task-aware prompt/impact, Claude/Copilot export
v0.3.0	Scan cache, graph drift validate, demo GIF
v1.0.0	First public release (recommended starting point)
v0.2.1	npm CLI runtime fix
v0.2.0	diff, Roslyn, protocol 0.2
v0.1.0	Initial protocol + CLI

Full history: CHANGELOG.md · Release index: docs/releases/README.md

---

Contributing

Contributions are welcome. See CONTRIBUTING.md and SECURITY.md.

---

License

Apache-2.0 — see LICENSE for full text.

---

Suggested GitHub topics

When promoting the repo, add topics such as: architecture, static-analysis, developer-tools, ai-tools, cursor, clean-architecture, dotnet, typescript, monorepo, github-actions, knowledge-graph.

Full list: .github/TOPICS.md