Read me first

If you have just arrived at this project, start here. No jargon, no code, and no assumption that you are a developer — just what this software is, who it is for, and what to do with it.

---

1. Who this is for

This is for teams who build software, and for the people responsible for the quality and safety of what those teams ship.

Four kinds of people get something different out of it:

• The engineer reviewing a colleague's work. The main user, many times a day. They want to know quickly: is this problem real, does it stop me, and what exactly do I change.
• The engineering manager. Wants to know whether quality is improving, where the trouble spots are, and whether this is worth what it costs.
• The security lead. Wants evidence: what was checked, against what standards, and proof that the company's source code never left the building.
• The person who runs the servers. Installs it, connects it to things, and keeps it healthy.

You do not need to be any of these to read this document.

---

2. What it does

When someone on a software team proposes a change, that change is supposed to be read by a colleague before it becomes part of the product. That reading is called a code review, and it is where a lot of mistakes get caught.

This software does the first pass automatically. Every time someone proposes a change, it reads it and writes back:

• A plain summary of what the change actually does.
• Specific comments on specific lines — what looks wrong, how serious it is, why it matters, and usually what to put there instead.
• A pass or fail mark, which your existing rules can use to stop a dangerous change from going in.

It does not replace the human reviewer. It clears the obvious problems out of the way so the human can spend their attention on the things that need judgement.

---

3. The world this belongs to

Software is built by making small changes to a large existing body of work. Because a small change in one place can break something far away, teams adopted a discipline: no change goes in until somebody else has read it.

That discipline works, and it is expensive. It uses the time of the most experienced people you have, and changes sit waiting for it. As teams have started using AI to write more code, the volume of changes needing review has grown faster than the number of people available to review them.

So tools appeared that do the first read automatically. There are two families:

• Rule-checkers, which look for patterns from a fixed list. Predictable, and they produce so many irrelevant complaints that people stop reading them.
• AI reviewers, which read code more the way a person does — but nearly all of them require you to upload your source code to their service.

This product is the second kind, without the upload. That is its whole reason for existing.

---

4. Where it fits

It sits between your code and the people who write it. It does not store your code, replace anything, or change how your team works. It watches, reads, and comments.

It connects to two things:

1. Where your code lives — GitHub, or a Gitea you run yourself (GitLab is planned, not yet built). It watches for proposed changes and posts its comments back there.
2. An AI service of your choosing — either a commercial one you already pay for, or one running on your own machines.

And that is the entire list. Your code goes to those two places and nowhere else. If you pick an AI service that runs on your own hardware, nothing leaves your building at all — the whole thing works with no internet connection.

Who tends to want this: companies whose code cannot legally or contractually be sent to an outside service — healthcare, finance, defence, government. Companies large enough that paying per developer has become painful. And open-source projects, where the people proposing changes are strangers and per-person pricing makes no sense at all.

---

5. The first thing to do

Try it without connecting anything.

There is a ready-made version that runs on one machine with everything included, already filled with realistic example data. Nothing to set up, no account, no code of yours involved:

docker run --rm -e PORT=30001 -p 30001:30001 aicr-preview:latest

Then open http://localhost:30001/dashboard in a browser and look around. Details are in preview/README.md.

Spend ten minutes on it before anything else. Everything you see is invented — the company, the projects, the people — but it is arranged to show you exactly how the real thing behaves, including what it does when something goes wrong.

What to look at, and why it matters:

Look at	Because
A review with problems found	This is the everyday view — see whether the explanations are worth reading
A review that failed	It says so plainly and does not block anyone's work
A change not yet reviewed	Visibly different from one that was checked and found fine. Most tools blur these two, and that is genuinely dangerous
The summary screen	What your manager would look at monthly

---

6. Setting it up properly

When you are ready for real use, someone technical does this once. It takes about an hour. The full instructions are in getting-started.md; in outline:

1. Find somewhere to run it. One ordinary server handles a mid-sized company — roughly 200 projects and a few hundred changes a day.
2. Choose your AI service. A commercial account, or a model on your own hardware if you want to be certain nothing leaves your network.
3. Connect it to GitHub or Gitea, so it hears about new changes.
4. Connect two or three real projects. Pick busy ones — a quiet project teaches you nothing.
5. Agree the house rules (next section).
6. Watch it for a week before turning on blocking. Let the team see the comments first and build some trust. Turning it into a gate on day one is the fastest way to have it resented.

---

7. Using it day to day

For most people there is nothing to run and nothing to remember. Changes get reviewed automatically and comments appear where the team already works.

Reading a comment. Each one tells you how serious it is (critical, high, medium, low, or information), what kind of problem it is, where it is, why it matters, and how confident it is. Security problems include a reference number you can look up independently, so you can check the claim rather than trust it.

