entrix

Install

Choose one installation path:

Claude Code Plugin (recommended)

/plugin marketplace add phodal/entrix
/plugin install entrix@entrix

Restart Claude Code after plugin installation.

Standalone CLI (uv or pip)

uv tool install entrix
# or
pip install entrix

entrix --help

If you want Claude Code MCP integration in the current repository after installing the CLI:

entrix install --repo .

Requires Python 3.10+. uv is only needed for the uv / uvx workflow.

• codify quality gates and architecture constraints as reusable guardrail specs
• run checks by fast / normal / deep tiers
• run change-aware checks on diffs with weighted scoring and hard gates
• route risky changes to deeper validation with review-trigger
• optionally add graph-based impact, test-radius, and review context analysis

• checks run before risky code lands
• each run generates evidence
• policy can hard-stop, warn, or escalate to human review automatically

Lifecycle View

Additional design context:

• tools/entrix/docs/adr/README.md: Entrix architecture decisions and rationale

Terminology

Entrix uses fitness in the evolutionary architecture sense: a fitness function is an executable check that measures whether a codebase still satisfies a quality or architecture goal. In product-facing language, you can think of these as versioned quality guardrails.

Requirements

• Python 3.10+
• Git repository context for commands that use --base HEAD~1

Optional:

• uv for uv tool install ... and uvx ...
• pip install entrix[graph] for graph commands

Advanced Installation

Alternate CLI Invocations

uv tool install entrix
# or
pip install entrix

uvx entrix --help
uvx entrix run --tier fast
uvx entrix run --tier normal --stream failures
uvx entrix run --tier normal --stream all
uvx entrix review-trigger --base HEAD~1

pip install entrix[graph]
pip install entrix[mcp]
pip install entrix[dev]

uvx entrix install --repo .

First Run

1. Create a guardrail spec

By default, entrix run looks for specs under the current project's:

