Skip to content

SKILL.md

Latest commit

 

History

History
163 lines (114 loc) · 4.86 KB

SKILL.md

File metadata and controls

163 lines (114 loc) · 4.86 KB
Raw
name contextlevy-cli
description Install and use the ContextLevy CLI for local AI context cost checks from git diffs. Covers npm install, scan/fix/badge/hook commands, JSON output, exit codes, and pre-push hooks. Use when the user asks about contextlevy diff, pre-push context checks, local ContextLevy setup, or installing contextlevy via npm.
metadata
author version
nonlooped
1.1.0

ContextLevy CLI

ContextLevy is a repo hygiene linter for agent-heavy teams. It flags diffs that will make coding-agent review noisy — generated output, coverage, build artifacts, lockfile churn, and agent instruction changes.

Privacy: No LLM calls, no code upload, no external API. Runs on your machine.

For PR comments in GitHub, use the contextlevy skill.

Install skills

npx skills add nonlooped/contextlevy

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

Local CLI

Install

npm install -g contextlevy

Requires Node.js 20+ and git on PATH.

Common commands

# Start here (no config required)
npx contextlevy check --base main

# Baseline repo context debt (tracked files)
npx contextlevy scan

# Scaffold config + workflow + pre-push hook
npx contextlevy init --full

# Suggest ignore patterns (dry-run by default)
npx contextlevy fix
npx contextlevy fix --write

# README/PR badges
npx contextlevy badge --style debt
npx contextlevy badge --from check --style risk

# Install hooks (Husky, lefthook, or .git/hooks)
npx contextlevy hook install
npx contextlevy hook install --pre-commit --no-pre-push

# Working tree vs main
contextlevy check --base main

# Staged changes only
contextlevy check --staged

# JSON for scripts / hooks
contextlevy check --base origin/main --format json

# Apply fail settings from contextlevy.config.yml
contextlevy check --base main --fail-on-config

# Strict category gate (dist/, coverage/, etc.)
contextlevy check --base main --strict

Exit codes

Code Meaning
0 Below fail thresholds
1 Fail threshold exceeded
2 Usage, config, or git error

CLI caveats

  • Analyzes tracked changes visible to git diff. Stage new files with git add, or pass --staged.
  • scan and fix --from scan use git ls-files for a repo-wide baseline.
  • Reuses the same config file and estimation modes as the GitHub Action.

Pre-push hook

Prefer the built-in installer:

npx contextlevy hook install

Or wire manually:

{
  "scripts": {
    "contextlevy": "contextlevy check --base origin/main --fail-on-config"
  }
}

Configuration

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

Minimal example:

mode: advisory
allow-paths:
  - "packages/api/src/generated/**"

Key options:

Key Default Purpose
token-threshold 1000 Skip PR comment below this token total
fail-on-severity unset Fail at low / medium / high / critical or above
fail-above-tokens unset Fail when total estimated tokens exceed this value
ignore-paths [] Globs excluded from analysis
allow-paths [] Globs counted but not flagged as high-impact
estimation-mode simple simple (chars÷4) or tokenizer (local BPE)
comment-format default default or compact (Action/CLI human output)

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

Category Examples
Coverage coverage/lcov.info, htmlcov/
Generated generated/client.ts, protobuf/OpenAPI dumps
Build output dist/, build/, .next/
Lockfiles package-lock.json, pnpm-lock.yaml
Agent config .agents/, AGENTS.md, skill packs
Large files Any path above large-file-token-threshold

Agent guidance

When helping a user set up the ContextLevy CLI:

  1. Ask whether they need local checks (CLI), PR comments (contextlevy), or both.
  2. Run contextlevy scan first for repo-wide debt, then contextlevy check before opening PRs.
  3. Use contextlevy fix --write to append missing ignore patterns; use contextlevy init --full for one-shot setup.
  4. Add contextlevy.config.yml with fail-on-severity or fail-above-tokens when using --fail-on-config.
  5. For monorepos, use ignore-paths for vendored/generated trees and custom-rules for project-specific paths.
  6. Recommend contextlevy hook install or fail-on-config in pre-push hooks; use fail-on-severity: high in CI for advisory-first teams.