byor 0.1.4

Make custom ast-grep diagnostics easy to set up, share, and expose to AI agents

Write a custom lint rule once and it becomes a live diagnostic in your terminal, your editor, and your AI agent's feedback loop.

The usual way to teach an agent your standards is a wall of prose in AGENTS.md or CLAUDE.md — which inflates every prompt, gets followed unevenly, and does nothing in your terminal or editor. byor makes the standard a rule instead: checked mechanically everywhere, and surfaced to the agent only when its own change trips it, scoped to the lines it touched.

byor is a small CLI around ast-grep, a fast structural search-and-lint tool. ast-grep scan lints from the terminal and ast-grep lsp shows diagnostics in your editor; byor arranges plain rule files and configuration so both work without setup, then adds the two things ast-grep leaves out: sharing rules across your repositories, and feeding their diagnostics back into AI coding agents.

# .byor/rules/project/no-print.yml
id: no-print
language: python
severity: warning
message: Use the logging module, not print, in library code.
rule:
  pattern: print($$$ARGS)
metadata:
  byor:
    agent_prompt: >
      Replace this print with a module-level logger,
      logging.getLogger(__name__), at the appropriate level.

message is what you read in the terminal and editor; agent_prompt is the directive byor hands your AI agent when it trips the rule.

Install

uv tool install byor && byor install   # install the CLI, then set up the skill + agent hooks (once)
byor init                              # optional — only for repo-scoped or shared rules (see below)

byor bundles ast-grep, so Python 3.11+ is all you need to run it — the rules themselves work in any language ast-grep supports (TypeScript, Go, Rust, and more), not just Python. byor install registers your editor and agent integrations machine-wide. byor init is optional: run it only when you want rules or checks scoped to a repository, or shared with contributors — your personal global rules and checks already work in every repo without it. docs/ai-agents.md covers what each step writes.

After that one-time bootstrap, let your AI coding agent handle the rest: open it in the repo and say "set up byor". The skill verifies the install, runs byor init if you want repo or team rules, and offers to import the preferences you already wrote in your CLAUDE.md / AGENTS.md as enforced rules.

Terminal and editor

A rule under .byor/rules/ is an ordinary ast-grep rule, so the ordinary tools read it:

ast-grep scan            # lint the repo
ast-grep scan src/       # ...or a path

For live in-editor diagnostics, point your editor's ast-grep integration at ast-grep lsp: rules light up as you type and reload when you edit them. (editor setup.)

Rule scopes

The same rule format lives at three scopes:

Scope	Lives in	Shared with
project	.byor/rules/project/	Your team (committed)
local	.byor/rules/personal/local/	You, this repo only
global	~/.config/byor/rules/	You, in every repo

Global rules are your personal standards; byor makes them apply in every repo. Project and local rules override a global rule with the same ID, so a team policy or a local experiment takes precedence. See docs/rules.md for the rule workflow and docs/sync-model.md for how byor copies global rules into each repo.

With AI coding agents

Agents can both obey your rules and write new ones:

• Feedback. A post-edit hook runs byor agent-check after the agent edits a file and feeds the diagnostics back into its context, scoped to the lines it changed, so it fixes violations before moving on.
• Capture. A bundled skill turns durable feedback ("never do this", "always do that") into an ast-grep rule: the agent drafts it, confirms once, and runs byor add. When a linter or type checker fits better, the skill offers that instead.
• Setup. The same skill onboards you: say "set up byor" and it checks the install, optionally inits the repo, and imports the mechanically checkable preferences from your existing CLAUDE.md / AGENTS.md as rules — and can clean up an existing repo on a throwaway branch so you start without a wall of warnings.

byor install wires up the agents you pick (once, machine-wide); byor hook adds or drops one later.

byor install --agents claude-code,codex
byor hook install --agent copilot       # add an agent later
byor hook uninstall --agent copilot     # or remove one (--agent skill removes the skill)

byor supports five harnesses:

Harness	Skill	Real hook	Diagnostic precision
Claude Code	yes	PostToolUse	the edited lines
Codex	yes	PostToolUse	the edited lines
Copilot CLI	yes	postToolUse	the edited lines
OpenCode	yes	tool.execute.after plugin	the changed file
Pi	yes	tool_result extension	the changed file

Cursor and Antigravity are not supported: neither exposes a post-edit hook that byor can reliably integrate with, so byor omits them until that changes.

A checks: section in .byor/config.yml (or your global config) runs extra command-line tools (a linter, a type checker, anything) on the changed files and folds their output into the same feedback. See docs/ai-agents.md.

Continuous integration

Project rules are committed files that work with ast-grep, so CI doesn't need byor: a fresh clone already has everything ast-grep scan reads. Scan with --error so warnings fail the build (a plain scan exits 0 on warnings):

- run: npm install -g @ast-grep/cli
- run: ast-grep scan --error

Commands

Setup. You run these once to get going.

byor install        Register byor's AI integrations (machine-wide)
byor init           Initialize byor in a repository
byor hook           Add or remove an agent integration
byor doctor         Check that everything is wired up

Rules. Your agent runs these as it captures and manages rules for you.

byor add            Create a rule in a scope
byor list           Show rules and where they come from
byor edit           Open a rule in $EDITOR
byor remove         Delete a rule
byor promote        Move a personal rule into shared project rules
byor exclude        Disable a global rule in this repository
byor include        Re-enable an excluded global rule

Automatic. byor runs these itself: the post-edit hook and self-heal.

byor agent-check    Render diagnostics for your agent
byor sync           Mirror global rules into the repo

Every command takes --help, and repo-operating commands take --repo PATH (default: search upward from the current directory).

Documentation

• docs/rules.md — rule format, scopes, and the rule workflow
• docs/ai-agents.md — AI agent integration and agent-check
• docs/sync-model.md — copies, self-healing, and git hooks
• examples/ — reference rules (simple → advanced) and config setups