boundrail

Boundrail

Architecture your agents can follow.

Boundrail maps the relationships in your code, checks the boundaries you declare, and shows what an edit changes. Use it from the CLI, in CI, or through MCP. Developers and coding agents get the same source locations, rule reasons, and repeatable checks.

Quickstart · Architecture rules · For coding agents · Service model · Evidence and limits · Full guide

Review the architectural change

An import diff should explain the change. Boundrail keeps the old and new evidence together: added and removed dependencies, module membership, deciding rules, and source locations.

# Capture the baseline before editing.
mkdir -p .archgraph
boundrail scan . --engine native --symbols --rules layout.yaml -o .archgraph/before.json

# After editing, collect with the same options and review the change.
boundrail scan . --engine native --symbols --rules layout.yaml -o .archgraph/after.json
boundrail diff .archgraph/before.json .archgraph/after.json --html changes.html --fail-on new-forbidden

Open changes.html to inspect the comparison. Removed imports remain selectable. A moved line is labelled Evidence only. Policy changes have their own notice, and missing collection metadata produces an Unverified comparison. A failing gate still writes the HTML for review.

The screenshot comes from a native scan before and after an actual fixture edit. It is not a production traffic trace. Comparison behavior and compatibility.

What you can do

Quickstart

Build the checked-out source with stable Rust:

git clone https://github.com/dogebonker/archgraph.git
cd archgraph
cargo +stable install --path . --locked --bin boundrail

boundrail report /path/to/your/project --engine native

report prints a summary and writes a JSON document and an offline HTML map in .archgraph/. Open the HTML file in your browser. The native engine is experimental. Go import collection still uses the Go toolchain for read-only package metadata. Run the remaining examples from your project's root directory.

Boundrail was previously named Archgraph. The repository URL and .archgraph/ project state retain their existing names for compatibility. Upgrade notes · Installation and collector requirements.

Explore the Next.js map or the public-repository gallery. This earlier capture uses the Archgraph name.

The map supports zoom, module selection, remembered positions, and a file-level view. Its What-if mode previews file moves without changing source. Rust simulations and the project's build and tests remain the checks for an actual refactor.

Make the boundaries explicit

The graph describes observed dependencies. Your policy describes which dependencies are allowed. Put the agreed constraints in layout.yaml:

version: 1
layers:
  - src/domain/**
  - src/application/**
  - src/adapters/**
  - src/main.ts
forbid:
  - id: domain-no-adapters
    from: src/domain/**
    to: src/adapters/**
    reason: Keep domain logic independent of I/O adapters.
public:
  - module: src/orders/**
    entries: [src/orders/index.ts]

boundrail check . --rules layout.yaml

Rules can also constrain external packages and indirect reachability. Named claims retain their reasons and ADR sources. Inferred layouts and the five architecture presets help you draft policy, but observed dependency direction does not automatically become intended architecture. Rule syntax, precedence, and examples · ADR import and lifecycle checks.

Give agents a project workflow

Analyze the repository into an inactive skill draft:

boundrail skill draft .

Review .archgraph/drafts/project-architecture/SKILL.md and its policy references. With a reviewed root layout.yaml in place, regenerate the draft and adopt it:

boundrail skill draft .
boundrail skill adopt .

Adoption installs .agents/skills/project-architecture/SKILL.md. It verifies policy fingerprints and preserves notes outside the generated block. Drafting never changes active policy or source. When no layout exists, the proposal stays in the draft directory until you review it. Draft, review, adopt, and update.

Check edits as they happen

boundrail hook install --agent codex
boundrail serve . --engine native --symbols

Keep the daemon running and start the agent in another terminal. Claude Code and Codex receive bounded context before edits and checks for new violations afterwards. Existing findings remain advisory. Codex requires explicit hook trust through /hooks. Cursor and OpenCode use --feedback-only. Host contracts, recovery, and the scripted demo.

Connect through MCP

claude mcp add --transport stdio boundrail -- boundrail mcp . --engine native --symbols

The ten read-only tools cover context selection, relevant rules, explanations, target claims, change checks, PR review, service evidence, fix proposals, move simulation, and verification. Answers have explicit budgets, omissions, and unavailable states. Claude Code, Cursor, and Codex configurations.

Five bundled skills cover general architecture analysis, context, regression checks, fixes, and policy drafting. They complement the generated project skill: boundrail, boundrail-context, boundrail-guard, boundrail-fix, and boundrail-rules.

For Codex, copy the five folders together so their sibling links and scripts remain available:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/boundrail* "${CODEX_HOME:-$HOME/.codex}/skills/"

Keep local customizations before copying updates. For a project install or another agent client, use that client's skill directory. Installing skills does not install the binary or enable hooks.

See services and infrastructure clients

Infer a source-based application model without adopting an application SDK or running the application:

boundrail services . --format json -o services-report.json
boundrail render services-report.json -o services.html

A NATS reference model with explicit service boundaries. This is static relationship evidence, not observed runtime traffic.

The offline catalog shows services, directed calls, owned client usages, confidence, and source locations. Supported patterns cover database and cache clients, HTTP calls, queue publishers and consumers, and routes. Configuration, wrappers, dynamic values, and unsupported transports can hide genuine relationships.

A services.yaml manifest can override service boundaries, declare relationships such as gRPC, and forbid service calls or explicit infrastructure package usage:

version: 1
services: [api, worker]
edges: []
forbid:
  - id: worker-no-postgres
    from: worker
    to: pkg:pg
    reason: Database access belongs to the API.

# Check every observed violation against authored service rules.
boundrail services . --manifest services.yaml --fail-on-forbidden

# Or compare two saved reports and fail only on newly observed violations.
boundrail diff services-before.json services-after.json --fail-on new-forbidden

Both service evidence sets use the later report's rules. Policy changes are reported separately. Client usage does not establish physical database ownership, and a missing edge does not prove independence. Service rules, inference limits, and report behavior.

Language and engine coverage

Import analysis offers reference collectors and an experimental native engine. Their coverage and tool requirements differ. Rust relationships describe source coupling, and Elixir macros and dynamic references can hide dependencies. Reference TypeScript collection can execute a repository-selected tool through npx, so use trusted code or a sandbox. Engine selection and limits.

More ways to inspect the code

Evidence and limits

Boundrail provides repeatable checks and inspectable evidence. We do not claim that it has proven faster agents, complete architecture discovery, or semantic correctness.

Reports show at least these relationships within the collected scope. Folder grouping can misrepresent deployment or ownership boundaries. Inferred suggestions require review, missing provenance stays visible, and semantic changes still need the project's build and tests.

Historical screenshots, measurements, and transcripts retain the name used when they were captured. Full command guide · Changelog · Third-party notices.

License

MIT or Apache-2.0, at your option.