locguard

A fast, zero-config CLI that keeps source files below a configurable line limit.

locguard defaults to 1,000 physical lines per source file. It ignores Git-ignored files, dependencies, generated code, vendored code, and build output, then scans only the source files that matter.

locguard
# ✓ 7 files checked

locguard scan
# ✓ 1,443 files checked

Install

The npm package installs the native locguard binary:

npm install -g locguard-cli

Native archives and shell/PowerShell installers are also published with GitHub Releases.

Usage

Bare locguard is optimized for local and agent check loops:

locguard

Inside Git it checks staged, unstaged, and nonignored untracked source files. Use scan for the authoritative full-tree check, such as in CI:

locguard scan

Scope a check explicitly when useful:

locguard --file src/main.rs --file src/server.rs
locguard --dir src --dir crates/api

A file over the limit fails with exit code 1:

Current LOC limit: 1000 lines, 1 file exceeded this limit.
FAIL src/runtime.rs

Warnings begin at 90% of the effective limit by default.

Configuration

No setup is required. Run locguard init only if you want to customize the defaults. It creates .agents/.locguard.toml:

limit = 1000
warn_percent = 90

include = []
exclude = []

[exempt]
files = []

Use include for project-specific source files such as Makefile, exclude for project-specific categories, and [exempt].files for exact legacy files that should be permanently grandfathered without teaching every agent about them.

CLI flags override repository configuration:

locguard --limit 800
locguard --include '**/*.foo'
locguard scan --no-exempt
locguard scan --json

Why it is fast

locguard is a threshold checker, not a code-analysis engine. It does not parse ASTs or decode source text just to count lines.

• Git supplies changed/full candidate paths and ignore semantics.
• Source-type and generated/vendor filters run before files are opened.
• File metadata can prove tiny files are below the warning threshold without reading their contents.
• Violating files stop being read as soon as line limit + 1 is proven.
• File scans run with modest parallelism and reusable buffers.
• Newlines are counted directly from bytes.
• Source candidates whose first 64 KiB contain a NUL byte are treated as binary-like and skipped instead of being decoded or guessed at.

Physical lines include comments and blank lines because the invariant is about keeping files small, modular, merge-friendly, and easy for coding agents to navigate.

Development

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cd docs && bun install --frozen-lockfile && bun run test:vercel && bun run check && bun run build

See the documentation for configuration and the complete command reference.

License

Apache-2.0