Skip to main content

byor: Build Your Own Rules

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

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    # or `uvx byor` to try without installing
byor install            # set up the skill + your agents' hooks (once)
byor init               # add byor to a repo

byor bundles ast-grep, so Python 3.11+ is the only requirement. byor install registers your editor and agent integrations machine-wide; byor init adds a repository's rule directories and sgconfig.yml. docs/ai-agents.md covers what each step writes.

You can also let your AI coding agent handle it: open it in the repo and ask it to set up byor.

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.

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

byor supports five harnesses:

Harness Skill Real hook Diagnostic precision
Claude Code yes PostToolUse the edited lines
Codex yes PostToolUse the patched 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

Metadata

Release files for byor 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for byor 0.1.2
File Size Uploaded Provenance Actions
byor-0.1.2.tar.gz 57.5 kB With provenance Details for byor-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for byor 0.1.2
File Interpreter ABI Platform Actions
byor-0.1.2-py3-none-any.whl Python 3 none any Details for byor-0.1.2-py3-none-any.whl

Total release size: 131.7 kB

Release files / byor-0.1.2.tar.gz

Download URL byor-0.1.2.tar.gz
Size 57.5 kB
Tags Source
SHA-256 checksum
How to use checksums
87276e647b0806b496e994e141dfc9dc18fceaf9d3cad598aba783d73d9a8013
BLAKE2b-256 checksum
How to use checksums
66d4868aeccb76757bc894c430a4209ef938d5d22ca779feecb817bd00a71425
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Release files / byor-0.1.2-py3-none-any.whl

Download URL byor-0.1.2-py3-none-any.whl
Size 74.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3ce803cf2ef4693b0713c7edad8a7d460ef7e0a6d147e66cb361a1752bb1eedd
BLAKE2b-256 checksum
How to use checksums
0a0e5c8e33cd5ea15d1dce035b23c04c3734673e34863311f8c45bf14d4dd8a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Security for byor 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for byor-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page