Heirloom Handover Agent

Proof-backed handovers for inherited codebases. Every claim links to the command that verified it.

Comment

Inspiration

Every developer has inherited a repository whose README stopped being true years ago. The commands are stale, the tests may or may not run, and nobody knows which. AI "explain this codebase" tools make it worse: they describe what the code probably does, confidently, with nothing behind it. I wanted a handover you could audit.

What it does

Point Heirloom at any public GitHub repository and it takes the repo over on the record, in five stages:

  1. Read. Intake from the GitHub API, a static survey of the tree, and manifest forensics: entry points, scripts, lockfiles, workspaces, how long the repo has been idle.
  2. Plan. NVIDIA Nemotron 3 Ultra on Nebius Token Factory writes the first-day plan. It is screened for unsafe instructions before anyone sees it.
  3. Probe. Deployability claims are re-checked on a clean clone with real commands. A clone that contradicts the survey is recorded as contradicted, not smoothed over.
  4. Run. A sandboxed runner clones the repo, installs it and runs its own tests: Node.js (npm, pnpm, yarn, bun, workspaces and CI-defined commands), Python (packaged projects are installed with pip install -e ., then pytest), Go (go test ./...) and Rust (cargo test). When tests fail, Nemotron proposes fixes. These are tokenized and checked against an allowlist (no shell, ever) and run for a bounded number of repair cycles on the same clone.
  5. Report. The handover pack: a runbook, an architecture map, a risk register and the evidence ledger, where every line carries the command and exit code that proved it.

When something can't be verified, the run says so with states like unverified, stopped honestly or static verification only.

The landing page itself is live: its hero is a turning 3D map of a repository being probed file by file. Visitors can type any public repo to see a real intake from the GitHub API, then take it over in one click. An admin console shows who has used the product, daily activity, outcomes and inference spend.

How I built it

  • Nebius Token Factory + NVIDIA Nemotron in two tiers: Nemotron 3 Ultra (nvidia/Nemotron-3-Ultra-550b-a55b) plans, diagnoses failures and writes the risk analysis; Nemotron 3 Nano (nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B) runs the fast loop steps.
  • Convex for the database, realtime agent feed, auth (email/password and guest sessions) and the scheduled pipeline. API keys never leave the server.
  • A sandbox runner (Docker, with Node, Python, Go and Rust toolchains) hosted on Render: public clones only, refuses to run as root, argv-allowlisted commands with no shell, hard per-phase timeouts, and one working tree per repair session. A Convex cron keeps it warm.
  • Tavily researches dependency release notes on demand. Its results are never auto-trusted.
  • React 19, Vite and Tailwind v4 for the landing page, workspace, handover pack and admin console. One brand-token block drives every page, and phones get bottom-tab navigation.
  • 74 Vitest tests cover strategy resolution, fix-command screening (including the Go and Cargo rules), pack assembly and runner/client parity.

Challenges I ran into

  • Making model output safe to execute. Model-authored fixes are treated as untrusted input: tokenized, argv-screened against an allowlist, and discarded if unsafe.
  • Keeping the runbook and the real run from drifting apart. One resolved strategy feeds both, so the runbook can never describe commands the sandbox didn't run.
  • Infrastructure. My first runner sat behind a free tunnel with a 100-second cap, which killed runs on real repositories. Moving it to a hosted container removed the cap.
  • Honesty under failure. Designing states like contradicted and stopped honestly took more thought than the happy path.

Accomplishments that I'm proud of

  • Zero claims ship without a command and an exit code behind them.
  • The public sample is seeded verbatim from a real run, so the marketing can't drift from what the pipeline actually produced.
  • A full takeover of a small library, from intake to the finished risk register, takes about a minute and costs cents of inference.
  • Real takeovers going green across four ecosystems on the live app: JavaScript (kind-of), Python (cachetools), Go (google/uuid) and Rust (itoa), each for under 10 cents of inference.

What I learned

Agents get more trustworthy when they're forced to show their work. The evidence ledger made the model's mistakes visible and fixable instead of hiding them.

What's next for Heirloom

  • Java, Ruby and PHP execution, and splitting very large monorepo runs into background jobs so they aren't bound by a single 10-minute window.
  • A GitHub Action that re-verifies a repo's setup docs on every pull request and flags README drift.
  • Private repositories through a GitHub App.

Built With

Share this project:

Updates

Submission history