Code becomes architecture facts

One local librarian for every project you care about.

ArchGuardian turns repositories into project-owned architecture metadata and lets a local Librarian index, compare, and query that truth through CLI and MCP. Today it already covers graph snapshots, dependency contracts, identity resolution, graph diffs, and federated lookups across registered projects.

Start in 3 steps See proof Open demo guide

`.archguardian/` is canonical Committed and working graphs stay visible Federation is derived locally CLI and MCP share one backend

Operating model

Project-owned facts. Local orchestration. Cross-repo visibility without a central source of truth.

2 Graph states

2 Interfaces

3 Query scopes

0 Required central services

North star

Think of it as a librarian with a shelf of project books.

Each repository owns its own architecture book. ArchGuardian catalogs the books you add, keeps committed and working truth in view, and gives engineers or agents structured evidence instead of guesswork.

Why this exists

AI is speeding up implementation faster than teams can preserve architectural visibility.

Most teams do not need another generic assistant. They need a way to derive architecture from source, keep it with the project, and query it across many repositories without inventing a central platform first. ArchGuardian is built first for polyrepo engineers, platform or architecture leads, and AI-assisted developers who need ownership and dependency context before they act.

The polyrepo tax

Developers can change one repo without seeing who depends on it elsewhere. Cross-project impact remains a manual search problem.

Architecture docs decay

Handwritten docs drift quickly. The only durable source is the code and configuration that actually define the system.

General AI lacks system memory

It can generate local code, but it does not reliably know ownership, aliases, blast radius, or downstream contracts.

Start

Start with one repo, then grow into an estate view.

The first run is small: install the CLI, scan a repository, then add projects to the local Librarian. From there you can inspect graph state, contract drift, federation, and estate gaps without standing up any central service.

Install the local tool

Use one editable install for both the CLI and the MCP server.

Scan a repository

Write validated project-owned artifacts under `.archguardian/` so the repo carries its latest architecture snapshot.

Register and query locally

Add repos to the Librarian and start checking graph status, contract drift, ownership, impact, and estate gaps.

Quickstart

Small surface area, real outputs.

`pip install -e ".[dev]"` `ag scan .` `ag add project /path/to/repo` `ag list projects --simple` `ag get contract --simple`

Good first checks

Use the current checkout before you think about federation.

`get status` for graph presence and staleness
`get contract` for manifest-vs-scan drift
`diff graph --summary` for pre-commit structural change
`analyze gaps` once you have a small registered estate

Core model

ArchGuardian has four layers, each with a clean boundary.

The important shift is ownership. Projects own deterministic facts. The local app owns registration, indexing, CLI, MCP, and optional reasoning. Federation is rebuilt from the project layer rather than replacing it.

Project Core

The canonical architecture data lives in the repo under `.archguardian/`.

`arch_manifest.yaml` for identity
`system.graph.json` for deterministic graph facts
optional `service_aliases.yaml`

Sentinel

The scan and refresh engine that turns source and config into validated project metadata.

extractors and signatures
evidence levels
identity candidate extraction

Librarian

The local hub that registers projects, loads their graphs, and exposes one backend for CLI and MCP.

local project registry
graph loader and index
project and federated queries

Federation

A derived view across registered projects. Local-first by default, optionally extended later with imported snapshots.

rebuildable from project facts
never the canonical source of truth
ready for agents through MCP

Workflow

Use normal Git workflows. Make architecture metadata travel with the repo.

This is the key operational advantage. Developer A scans and commits project metadata. Developer B pulls the same repository, adds it to their local Librarian, and immediately benefits from the latest committed architecture snapshot.

Add a project

The Librarian registers a local repository and checks whether `.archguardian/` data already exists.

Scan or refresh

The Sentinel scans source and config, then writes validated project-owned artifacts.

Commit the graph

The project shares its latest architecture snapshot through Git, just like any other reviewed artifact.

Federate locally

The Librarian merges all registered project graphs into a local federated index for project and cross-project queries.

Truth state A

Committed graph

The versioned baseline the team has shared through Git.

portable
reviewable
safe for CI baseline checks

Truth state B

Working graph

The latest local scan for the current checkout, including uncommitted changes.

useful for branch impact
useful before commit
must stay visible alongside committed truth

What lives in the repo

Project-owned

manifest
graph snapshot
alias map

What lives locally

Librarian-owned

project registry
index state
private settings and reasoning state

Capabilities today

ArchGuardian already does more than emit a graph file.

It can scan real repositories into deterministic project artifacts, compare committed and working graph states, review dependency-contract drift, resolve identities, and answer project or federated queries over one local registry. CLI and MCP are two surfaces over that same backend.

Scan real repo facts

Source, build, and runtime configuration are pulled into validated project-owned artifacts instead of free-form notes.

Python, Java, Kotlin, shell, Docker, Compose, TypeScript, TSX, Gradle, and Maven coverage
project typing and identity metadata under `.archguardian/`
scanner diagnostics for unresolved, orphaned, and stale linkage signals

Review the current checkout

The local graph is useful before commit, not just after a snapshot lands in Git.

graph summaries and module inspection
dependency-contract drift against manifest expectations
working-versus-committed graph diff for the current checkout

Reason across a local estate

