clawlint-auditing

Auditing a Claude Code setup with clawlint

clawlint is a deterministic linter for Claude Code configs. It catches the cheap mistakes — oversized agent files, stale path references, overbroad tool permissions, vague skill descriptions, token-heavy output styles, dead skills that nothing references — before they rot.

When to audit

• After editing an agent file. CLAUDE.md, AGENTS.md, or .claude/agents/*.md changes are the #1 source of silent context bloat. A quick clawlint check --scope project after edits catches size regressions.
• When onboarding a new project. Run once to see what you inherited.
• When Claude's behaviour suddenly gets weirder. Overlapping skill triggers and hedged rule language both cause drift. Lint to confirm.
• Before shipping a skill or agent for others to use. Vague descriptions and missing "when not to use" sections are the top reasons others can't predict your agent's behaviour.

How to run

clawlint check                    # default: scope=all, deterministic only
clawlint check --scope project    # just the current repo's .claude/
clawlint check --scope global     # just ~/.claude/ and ~/CLAUDE.md
clawlint check --llm-assist       # escalate judgment-heavy rules (costs tokens)
clawlint tui                      # interactive dashboard

--format json emits the canonical envelope — pipe into jq or the TUI (clawlint check --format json | clawlint tui).

What clawlint does NOT do

• Run your code or your hooks. It reads config only.
• Detect prompt-injection or security issues in agent files. Wrong tool.
• Replace code review. Rule judgments are heuristic; some will be wrong.

How to interpret output

See the clawlint-interpreting-results skill for the diagnostic schema, severity semantics, and how to tell a real finding from a false positive.

When to suppress instead of fix

Suppression is for findings that are genuinely wrong in context — not for silencing rules you find annoying. If you suppress, leave a one-line comment explaining why, so future-you doesn't have to re-derive the reasoning.

<!-- clawlint: disable-next-line=agent-file-stale-paths -->

See `src/legacy/` — kept for v1 compat until the migration ships.

Checklist

• Run clawlint check --scope project after agent-file edits
• Skim the diagnostic list; group mentally by category
• Fix errors. Triage warnings. Ignore info unless several cluster
• Suppress only with an explanatory comment
• Re-run to confirm the count dropped