loq

An electric fence for LLMs (and humans too). Written in Rust, loq enforces file line limits: fast, works out of the box, and language agnostic.

Why loq?

• 🔒 Hard limits to prevent oversized files and context rot
• 📏 Line counts first, with optional approximate token budgets for prompts and agent-facing files
• 🧩 Works everywhere - no language-specific setup
• 🤖 Designed specifically with coding agents in mind
• 🦀 Lightning fast Rust core

Getting Started

Installation

# With uv (recommended)
uv tool install loq

# With pip
pip install loq

# With cargo
cargo install loq

Usage

# Check current directory for violations (default: 500 lines)
loq check           

# Check specific paths               
loq check src/ lib/     
     
# Check only staged files
loq check --staged

# Check files changed since a ref
loq check --diff HEAD
loq check --diff origin/main..HEAD

# Check files from stdin
git diff --name-only | loq check -

--staged and --diff are repo-wide modes. They cannot be combined with PATH args or stdin scope (loq check -).

Managing legacy files

# Creates, updates or removes exact-path rules
# to match the current state of your files.
loq baseline

# Creates or updates exact-path rules for current violations
loq relax
loq relax src/legacy.rs   # specific file
loq relax --extra 50      # custom buffer

# Ratchets down or removes existing exact-path rules
# as your file sizes become compliant over time
loq tighten

All three commands manage exact-path rules in loq.toml. baseline and relax can add new rules; tighten only updates or removes existing ones. They manage line limits and leave token-governed files alone, and they operate on the current directory (like check), writing to the nearest loq.toml found above it.

Configuration

loq works zero-config. Run loq init to create a loq.toml file to customize:

# default, for files not matching any rule
default_max_lines = 500

# Or default to an approximate token budget instead of lines.
# Set only one of default_max_lines / default_max_tokens.
# default_max_tokens = 8000

# skip .gitignore'd files
respect_gitignore = true

# ignore files or paths
exclude = ["**/generated/**", "*.lock"]

# Add fix_guidance to include project-specific instructions
# with each violation when piping output to an LLM:
fix_guidance = "Split large files: helpers → src/utils/, types → src/types/"

# Last match wins
# * stays within a path segment
# ** matches across directories
[[rules]]
path = "**/*.tsx"
max_lines = 300

# Agent-facing files can use approximate token budgets.
# Tokens are estimated as bytes / 4, rounded up.
[[rules]]
path = "prompts/**/*.md"
max_tokens = 8000

Output options

# Detailed output
loq check -v

# JSON format
loq check --output-format json

Add as a Pre-commit Hook

repos:
  - repo: https://github.com/jakekaplan/loq
    rev: v0.2.0
    hooks:
      - id: loq

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

License

This project is licensed under the MIT License.