Code Conventions (AI)

An AI agent (implemented as a GitHub bot) to enforce your own code conventions and improve your codebase as a result, even if your codebase is already in a pretty good shape.

Why?

You probably already know how to write code (I’m not here to argue with you), so you already know all the best practices (you see how much I believe in you…). And you’re probably already enforcing those best practices using a linter (ESLint for JavaScript, Flake8 for Python, RuboCop for Ruby, etc) in your codebase (and if you don’t, you should).

But while linters are great for simple things (e.g. “don’t leave behind unused variables”), some more advanced conventions are more difficult to codify (e.g. “when making a change to this database schema make sure you use snake_case and also let Jeff know”).

Each team, as it reaches a certain size (or hires the first intern), starts to develop their own set of code conventions. These are rarely written as static AST walkers, but simply as plain English document (usually in a file called CONVENTIONS.md, here is a good example).

Over time, that document grows in size and no engineer can remember it all. That's where this app comes in. It helps you enforce your own code conventions and keep your codebase beautiful.

Does this replace my linter?

It can, but not really. You should use both.

Linters are cheaper, faster, deterministic and can autofix things for you. This is more for those higher level concepts which linters can’t handle.

Does this replace my custom rules in the linter?

Absolutely. Why would you spend hours fighting with ASTs only to forget about edge cases, when you can simply describe it in plain English.

Whatever, I’m just gonna wait until AI writes all the code for me

You probably want to tell your AI how you want it to write code (e.g. “use Better Stack for logging instead of Datadog”, “use friendly tone in the error messages”). So you want to have CONVENTIONS.md and you want an agent to check on your agent anyway.

What I’m saying is that this is a good investment for both short term and long term.

How it works

1. Install this app into your GitHub repo.
2. Make sure you have CONVENTIONS.md in your repo.
   • This is a standard best practice so you should do that anyway.
   • There is no pre-defined set of conventions. You should write your own that are relevant to you (e.g. “use React functional components instead of class components” is useless for you if you don’t use React). Here is an example.
3. Profit.
   • Whenever someone submits a new pull request, this app will analyze it and add a comment into the PR with suggestions based on your code conventions.
   • It does not make any changes to the code. It’s up to you whether you want to apply them or ignore them.

Pricing

Security

This app requires the following permissions to run:

• Read and write access to pull requests - This is needed to receive events whenever a pull request is opened (read) and add a comment with the suggestions (write).
• Read access to code and metadata - This is needed to read the contents of the pull request. GitHub doesn’t include the contents of the pull request in the pull request event itself (and there is no separate permission to access only the diff files), hence this permission. The app will also need to read the CONVENTIONS.md file. (The app doesn’t read the rest of codebase, you can verify this in the audit logs.)

No code is stored on our servers and the pull requests are immediately discarded after being processed. The only thing we keep is the name of the repo, the installation id, and your code conventions.

Is this app SOC2 certified?

No, and it doesn’t need to be either. This app doesn’t have access to your user data (database, PIIs, etc), only to your codebase, and you don’t store database credentials and PIIs in the codebase, right? Right?

Noted, but I would still prefer SOC2

Check out the Enterprise plan. This allows you to host the app yourself on your own infra (AWS, GCP, Azure) and use your own API keys (we use OpenAI models under the hood).