Contributing to pi-mono with a public maintainer corpus

· updated
pipi-monoupstreamtypesenserestateextensionsgithubarticle

I recently filed an issue against badlogic/pi-mono and got the right kind of pushback.

Not rude. Not dismissive. Just precise.

which provider/model triggered this?

please reopen the issue with concrete steps to reproduce this

on a type level, this is impossible

That’s the whole game.

If a maintainer can look at your bug report and immediately ask which provider, which model, whether it reproduces on clean upstream, and which layer actually violated the invariant, you’re not done. You’re still debugging locally.

So I stopped treating that as a one-off comment and turned it into tooling.

If you just want the install surface, the public skill/extension repo is here: joelhooks/contributing-to-pi-mono.

npx skills add -y -g https://github.com/joelhooks/contributing-to-pi-mono

The problem

The useful knowledge around pi-mono wasn’t sitting in one neat doc.

It was spread across:

  • CONTRIBUTING.md
  • AGENTS.md
  • issue templates
  • maintainer comments on issues
  • review comments on pull requests
  • commit history
  • release notes
  • the difference between what got a fast lgtm and what got bounced back

That kind of knowledge evaporates fast. You remember the vibe but lose the exact wording. Then you file the next issue from memory and waste everyone’s time again.

That’s bullshit.

What I built

I split this into two parts.

1. A public search surface for pi-mono maintainer context

Before you open an issue, you can hit a public search surface instead of guessing from memory:

  • /api/search?q=...&collection=pi_mono_artifacts
  • /api/pi-mono

The point isn’t to build a shrine to issue history. The point is to make maintainer feedback searchable before you type the next upstream report.

2. A public pi extension + skill repo

I created a separate public repo for the contributor-facing surface:

It ships:

  • a pi extension with pi_mono_search
  • a discovery tool for the public corpus
  • an installable public skill for contribution workflow

That split matters.

joelclaw owns the index, search, rate limiting, and web surface.

The public repo owns the thing another person can actually install without dragging the whole joelclaw monorepo into their lap.

Why the maintainer feedback was right

The original temptation was obvious: patch the crash site and move on.

That would have been the wrong move.

If the type-level contract says a state is impossible, then a defensive guard around the crash site might keep the process alive while hiding the real bug in a provider adapter, extension, or normalization layer.

That’s not a fix. That’s a tarp.

The better question is:

  • did this reproduce on clean origin/main?
  • did it reproduce with extensions disabled?
  • which provider/model produced the bad state?
  • did core actually break, or did core just happen to dereference the mess later?

Once you have those answers, the whole tone of an issue changes.

It stops sounding like “something weird happened in a long session” and starts sounding like an adult bug report.

The stance got more explicit

If the softer version above still sounds like interpretation, Mario later said the quiet part out loud.

On X he wrote:

you will be banned from the pi-mono repo if:

  1. you are a dick
  2. you keep submitting clanker slop repeatedly for the same “issue” to which you got a reply and workaround from yours truely

there is no way to appeal my decision.

Source: Mario Zechner on X

He linked that post directly to pi-mono issue #1993. That’s blunt, but useful. It clarifies the social contract around upstream work: if a maintainer already gave you an answer, a workaround, or a boundary call, you don’t get to come back with the same issue wrapped in fresher agent slop and call it diligence.

That’s also why I think the public corpus matters. It doesn’t just help you search for technical facts. It helps you search for the maintainer’s tolerance boundary before you waste their time.

What the corpus is good for

A few searches tell you a lot:

curl -sS "https://joelclaw.com/api/search?q=which+provider%2Fmodel+triggered+this&collection=pi_mono_artifacts"
curl -sS "https://joelclaw.com/api/search?q=Breaks+TUI&collection=pi_mono_artifacts"
curl -sS "https://joelclaw.com/api/search?q=getAgentDir&collection=pi_mono_artifacts"

Those three alone cover:

  • repro expectations
  • the extension-vs-core boundary
  • an example of a small fix that got quick approval because the direction was obvious

That’s the difference between searching for facts and searching for patterns.

Install the public extension

git clone https://github.com/joelhooks/contributing-to-pi-mono ~/Code/joelhooks/contributing-to-pi-mono
cd ~/Code/joelhooks/contributing-to-pi-mono
npm install
mkdir -p ~/.pi/agent/extensions ~/.pi/agent/skills
ln -sfn ~/Code/joelhooks/contributing-to-pi-mono ~/.pi/agent/extensions/contributing-to-pi-mono
ln -sfn ~/Code/joelhooks/contributing-to-pi-mono/skills/contributing-to-pi-mono ~/.pi/agent/skills/contributing-to-pi-mono

Start a fresh pi session after that.

Then use the tool before you file anything upstream.

Under the hood

The backend implementation is later in the story because most people can just use the public API surface first. But for the folks who do want to copy the full pattern behind that API, here’s what I built.

I added a Restate-backed sync that materializes badlogic/pi-mono into a Typesense collection named pi_mono_artifacts.

It pulls in:

  • repo docs and package READMEs
  • issues and issue comments
  • pull requests and review comments
  • commits and releases
  • an evidence-backed maintainer profile
  • sync checkpoints for incremental refreshes

That is what keeps the public API and search surface useful instead of turning into a stale demo.

The actual lesson

This isn’t really about one issue.

It’s about turning maintainer pushback into reusable system memory.

If somebody sharp tells me my report is under-evidenced, I don’t want a private feeling about that. I want a public artifact that makes the next report better by default.

That’s what the corpus, the API, the extension, and the skill are for.

Not to automate contribution.

To automate the part where we stop being sloppy.