Marking a comment useful or not useful. This is the one habit worth building. It takes a second and it is how the tool learns. Once your team has rejected the same kind of comment enough times, it stops raising it and tells you how many it held back. You can always see what was held back and turn it back on.

Setting the house rules. Each project carries a small settings file, kept alongside the code, that decides what gets reviewed, what gets reported, and what is serious enough to stop a change. Because it lives with the code, changing the rules is proposed and approved like any other change — no administrator, and a full history of who changed what.

Checking your own work first. Developers can run the reviewer on their own machine before anyone else sees the code. Details in useful-commands.md.

---

8. Looking after it

How often	What
Weekly, at first	Look at what is being found and whether the team is marking comments useful. If most are being rejected, tune the rules — don't endure it
Monthly	Open the summary screen. Is the trend going the right way? Which projects attract the most problems?
Monthly	Check the running cost of your AI service. Each review has a spending limit you can adjust per project
Ongoing	Apply updates, and confirm your database backups actually restore. A backup nobody has tested is not a backup
When someone leaves the team	Nothing. The tool keeps no accounts of its own — it asks your existing systems who people are and what they may see
When a project ends	Disconnect it (reversible, keeps the history) or erase it (permanent, deliberately hard to do by accident)

---

9. Words you will see

Repository — one project's code, kept in one place. Change (or pull request, merge request) — a proposed edit, waiting to be approved. Review — one attempt to read one version of a change. Finding — one problem the reviewer identified. Severity — how serious: critical, high, medium, low, or information. Merge gate — the rule that stops a change going in until it passes. Self-hosted — running on computers you control, rather than someone else's service. Air-gapped — a network with no connection to the internet at all. Withheld — a finding the tool decided not to show you, because your team keeps rejecting that kind. It always tells you the count.

---

10. The other documents

Document	For
getting-started.md	Installing it — plain language, some commands
demo-data.md	Loading example data for a demonstration
production-initialization.md	Preparing a real environment. Read before running it — it erases data
useful-commands.md	The commands worth knowing
api-reference.md	Connecting other software to it
testing.md	How it is tested, and how to check that yourself
preview/README.md	The ready-made version described in section 5
collateral/	Explanatory material, including four papers on the thinking behind it

---

11. Who can see what

Worth understanding early, because it surprises people.

The tool keeps no user accounts and no permissions of its own. When someone opens it, it asks your existing systems who they are and which projects they are allowed to see — every time. It cannot show anyone anything your company has not already given them access to, and it cannot be configured to.

The practical consequences: someone who sees no projects has an access problem in your main system, not here. Removing someone's access there removes it here within about a minute. And there is no list of users here to maintain, or to leak.

When someone is signed in but refused, the page they see says so and names who to ask — whoever your technical team nominated when installing it. Being refused is an access decision, not a fault, so it is never reported as "not found".

---

12. Questions people ask

Does it replace human code review? No. It does the first pass so people can spend their attention on judgement.

What if it says something wrong? Mark it not useful. That is a signal, not a complaint form — enough of them and that kind of comment stops appearing.

Can it invent problems that do not exist? It is guarded against. Any finding pointing at code that is not actually in the change is thrown away before anyone sees it, and the number thrown away is recorded so your technical team can confirm the guard is working.

What if someone writes a note in the code trying to trick it? Treated as an attack, and defended against. Anything in your code is examined, never obeyed. Your actual instructions come only from the settings file, which is approved like any other change.

Will it stop our work if it breaks? No, by design. If it cannot review something it says so and gets out of the way. A tool that can halt everybody when it has a bad day gets switched off within a week — and then it protects nothing.

Does it work with our programming language? Reviewing works with any language. The deeper whole-project understanding covers twelve of the most common ones; outside that list you still get reviews based on the change alone, and the tool tells you that is what happened.

What does it cost? The software is free and open source. You pay for a server and for whatever your chosen AI service charges — nothing per developer. Below roughly fifteen to twenty developers, a commercial subscription is usually the better deal, and the paper on costs says so plainly.

Is it certified for compliance? No, and be wary of anything claiming otherwise. Its findings are advice about correctness, security, and performance — not a formal security assessment.

---

13. Getting help

• Community: wbsp.ai — questions, suggestions, and people who can adapt this to your needs.
• Something unclear in these documents? That is a documentation problem worth reporting. If you had to read a paragraph twice, so will the next person.

---

One last thing

This software was built entirely by AI. What that gives you is the working core: the functionality is there, without any company's branding or house style on it.

It is meant as a starting point. If you know this field and your way around AI tools, you can shape it into what your team actually needs. If not, wbsp.ai is where to find people who can — and it is worth looking around while you are there, since others have built versions of this and many other applications that may already be closer to what you want.