bully

Bully: Lint Rules Claude Code Can't Ignore

The edit doesn't land until your lint rules pass.

Install · Quick start · Configuration · Architecture · Design · Rule authoring · Telemetry

---

Bully is a PostToolUse hook for Claude Code. On every Edit and Write, it runs your linters (ruff, tsc, eslint, biome, phpstan, clippy, …) and uses an LLM to evaluate plain-English rules against the diff. If anything fails, Claude can't land the edit. Each block feeds the rule back to the agent, so your rules improve its behavior without manual coaching.

Read the Design doc for the architecture, data flow, and baseline contract.

Install

/plugin marketplace add https://github.com/dynamik-dev/bully
/plugin install bully

Restart Claude Code. Then in a project:

> /bully-init

/bully-init detects your stack, wires your existing linters as passthrough rules, and creates .bully/ for telemetry. Review the generated .bully.yml, tweak, commit.

Manual install, bully doctor, model overrides, and uninstall live in Reference.

Quick start

> /bully-init                  # bootstrap a config from your stack
> /bully-author                # add a rule (engine routing + fixture test)
> /bully-review                # prune noisy and dead rules from telemetry

bully baseline-init --glob "src/**/*.ts"   # ignore pre-existing violations
bully guide src/foo.ts                     # which rules apply before editing
bully lint src/foo.ts --print-prompt       # debug the semantic prompt

Silence one line when a rule is right in general but wrong here:

eval(expr); // bully-disable: no-eval reason: sandboxed input

What Bully does

• Linter passthrough. engine: script rules call your existing linters as subprocesses (ruff check --quiet {file}, tsc --noEmit). The same checks CI runs, blocking on every edit.
• Structural patterns. engine: ast rules use ast-grep to match shape, not text. Comments, strings, and formatting variants don't fool them.
• Prose rules. engine: semantic rules are plain English ("don't derive state with useEffect"). The bully-evaluator subagent has no Read / Grep / Glob and only sees the diff, so adversarial content can't redirect it.
• Session rules. engine: session fires at Stop over the cumulative changed-set: "auth changed without tests", "migration without rollback", "API changed without changelog". Catches things no per-edit lint can see.
• Trust + capabilities. bully won't run any rule until you bully trust the config. Per-rule capabilities: (network: false, writes: cwd-only) further gate what scripts can do.
• Telemetry + review. Every run appends a JSONL record to .bully/log.jsonl. /bully-review flags noisy and dead rules; the bully-scheduler agent can run on cron and open small PRs to retire them.
• Authoring + feedforward. /bully-init bootstraps a config. /bully-author adds rules with engine routing and fixture testing. bully guide <file> lists rules in scope before the agent edits.

Configuration

One YAML file at .bully.yml in your repo root. A flat list of rules; each names what to check, where it applies, severity, and which engine runs it.

schema_version: 1

rules:
  ruff-check:
    description: "Code must pass ruff check."
    engine: script
    scope: ["*.py"]
    severity: error
    script: "ruff check --quiet {file}"

  no-any-cast:
    description: "No `as any` casts. Use a precise type or `unknown` plus narrowing."
    engine: ast
    scope: ["src/**/*.ts", "src/**/*.tsx"]
    severity: error
    pattern: "$EXPR as any"