A review you can do in a few minutes
The inbox shows one scenario at a time, in plain language. Approve it, ask for changes or reject it. Only then does the agent start building.
MIT Open source and self-hostable
Agents build what you agreed to.Tests prove it.
OpenUsecase is for people who work with coding agents. Before it builds, an agent writes down the behaviour. You approve it, and tests carry its ID.
Feature: Change the primary colour
UC-142/S2 Reject an invalid colour
Given I am on the settings page
When I enter a value that isn't a colour
Then I see an error
And the app keeps the current colour
✓ Approved by Mia
✓ UC-142/S2 rejects an invalid colour
done · passing
The problem
It works, but it isn't what you meant.
An agent turns a short request into code, then writes tests for that code. Every test passes. You find out what it decided when you read the diff, or when a customer does.
- Let people change the colour
- A colour field in settings
- Saves whatever is typed
- The field saves its value
- Any value is stored
Agreed too lateYou see the decisions after they're built, inside a diff.
Plans disappearThe plan lives in a chat that ends with the task.
Nothing to askMonths later, nobody can say what the product should do.
Features
Agree first, build second, prove it after.
Each use case goes from a proposal to a permanent record of what your product does.
Status you can trust
A use case is done when tagged tests pass on the default branch. A broken test turns
it to done · failing.
You choose how much to review
An admin sets one mode per agent, and each use case records how it was approved. No agent can change its own mode.
Answers that say how they know
Agents answer from the catalogue and tell you how well it's backed up: tested, only proposed or not covered.
A check on every pull request
It fails unless the PR names approved use cases, or says why it has none, and every scenario has a tagged test.
A catalogue of what your product does
Use cases stay after they ship, grouped by area and searchable. Rejected ones stay too, so nobody proposes them again unaware.
One record for everyone
Agents work over MCP, people in the inbox, and CI sends test results. Each has its own identity, so you can see who did what.
Self-host in one command
One Docker image and Postgres, configured with environment variables, with a default for every setting.
Shared words
Link OpenPurpose to mark glossary terms in the inbox and keep agents to them. It's optional.
Checks by hand
Some things have no test. A person can verify a scenario, and it says so.
Export and import
Everything you put in comes out again, and goes back in.
How it works
Running in five minutes.
-
1
Run it
Run it on your own server, then add a team, a project and an agent in Settings.
$ git clone https://github.com/openstuff-dev/open-usecase $ cd open-usecase && cp .env.example .env $ docker compose up --build -
2
Connect your agent
OpenUsecase is an MCP server, and it tells an agent the workflow when it connects. Ask for something a user can see. The agent proposes a use case and stops.
-
3
Approve, and let CI prove it
Approve it in the inbox and the agent builds it. Name tests with the scenario's ID, and CI turns the use case to
done · passing.
Why OpenUsecase
A plan in a chat ends with the chat.
| What matters | A plan in a chat or a file | OpenUsecase |
|---|---|---|
| You agree before it's built | PartlyIf you read it, and the agent waits. | YesThe agent stops until a use case is approved. |
| Tests point back at what you agreed | NoNothing links a test to a plan. | YesEach test carries a scenario's ID. |
| Still true a year later | NoIt goes stale without saying so. | YesA failing test shows on the use case. |
| You own the data | PartlyA file is yours. A chat may not be. | YesSelf-host it, and export everything. |
Open source
Read the code, run it, change it.
- MIT licence. Use it at work, fork it, sell it.
- One compose file. Configured with environment variables.
- Your data. On your servers, exportable at any time.
$ git clone https://github.com/openstuff-dev/open-usecase
$ cd open-usecase && cp .env.example .env
$ docker compose up --buildPart of the OpenStuff family: tools built on one shared toolkit.
For teams and companies
Every product and agent, on one server.
Each team has its own projects, people and agents, kept apart from the other teams in the database itself.
Projects and areas
A project can span several repositories, with its use cases grouped by area.
Teams
Separate teams on one server, kept apart with Postgres row-level security.
Agents can't raise their rights
An agent can't manage tokens or permissions, not even its own.
Only people reject and retire
Admins manage the team. Members review. Agents and CI each have their own token.
Tokens shown once
Tokens are stored as hashes, and each one belongs to a single agent or CI job.
Export and import
Move a team's use cases, with their IDs and history, to another server.
FAQ
Questions people ask first
Is it free?
Yes. OpenUsecase is open source under the MIT licence, so self-hosting costs nothing but your server.
Can I self-host it?
Yes, and for now that's the only way to run it. Docker Compose starts the app and Postgres, configured with environment variables.
Where is my data?
In your own Postgres. CI reports are read and thrown away, and you can export a team's data at any time.
Does every change need a use case?
No, only changes a user can see. Refactors, dependency bumps and CI need none. If an agent is unsure, it asks.
Which agents does it work with?
Any agent that speaks MCP. So far, we've run it with Claude Code. Test results come in as JUnit XML, which most test runners can write.
Can an agent get around it?
The server can prove that an approving token didn't write the use case, but it can't see who holds a token. A sub-agent normally counts as its parent. For a real second opinion, run the reviewer in CI with a token the proposing agent can't read.