Entrix

<h1 align="center">Entrix</h1> <p align="center"> <strong>Shift quality from manual review to executable change guardrails.</strong> </p> <p align="center"> <a href="https://pypi.org/project/entrix/"> <img src="https://img.shields.io/pypi/v/entrix.svg" alt="PyPI version" /> </a> <a href="https://pypi.org/project/entrix/"> <img src="https://img.shields.io/pypi/pyversions/entrix.svg" alt="Python versions" /> </a> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" /> </a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/phodal/entrix/main/docs/lifecycle.svg" alt="Entrix Lifecycle" width="85%" /> </p> <br>

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.

<details> <summary><strong>What it does</strong></summary> <br>

• codify quality gates and architecture constraints as reusable fitness 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

</details> <details> <summary><strong>Guardrails in the change lifecycle</strong></summary> <br>

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

</details>

Lifecycle View

Additional design context:

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

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

<details> <summary><strong>CLI invocation options</strong></summary> <br>

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

</details> <details> <summary><strong>Optional extras</strong></summary> <br>

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

uvx entrix install --repo .

</details>

First Run

1. Create a fitness 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 fitness checks from docs/fitness/*.md
• entrix validate: validate the fitness 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 fitness 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