Heir - The right to repair, for open source.

An autonomous AI caretaker for abandoned open-source repos: it triages a GitLab backlog, self-diagnoses a real bug from the source, and opens a Draft merge request for a human to review and merge.

Comment

Inspiration

Open source runs on the unpaid labor of maintainers - and maintainers burn out. When one walks away, the project doesn't die loudly; it just goes quiet. Issues pile up, fixes never come, and the people still depending on it are stuck. We kept finding these graveyards: libraries with thousands of users and a backlog no one has touched in years. We wanted to give those projects a caretaker - something that could do a maintainer's first hours of work and hand back a reviewable change, without ever taking control. That's the right to repair, for open source.

What it does

Heir inherits an abandoned repository and works as two separate agents:

  • Triage reads the entire open-issue backlog, classifies every issue (bug / feature / question / maintenance / meta), flags good first issues, and names the single strongest, safest fix candidate - as a structured report. It is read-only by construction: it is given no tools that can write to the repository.
  • Fix takes one issue, reads the issue and the source, diagnoses the root cause itself, writes a minimal fix to a dedicated branch, and opens a Draft merge request explaining its reasoning. It never merges - a human reviews, and the repository's own CI runs against the change.

The target repository and issue are supplied at run time, so Heir works on any repository and any issue.

How I built it

Heir is two independent agents built with the Agent Development Kit (ADK)- the code-first path of Google Cloud Agent Builder - running on Cloud Run, reasoning with Gemini on Vertex AI, and talking to GitLab over the Model Context Protocol (MCP). The triage agent's MCP toolset is filtered down to a single read-only operation, which makes "read-only" a structural property rather than a prompt request. The fix agent has the write operations it needs (branch, commit, merge request) but is gated to only ever open a Draft. We pass the target repo and issue as ADK session state, injected into each agent's instructions, so one service handles any project.

Challenges I ran into

  • GitLab's first-party MCP server authenticates only through interactive, browser-approved OAuth - which a headless Cloud Run service can't complete (a personal token returns 403 against the MCP scope). We integrated GitLab through an open-source MCP server that speaks the same protocol and the same operations server-to-server.
  • The model occasionally serialized newlines as literal characters, which would have corrupted a committed file. Instead of hoping a prompt would fix it, we added a callback that sanitizes tool arguments at the boundary - so it can't happen, whatever the model emits.
  • For reliability and safety we chose two independent agents over a single router, so the read-only guarantee holds by construction and the demo path stays simple.

Accomplishments I'm proud of

  • Triage that is read-only by construction - a safety property you can verify, not merely trust.
  • A fix agent that genuinely self-diagnoses: it is never told what the bug is; it reads the code and works it out.
  • Heir's Draft MR passes the target repo's own CI, green - the honest answer to "does the fix actually hold up?"
  • A live interface where anyone can trigger a real triage run and watch Heir classify the backlog.

What I learned

For autonomous agents that write to real systems, structural boundaries - tool filters, draft gates, argument sanitizers - matter far more than instructions. ADK + MCP is a clean way to give an agent real, scoped capabilities, and session state is the right place to parameterize "which repo, which issue." And keeping a human in the loop isn't a limitation; it's what makes an autonomous contributor trustworthy enough to actually use.

What's next for Heir

Today Heir reliably does one thing well: pointed at an issue, it self-diagnoses, opens a CI-verified Draft merge request, and stops for human review. The path to a maintainer-grade caretaker builds outward from that core - each step widening autonomy while keeping the human-in-the-loop guarantee intact:

  • Autonomous issue selection - close the loop between the two agents so Heir acts on triage's own recommendation, choosing what to repair first, not just how.
  • Closed-loop self-repair - go past typecheck: run the project's full test suite, read the failures, and iterate on the fix until the pipeline is green - the honest equivalent of a maintainer's edit–test–repeat.
  • Event-driven operation - trigger Heir by labeling an issue (a GitLab webhook), so a maintainer can hand off work and walk away while a Draft MR appears for review.
  • Backlog mode - work several issues in one pass, each on its own isolated branch and Draft MR, with failures contained so one bad fix never blocks the rest.
  • Safe multi-project operation - project-scoped credentials, protected-path guardrails, rate limits, and observability, so Heir can be trusted across many repositories at once.
  • Beyond one ecosystem - more languages and frameworks, reaching deeper into the long tail of abandoned projects that need a caretaker.

The throughline never changes: Heir does more of a maintainer's work autonomously - and always hands the keys back to a human.

Built With

Share this project:

Updates

Submission history