docs/fitness/*.md

When docs/fitness/manifest.yaml is present, Entrix uses the manifest as the source of truth. That allows nested evidence files such as docs/fitness/runtime/observability.md and docs/fitness/runtime/performance.md.

Example docs/fitness/code-quality.md:

---
dimension: code_quality
weight: 20
threshold:
  pass: 90
  warn: 80
metrics:
  - name: lint
    command: npm run lint 2>&1
    hard_gate: true
    tier: fast
    description: ESLint must pass

  - name: unit_tests
    command: npm run test:run 2>&1
    pattern: "Tests\\s+\\d+\\s+passed"
    hard_gate: true
    tier: normal
    description: unit tests must pass
---

# Code Quality

Narrative evidence, rules, and ownership notes can live below the frontmatter.

Advanced metric fields

Beyond the basic fields shown above, each metric in the frontmatter supports additional options:

metrics:
  - name: api_contract
    command: npm run test:contract 2>&1
    hard_gate: false
    tier: normal
    description: API contract tests

    # Execution scope — where this metric is authoritative
    # Values: local, ci, staging, prod_observation
    execution_scope: ci

    # Timeout in seconds (null = no limit)
    timeout_seconds: 120

    # Gate severity: hard, soft, advisory
    gate: soft

    # Evidence type: command, test, probe, sarif, manual_attestation
    evidence_type: test

    # Confidence level: high, medium, low, unknown
    confidence: high

    # Signal stability: deterministic, noisy
    stability: deterministic

    # Fitness kind: atomic (single check) or holistic (system-wide)
    kind: atomic

    # Analysis mode: static (code structure) or dynamic (runtime)
    analysis: dynamic

    # Owner responsible for this metric
    owner: team-platform

    # Only run when these file patterns change
    run_when_changed:
      - "src/api/**"
      - "openapi.yaml"

    # Temporary waiver to bypass a failing metric
    waiver:
      reason: "Known flaky test, fix tracked in issue #42"
      owner: team-platform
      tracking_issue: 42
      expires_at: "2025-06-01"

2. Run the checks

entrix run --tier fast
entrix run --tier normal
entrix run --tier normal --scope ci --dimension code_quality --dimension testability
entrix run --tier fast --metric eslint_pass --metric ts_typecheck_pass
entrix run --changed-only --base HEAD~1
entrix validate

Use --metric when you want to run only specific metric names without creating a temporary dimension file split. Commands that use --base HEAD~1 must run inside a git repository with a valid base revision.

3. Add review triggers

By default, review-trigger loads the current project's:

docs/fitness/review-triggers.yaml

Example docs/fitness/review-triggers.yaml:

review_triggers:
  - name: high_risk_directory_change
    type: changed_paths
    paths:
      - src/core/acp/**
      - src/core/orchestration/**
      - services/api/**
    severity: high
    action: require_human_review

  - name: oversized_change
    type: diff_size
    max_files: 12
    max_added_lines: 600
    max_deleted_lines: 400
    severity: medium
    action: require_human_review

Run it:

entrix review-trigger --base HEAD~1
entrix review-trigger --base HEAD~1 --json

Example output:

{
  "human_review_required": true,
  "base": "HEAD~1",
  "changed_files": [
    "services/api/src/routes/acp_routes.rs"
  ],
  "diff_stats": {
    "file_count": 13,
    "added_lines": 936,
    "deleted_lines": 20
  },
  "triggers": [
    {
      "name": "high_risk_directory_change",
      "severity": "high",
      "action": "require_human_review",
      "reasons": [
        "changed path: services/api/src/routes/acp_routes.rs"
      ]
    }
  ]
}

Develop from the Routa.js checkout

If you are using the copy of entrix vendored in the Routa.js monorepo, the current repository workflow is:

pip install -e tools/entrix

PYTHONPATH=tools/entrix python3 -m entrix --help
PYTHONPATH=tools/entrix python3 -m entrix run --tier fast
PYTHONPATH=tools/entrix python3 -m entrix review-trigger --base HEAD~1

Most local hooks and helper scripts in this repository use the PYTHONPATH=tools/entrix python3 -m entrix ... form so they can run directly from the monorepo checkout without requiring a separately installed global binary.

Develop the package itself from source

If you are working on the entrix package source itself, clone this repository and install it from the repository root.

From the repository root:

git clone https://github.com/phodal/entrix.git
cd entrix
uv pip install -e .

With pip:

git clone https://github.com/phodal/entrix.git
cd entrix
pip install -e .

CLI Reference

Most repositories only need these three commands:

• entrix run: execute guardrail checks from docs/fitness/*.md
• entrix validate: validate the guardrail configuration
• entrix review-trigger: escalate risky diffs to human review

Use entrix analyze long-file for oversized-file structure analysis and entrix graph ... for graph-backed impact analysis.

Example Packs

Entrix includes copyable examples under examples/:

• examples/file-length-hook/: pre-commit file budget hook
• examples/frontend-quality-pack/: layered frontend quality gates with review-trigger guidance

entrix run

Runs dimension-based guardrail checks loaded from docs/fitness/*.md.

Common flags:

entrix run --tier fast
entrix run --parallel
entrix run --dry-run
entrix run --verbose
entrix run --format ascii
entrix run --format rich
entrix run --changed-only --base HEAD~1
entrix run --files src/app.ts src/lib.ts
entrix run --output report.json
entrix run --output -              # JSON to stdout
entrix run --min-score 90

Use --output to write a JSON report to a file (or - for stdout), useful for CI artifact collection. Use --files to pass an explicit list of changed files for incremental metric selection. Use --format ascii for a zero-dependency visual scorecard, or --format rich for richer terminal rendering when rich is installed (pip install entrix[visual]).

entrix install / entrix init

Generate .mcp.json for Claude Code MCP integration in a target repository.

entrix install --repo .
entrix init --dry-run

entrix serve

Run the Entrix MCP server over stdio.

entrix serve

entrix validate

Checks that dimension weights sum to 100%.

entrix validate

entrix review-trigger

Evaluates governance-oriented trigger rules for risky changes.

Common flags:

entrix review-trigger --base HEAD~1
entrix review-trigger --json
entrix review-trigger --fail-on-trigger
entrix review-trigger --config docs/fitness/review-triggers.yaml

entrix analyze long-file

Structural analysis for oversized or explicit source files. Returns ClassMap / FunctionMap payloads showing classes, methods, and standalone functions with line spans.

Supported languages: Python, Rust, Go, Java, and TypeScript/JavaScript (including tsx / jsx files).

entrix analyze long-file --files src/app.ts src/lib.ts
entrix analyze long-file --json
entrix analyze long-file --config file_budgets.json --strict-limit
entrix analyze long-file --min-lines 100

When no --files are given, the command auto-discovers files that exceed their configured line budget.

entrix graph ...

Graph-backed commands support building the code graph, querying relationships, impact analysis, test radius estimation, commit history analysis, and AI-friendly review context generation.

Requires the optional graph dependency: pip install entrix[graph].

entrix graph build

Build or update the code graph.

entrix graph build --base HEAD~1
entrix graph build --build-mode full --json

entrix graph stats

Show graph statistics (node and edge counts).

entrix graph stats
entrix graph stats --json

entrix graph impact

Analyze the blast radius of changed files.

entrix graph impact --base HEAD~1
entrix graph impact --base HEAD~1 --depth 3 --json

entrix graph test-radius

Estimate which tests are affected by changed files.

entrix graph test-radius --base HEAD~1
entrix graph test-radius --base HEAD~1 --max-targets 50 --json

entrix graph query

Run a structural query against the code graph.