Once projects are registered, the Librarian can answer ownership and dependency questions across repositories without inventing a central platform.

federated identity lookups and ambiguity handling
impact radius, dependency, estate-gap, and pattern queries
collision reporting and estate-level registry metrics

Local librarian registry

Register projects and review the estate you have on hand.

These operations manage the local catalog, refresh working copies, and surface estate-level health without changing ownership of project facts.

CLI: `add project <path>` CLI: `list projects` CLI: `refresh project --all` CLI: `remove project --all` MCP: `add_project(path)` MCP: `list_projects()` MCP: `refresh_project(project_ref)`

Current checkout and project review

Inspect what changed, what is owned, and where drift has appeared.

These commands work against project-owned data under `.archguardian/` and make the local checkout useful for review before anything is committed.

CLI: `scan .` CLI: `get graph --summary` CLI: `get contract` CLI: `get status` CLI: `diff graph --summary` MCP: `get_graph(summary=True)` MCP: `get_dependency_contract()` MCP: `diff_graph(summary=True)` MCP: `get_project_graph(project_ref)` MCP: `resolve_project_identity(project_ref, alias)`

Cross-project queries

Read the derived map across all registered projects.

Federated tools expose ownership, inbound references, dependency gaps, and search over the local estate without promoting the federation layer into canonical truth.

CLI: `get federation <identity>` CLI: `get impact-radius <identity>` CLI: `analyze gaps --simple` CLI: `list collisions` CLI: `resolve identity <alias>` MCP: `get_federation(identity)` MCP: `get_federated_dependencies(service_name)` MCP: `get_impact_radius(service_name)` MCP: `analyze_estate_gaps()` MCP: `list_identity_collisions()` MCP: `resolve_identity(alias)` MCP: `search_patterns(keyword)`

Optional reasoning

Use LLMs after structured retrieval, not before.

Reasoning is most useful once the graph, contract drift, and ownership signals have been retrieved first. The model should explain evidence, not invent it.

MCP: `lint_architecture(diff, model?)` Input: diff or snippet plus graph facts Bias: evidence beats narrative Future: graph-backed workflow companions

Proof

What ArchGuardian can prove today, not just describe.

The current product surface already answers practical review questions: what changed in this checkout, who owns a target identity, where ambiguity remains, and which observed dependencies still have no registered owner.

Checkout drift

Show structural change before commit

Compare the working tree with the committed graph and surface changed nodes, observed dependency movement, and contract state changes.

CLI: `diff graph --summary` MCP: `diff_graph(summary=True)`

Cross-repo ownership

Resolve owners without hiding ambiguity

Federated lookups report `resolved`, `ambiguous`, or `unowned` so review can stay grounded in actual ownership evidence.

CLI: `get federation <identity>` MCP: `get_federation(identity)`

Impact review

Trace likely blast radius fast

Impact queries help reviewers see what identities or projects would be touched by a service or dependency change.

CLI: `get impact-radius <identity>` MCP: `get_impact_radius(service_name)`

Estate dark matter

Separate external facts from real gaps

Estate-gap analysis highlights observed-but-unowned identities and separates likely libraries or runtimes from unresolved linkage work.

CLI: `analyze gaps --simple` MCP: `analyze_estate_gaps()`

Trust rule

Conservative by design.

When ownership is unclear, ArchGuardian keeps that uncertainty explicit instead of guessing through it. Federation is derived, not canonical. Evidence beats narrative, especially when the answer is incomplete.

Roadmap

What comes next as ArchGuardian turns into a daily engineering surface.

The next stretch is about making cross-repo answers more trustworthy and easier to use in real review workflows. That means sharper linkage, better drift signals, stronger extension points, and then broader reach once the local model is dependable.

Sharpen cross-repo linkage

Resolve more config-backed identities, improve provenance for inferred edges, and make unowned, unresolved, and stale signals obvious during estate review.

Make review workflows routine

Turn graph status, contract drift, and graph diff into everyday tools for local development and pull-request review rather than specialist commands.

Open the scanner surface carefully

Introduce a stable plugin contract and fixture-backed validation so new extractors can be added without weakening determinism or graph semantics.

Bring graph checks into CI

Use graph diffs, impact signals, and contract review to produce machine-readable architecture checks that fit existing delivery pipelines.

Extend federation beyond one machine

Add import and export of graph snapshots, then optional shared registry workflows, once local identity semantics are strong enough to trust outside one laptop.

Add workflow companions later

Loop breakers, task coaching, and session journals make sense as downstream companions once graph truth and review workflows are strong enough to anchor them.

FAQ

Short answers for the architectural choices that matter.

Why not keep the graph only in a central service?

Because the project needs to stay portable, reviewable, and useful offline. Git sharing of deterministic project facts is a feature, not a workaround.

Is the Librarian the source of truth?

No. The Librarian is the local orchestrator over project-owned facts. Federation is derived and rebuildable.

Does this replace Copilot or Cursor?

No. It gives agents and editors a graph-backed architecture layer they do not have today.

Why keep both committed and working graphs?

Because teams need a shared baseline and developers need branch-level truth before they commit.

Do I need networked federation from day one?

No. Local-first is the default. Shared federation is an extension, not a prerequisite.

Where should LLMs fit?

After structured graph retrieval. Facts should come from the project contract and federated index first.