Graphenium is a local, pre-flight linter and external architecture gate for AI coding agents.

It enforces structural compliance on AI assistants (such as Claude Code, Cursor, Aider, and Grok) by mechanically blocking code changes that violate your module boundaries, bypass your service layers, or introduce architectural drift.

Standard developer tools help agents find files. Graphenium prevents agents from creating architectural debt.

Without Graphenium (Vibe-Coding)        With Graphenium (Containment)
--------------------------------        -----------------------------
Agent edits files blindly               Agent validates design pre-flight
Agent ignores architectural layers      Graphenium blocks direct boundary violations
Constraints decay in long chats         External Datalog engine enforces strict rules
Reviewer hunts for bypassed layers      Reviewer gets deterministic scope-creep audits
CI checks only test passing             CI fails on architectural drift

Binary: gm
Schema: 0.2.0
Status: AST + Stack Graphs resolver stable, pre-flight policy engine stable, zero-drift delta gating stable, telemetry overlay experimental

---

Why Graphenium Exists: The Containment Gap

AI coding agents are highly efficient at local edits, but they suffer from structural blindness and context decay. Over a long chat session, an agent will lose track of your system instructions and optimize for the path of least resistance (e.g., writing a raw database call inside an HTTP controller to make a local test pass).

Relying on "soft" guardrails like CLAUDE.md or system prompts to maintain design patterns does not work. When context windows get full, these constraints are dropped.

Graphenium establishes external engineering governance. It operates outside the LLM context, treating architectural boundaries as a strict, compiled contract.

graph TD
    A[Agent Declares Design Spec] --> B[Graphenium Pre-Flight Check]
    B -->|Violation: Block| C[Reject with structural hints]
    B -->|Pass: Authorize| D[Agent Implements Code]
    D --> E[Graphenium Post-Edit Audit]
    E -->|Scope Creep| F[Fail Build / Block PR]
    E -->|Compliant| G[Approve for human review]

Loading

---

The Core Technical Lifecycle: Design-then-Verify

Graphenium enforces an explicit three-step compiler loop on the agent:

1. Declare Intent (Pre-Flight Spec): Before editing any code, the agent registers its planned changes (classes, methods, and dependencies) in a virtual planning workspace.
2. Transitive Policy Solving: Graphenium's engine runs a local Datalog solver to analyze the proposed virtual AST. If the design bypasses an intermediary architectural layer or uses banned symbols, Graphenium blocks the plan and provides structural feedback.
3. Zero-Drift Delta Gating: Even without a .graphenium/policy.json file, Graphenium applies in-memory modularity analysis (ΔQ) and surprise edge profiling to reject plans that mathematically degrade community structure.
4. Post-Facto Compliance Audit: After the agent writes the code, Graphenium parses the physical modifications, ensuring that the agent did not touch files outside the declared scope, introduce unplanned dependencies, or fail to implement its declared spec.

---

Quick Start

# 1. Initialize workspace
# Generates .grapheniumignore with standard project defaults
gm init

# 2. Build local AST and Stack Graphs index (No LLM keys required)
gm run . --no-semantic --no-viz

# 3. Diagnose codebase health and import resolution
gm doctor --graph graphenium-out/graph.json --resolution

# 4. Analyze structural neighborhoods
gm query "authentication flow" --budget 2000

# 5. Start the MCP server for AI coding agents
gm serve --graph graphenium-out/graph.json --watch

---

Installation

# From a local checkout
cargo install --locked --path .

# Or use the platform installer
curl -fsSL https://raw.githubusercontent.com/lambda-alpha-labs/Graphenium/main/install.sh | sh

Requires Rust 1.81 or later. Tree-sitter language grammars are compiled and bundled.

---

Core Technical Capabilities

1. AST-Proven Provenance (Facts vs. Heuristics)

Most AI developer tools use LLMs to guess how modules depend on each other, leading to hallucinations. Graphenium establishes an index of compiler-proven truth using Tree-sitter and Stack Graphs. Every relationship carries explicit provenance:

