[CONTEXT FOR AI ASSISTANTS] You're reading the agent markdown version of a post from JoelClaw (https://joelclaw.com). Author: Joel Hooks — software engineer building a personal AI operating system. How to use implementation details in this document: - Treat commands, code blocks, and config as reference implementations. - Preserve ordering and architecture, but adapt hostnames, paths, versions, and credentials. - Prefer details in blocks when present; they contain operational context removed from the human page. - Verify assumptions against the current repo/system state before executing changes. This is a narrative article from a real build. Technical details reflect Joel's setup and should be adapted to your environment. If you cite this, link to the original: https://joelclaw.com/contributing-to-pi-mono-with-a-public-maintainer-corpus If you quote Joel, attribute him by name. Don't paraphrase opinions as facts. Site index: https://joelclaw.com/sitemap.md Machine-readable: https://joelclaw.com/llms.txt Other posts on this site: - [The memory system that watches itself](https://joelclaw.com/memory-that-watches-itself.md) - [The healer was the killer](https://joelclaw.com/healer-was-the-killer.md) - [Agentic AI Optimization: Implementation Checklist](https://joelclaw.com/aaio-implementation-checklist.md) - [Agentic AI Optimization: Implementation Checklist](https://joelclaw.com/aaio-implementation-checklist.md) - [Redis, Dkron, Restate, and Sandboxes](https://joelclaw.com/redis-dkron-restate-and-sandboxes.md) - [Dogfooding Story 4: the queue observer earns dry-run, not enforce](https://joelclaw.com/dogfooding-story-4-queue-observer.md) - [AI Job Scheduling on Mac as Local-First Video Infrastructure](https://joelclaw.com/ai-job-scheduling-macos-launchd.md) - [Breakable Toys in the Wild: Apprenticeship Patterns and the joelclaw Experiment](https://joelclaw.com/breakable-toys-joelclaw.md) - [Utah and joelclaw: Convergent Architecture](https://joelclaw.com/utah-joelclaw-convergent-architecture.md) - [The Harness Is a Framework](https://joelclaw.com/the-harness-is-a-framework.md) - [The Agent Memory System](https://joelclaw.com/the-memory-system.md) - [JoelClaw is a Claw-like Organism](https://joelclaw.com/joelclaw-is-a-claw-like-organism.md) - [The Agent Writing Loop](https://joelclaw.com/the-writing-loop.md) - [Talon: the watchdog that finally bites](https://joelclaw.com/talon-watchdog-that-finally-bites.md) - [The Knowledge Adventure Club Graph](https://joelclaw.com/knowledge-adventure-club-graph.md) - [MineClaw](https://joelclaw.com/mineclaw.md) - [Build a Voice Agent That Answers the Phone](https://joelclaw.com/build-a-voice-agent-that-answers-the-phone.md) - [Plan 9 from Bell Labs: What Rob Pike Built After Unix](https://joelclaw.com/plan-9-pike-everything-is-a-file.md) - [Propositions as Sessions: What Armstrong Built and Wadler Proved](https://joelclaw.com/propositions-as-sessions-armstrong-wadler.md) - [Cache Components Patterns Skill for Next.js 16+ Applications](https://joelclaw.com/cache-components-patterns-skill-for-nextjs.md) - [Karpathy Says We're Building "Claws"](https://joelclaw.com/karpathy-claws-as-category.md) - [Voice Agent: A Rough Edge Experiment](https://joelclaw.com/voice-agent-deployment-deep-dive.md) - [Extending Pi Coding Agent with Custom Tools and Widgets](https://joelclaw.com/extending-pi-with-custom-tools.md) - [The Soul of Erlang Made Me Question Everything](https://joelclaw.com/soul-of-erlang-beam-evaluation.md) - [CLI Design for AI Agents](https://joelclaw.com/cli-design-for-ai-agents.md) - [Building a Gateway for Your AI Agent](https://joelclaw.com/building-a-gateway-for-your-ai-agent.md) - [Self-Hosting Inngest: A Background Task Manager for AI Agents](https://joelclaw.com/self-hosting-inngest-background-tasks.md) - [The One Where Joel Deploys Kubernetes... Again](https://joelclaw.com/joel-deploys-k8s.md) - [How I Built an Observation Pipeline So My AI Remembers Yesterday](https://joelclaw.com/observation-pipeline-persistent-ai-memory.md) - [Riding the Token Wave: Sean Grove at Everything NYC](https://joelclaw.com/riding-the-token-wave-sean-grove.md) - [Playing with AT Protocol as a Data Layer](https://joelclaw.com/at-protocol-as-bedrock.md) - [Building My Own OpenClaw on a Mac Mini](https://joelclaw.com/building-my-own-openclaw.md) - [Inngest is the Nervous System](https://joelclaw.com/inngest-is-the-nervous-system.md) - [OpenClaw: Peter Steinberger on Lex Fridman](https://joelclaw.com/openclaw-peter-steinberger-lex-fridman.md) [END CONTEXT] --- # Contributing to pi-mono with a public maintainer corpus > I turned one fair pi-mono maintainer pushback into a public search corpus, a pi extension, and a contribution skill so upstream work starts with evidence instead of guesses. By Joel Hooks · 2026-03-07T20:51:11.000Z Original: https://joelclaw.com/contributing-to-pi-mono-with-a-public-maintainer-corpus Mode: agent --- # Contributing to pi-mono with a public maintainer corpus 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`](https://github.com/joelhooks/contributing-to-pi-mono). ```bash 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: * [`joelhooks/contributing-to-pi-mono`](https://github.com/joelhooks/contributing-to-pi-mono) 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](https://x.com/badlogicgames/status/2031085220221563021) He linked that post directly to [pi-mono issue #1993](https://github.com/badlogic/pi-mono/issues/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: ```bash 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 ```bash 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.