Contextlevy

ContextLevy (GitHub Action)

ContextLevy is a repo hygiene linter for agent-heavy teams. It flags PR diffs that will make coding-agent review noisy and posts focused PR comments before that noise becomes repo debt.

Privacy: No LLM calls, no code upload, no external API. Runs locally in CI.

For local pre-push checks, use the contextlevy-cli skill.

Install skills

npx skills add nonlooped/contextlevy

The wizard lets you pick contextlevy (this skill), contextlevy-cli, or both. To install only this skill: --skill contextlevy.

GitHub Action

1. Install the app (recommended)

Install the ContextLevy GitHub App on the repository.

Permissions: Contents read, Pull requests read & write, Issues read & write.

2. Add the workflow

Create .github/workflows/contextlevy.yml:

name: ContextLevy

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write
  checks: write
  security-events: write

jobs:
  contextlevy:
    name: Check repo context hygiene
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: nonlooped/contextlevy@v2
        with:
          github-token: ${{ github.token }}

Action behavior

• Reads config from the base branch (a PR cannot silence the check by editing contextlevy.config.yml in the same diff).
• Posts a PR comment when estimated tokens exceed token-threshold.
• Publishes a Check Run named ContextLevy when create-check is enabled (default).
• Uploads SARIF to Code Scanning when upload-sarif is enabled (default).
• Fail mode (fail-on-severity or fail-above-tokens in config) fails the workflow even when the comment is skipped.
• Workflow YAML only needs auth inputs; all tuning lives in contextlevy.config.yml.

Action inputs

Action outputs (for downstream steps)

Configuration

Add contextlevy.config.yml at the repo root (or see CONFIG.md for all supported paths).

Minimal example:

mode: advisory
token-threshold: 1000
fail-on-severity: high
allow-paths: []

Key options:

Editor autocomplete: point YAML at docs/schema/contextlevy.schema.json in the ContextLevy repo.

For full config tables, severity levels, and recipes, see reference.md and CONFIG.md.

What ContextLevy flags

Agent guidance

When helping a user set up ContextLevy on GitHub:

1. Confirm they need PR comments (Action), local checks (contextlevy-cli), or both.
2. Add contextlevy.config.yml before the workflow — keep workflow YAML minimal.
3. Include checks: write and security-events: write when using Check Runs and SARIF (defaults).
4. For monorepos, use ignore-paths for vendored/generated trees and custom-rules for project-specific paths.
5. Recommend npx contextlevy init --full for new repos; mode: advisory for advisory-first teams, mode: strict for artifact fails.
6. Pair CLI check --strict with contextlevy hook install; use GitHub Action for PR comments and branch protection.
7. Do not put GitHub App private keys in contextlevy.config.yml — use secrets/variables.