• EXTRACTED (AST-Proven): Compiler-backed facts (imports, type inheritance, explicit call signatures).
• INFERRED (Heuristics): Semantic leads that the agent is forced to verify.
• AMBIGUOUS (Collisions): Identifier collisions that force the agent to halt and inspect source files directly.

2. Datalog-Powered Policy Solving

Static linters can check direct imports, but they are blind to multi-hop architectural bypasses. Graphenium solves this by compiling your codebase structure into logical facts and running an embedded Datalog inference engine (src/analyze/query.rs & stdlib.dl).

It uses first-order logic and fixed-point iteration to mathematically prove boundary violations over an infinite number of dependency hops.

3. Zero-Drift Delta Gating (Topological Entropy Guardrails)

Even without explicit policy rules, Graphenium applies in-memory modularity analysis to every planning workspace. The delta engine compares physical-only and virtual (plan-overlay) subgraphs, computing Louvain modularity deltas (ΔQ) and profiling surprise edges. Plans that degrade community structure or introduce architectural shortcuts (cross-community, peripheral→hub) are rejected automatically.

Available via evaluate_delta_gate (MCP), validate_plan (orchestrator), and gm check --delta --plan <id> (CLI).

4. Declarative Structural Governance

Enforce system design boundaries at commit-time or in CI. You declare rules in .graphenium/policy.json at the root of your repository:

{
  "rules": [
    {
      "type": "forbidden_dependency",
      "from_pattern": "src/controllers/**",
      "to_pattern": "src/db/**",
      "reason": "Controllers must use services, not access DB directly"
    },
    {
      "type": "strict_layering",
      "layers": [
        "src/serve/**",
        "src/analyze/**",
        "src/extract/**",
        "src/model/**"
      ],
      "reason": "Respect tiered architecture: serve -> analyze -> extract -> model"
    }
  ]
}

Use gm check --plan <id> --strict to run pre-flight policy checks and post-facto compliance audits in CI.

# Topological delta gate (zero-config modularity protection)
gm check --delta --plan <id>

---

Technical Safeguards: Friction & Loop Mitigations

Traditional static analysis tools and natural-language guardrails (like CLAUDE.md or system prompts) fail when context windows fill up, leading to agent "vibe-coding" and rapid token consumption. Graphenium implements three structural safeguards to prevent developer friction and agent deadlock:

1. Mitigating the "Agent Deadlock" Loop (Pre-Flight Virtual ASTs)

• The Friction: If an agent is blocked by a strict linter, it can fall into a token-wasting trial-and-error cycle (Propose → Blocked → Tweak → Blocked).
• Graphenium's Mechanism: Graphenium prevents this loop by isolating change evaluations to a virtual planning workspace (create_planning_workspace). The agent registers its intent — classes, methods, and imports — before editing any physical files. Graphenium's pre-flight solver evaluates this virtual AST in milliseconds.
• If a violation is found, the agent does not receive a vague natural-language rejection. It receives structured, compiler-proven topological path violations (e.g., demonstrating the exact transitively bypassed service layers). This allows the agent to correctly refactor its design plan in memory before wasting LLM tokens on physical file rewrites.

2. Solving "Policy Rot" (Zero-Config Topological Delta Gating)

• The Friction: Declaring and maintaining strict architectural rules in a static JSON file (policy.json) introduces manual configuration overhead that fast-moving teams often neglect.
• Graphenium's Mechanism: If no .graphenium/policy.json file is present in the repository, Graphenium dynamically falls back to Zero-Drift Delta Gating (gm check --delta). Instead of relying on static directory regexes, Graphenium uses its native Louvain community-detection engine to evaluate your codebase's current structural cohesion.
• When an agent proposes a virtual plan, Graphenium calculates the modularity delta (ΔQ) and surprise coupling score of the new edges. It gracefully accepts your existing legacy complexity as the baseline, but mechanically blocks the agent from introducing new topological decay. No configuration files are required to protect your system's modularity.

3. Resolving Agent Integration Friction (Direct Skill-Folder Injection)

