Contributing

The best bug reports come from using it

Several shipped fixes were found by an agent hitting something awkward mid-task and filing it — not by anybody reading the source. If you try this and something gets in your way, that is the contribution.

File an issue Browse the code

Get the code running

Python 3.12 or newer, managed with uv. No external services: the test suite runs against a temporary SQLite file.

git clone https://github.com/salimfadhley/agent-inbox
cd agent-inbox
uv sync

# the four gates — all must pass before anything merges
uv run pytest
uv run ruff check
uv run ruff format --check
uv run pyright

That is the whole setup. If a change needs a service to test, it is probably the wrong change.

What a good contribution looks like

Report friction, not just faults

“I had to call this twice to do an obvious thing” is as valuable as a stack trace, and rarer. Say what you were trying to do when it got in the way.

Prove a guard by removing it

A test asserting “this did not happen” passes trivially when the code path is never reached. Delete the guard, watch the test fail, put it back. Otherwise you have written a test that cannot fail.

Prefer end-to-end over mocks

The store is one SQLite file, so a full round-trip is cheap. Heavy mocking tends to assert that the code does what it does.

Say why in the commit

The what is in the diff. The reasoning, the thing you rejected, and the failure that prompted it are not — and they are what the next reader needs.

Rules worth knowing before you open a PR

No deployment specifics: No hostnames, IP addresses, secrets or organisation names in code, docs or tests. This is upstream library code; someone else’s network is not part of it.
Consistency beats upgrades: Downstream users depend on our patterns. A change that breaks a working habit needs to be worth more than the disruption it causes.
Docs change with behaviour: In the same change, not a follow-up. A document describing behaviour that shipped differently is worse than no document.
Settle a foundation before building on it: If the layer underneath is still moving, settling it is the work. Building on top only multiplies what has to be redone.

The full versions live in coding-standards.md and the project charter.

Good places to start

Open enhancements — several are small and self-contained.
The ADRs — the fastest way to understand why things are shaped as they are.
The issue list — including a few open questions that want an opinion more than a patch.

Reviews from outside are welcome and taken seriously. Two real security defects in this project were found by an outside model asked one narrow question and left to write its own probes. If you want to try to break something, ask about a specific invariant rather than reviewing broadly — it works far better.