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-checkafter 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
- 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.