• The Friction: Standard stateless MCP setups mean agents can easily bypass sequential "three-step" design loops (Declare → Solve → Post-audit), requiring manual developer mediation.
• Graphenium's Mechanism: Graphenium circumvents this integration barrier by programmatically injecting its behavioral rules directly into the agentic runtime. During installation (install.sh or install.ps1), Graphenium copies its standard system skill instruction set (skills/graphenium/SKILL.md) directly into Claude Code's native skill directory (~/.claude/skills/graphenium/SKILL.md).
• This ensures that the moment the assistant handshakes with Graphenium, it ingests explicit, structured operating parameters on how to manage virtual workspaces and resolve topological violations, without requiring the developer to configure system prompts manually.

---

Language Support

Graphenium supports mixed repositories with Rust, Python, Go, JavaScript, TypeScript, Java, C, C++, and C#.

C# projects receive build-boundary awareness through .sln and .csproj parsing, enabling Graphenium to model assemblies, namespaces, and project references as structural boundaries.

---

MCP Setup

Integrate Graphenium directly into your agent's execution loop. For tools that spawn MCP from the project directory, use the scripts/graphenium-mcp launcher (rebuilds only when the index is missing, keeping startup instantaneous).

install -m 755 scripts/graphenium-mcp ~/.local/bin/graphenium-mcp

Claude Code

claude mcp add graphenium --scope user -- gm serve --graph /path/to/graphenium-out/graph.json --watch

Grok

Configure in ~/.grok/config.toml:

[mcp_servers.graphenium]
command = "/Users/<you>/.local/bin/graphenium-mcp"
args = []
enabled = true

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "graphenium": {
      "command": "gm",
      "args": ["serve", "--graph", "/path/to/graphenium-out/graph.json", "--watch"]
    }
  }
}

---

Detailed Documentation Map

Root

Document	Purpose
AI_SETUP.md	Step-by-step assistant setup playbook.
CONTRIBUTING.md	Contributor guidelines and module reference.
CHANGELOG.md	Release history and milestone summary.
SECURITY.md	Local-first security guarantees and vulnerability reporting.
MANIFEST.md	Complete package manifest indexing all documentation.

Core Documentation (docs/)

Document	Purpose
docs/GETTING_STARTED.md	Installation, initial codebase indexing, and MCP setup.
docs/AGENT_WORKFLOWS.md	Containment workflows: pre-flight, in-edit planning, and verification.
docs/CI_AND_GOVERNANCE.md	Enforcing architecture policies in CI pipelines.
docs/COMMAND_REFERENCE.md	Complete CLI syntax and configuration arguments.
docs/MCP_TOOLS.md	Behavior specifications for MCP clients.
docs/ARCHITECTURE.md	Indexing pipelines, C# project references, and Datalog evaluation.
docs/TRUST_MODEL.md	Under-the-hood details of AST-proven vs heuristic confidence.
docs/BENCHMARKING.md	Performance metrics: latency, token budgets, and scaling limits.
docs/COMPARISON.md	Why Graphenium is distinct from grep, AST tools, and GraphRAG.
docs/POSITIONING.md	Market positioning, target personas, and competitive differentiation.
docs/HARNESS_ADAPTER.md	Embedding Graphenium's structural engine as a library.
docs/WORKED_EXAMPLES.md	Case studies proving containment on real repositories.
docs/GRAPH_REPORT.md	Interpreting the generated codebase audit report.
docs/DOCUMENTATION_MAP.md	Full documentation ecosystem overview.

Agent Integration

Document	Purpose
skills/graphenium/SKILL.md	Agentic skill instructions and containment behavior rules.
contrib/harness-adapter/README.md	Embedding Graphenium's engine inside AI coding harnesses.

Case Studies (worked/)

Document	Purpose
worked/README.md	Overview of structural containment case studies.
worked/TEMPLATE.md	Template for documenting new codebase case studies.
worked/graphenium-self-analysis/README.md	Graphenium self-analysis: applying the containment engine to itself.
worked/graphenium-self-analysis/sample-queries.md	Sample query output on Graphenium's own codebase.

---

Contact & Enterprise

• Issues and Feature Requests: GitHub Issues
• Security Reports: security@graphenium.dev
• Design partners, enterprise pilots, and partnerships: hello@graphenium.dev

---

License

MIT. See docs/LICENSE.md.