Buddy — Your friendly repo onboarding agent

Hi, I'm Buddy 🤝

I help brand-new contributors feel at home in any code repo — fast. I explain things like you're 10, write everything down in plain Markdown, and travel with the repo so the next person benefits too. Works with GitHub Copilot CLI, Claude Code CLI, Codex CLI, and OpenCode.

npm install -g @prustogi/buddy

Friendly by design: Buddy never invents facts, never stores secrets, and never reaches outside your repo for memory. Everything it learns is written to .buddy/ as plain Markdown — readable by humans, reviewable in a PR, portable between machines.

A teammate for day one,
and every day after

Most repos punish newcomers with stale READMEs and tribal knowledge. Buddy fixes that — it builds a friendly onboarding doc set right inside your repo, then keeps it fresh as the code changes.

📖

Explained like you're 10

Short sentences. Plain words. Real examples. No jargon dumps. If a term is fancy, Buddy defines it in one line.

🗂️

Portable knowledge

Everything lives in a .buddy/ folder at your repo root. Markdown for humans, small JSON for indexes. No databases, no embeddings, no global caches.

🐙

Git-friendly & shareable

Commit .buddy/ with your code. The next person who clones the repo gets the same onboarding instantly — no re-indexing required.

🔗

Captures team links safely

Drop in a runbook, design doc, or wiki URL. Buddy files it under tags and redacts secrets in URLs (tokens, keys, passwords) before saving.

🔄

Stays fresh on every commit

Run buddy status or buddy precheck before a PR. Buddy flags which docs are likely stale based on what you just changed.

🛡️

Honest about uncertainty

If Buddy isn't sure, it says so — and writes the gap to NOTES/open_questions.md with a hint about which file to check next.

🎮

Interactive tour (new in 0.5)

Run buddy tour to get a single self-contained .buddy/tour.html. Double-click to open. Scroll-driven cards, a graduation quiz with real repo facts, and zero install.

🎯

Starter tasks, auto-found

The tour ships with curated warm-ups and auto-detected TODO / FIXME notes from the codebase — instant tiny PR ideas for day one.

Three commands to a friendlier repo

Install

Install Buddy globally from npm:

npm install -g @prustogi/buddy

Initialize

This scaffolds .buddy/, installs the Buddy agent for Copilot CLI (.github/agents/), Claude Code (.claude/agents/), Codex CLI (AGENTS.md), and OpenCode (.opencode/agent/), and opens the welcome page.

cd your-repo
buddy init

Meet your buddy

Launch your AI CLI of choice in the same folder, then ask Buddy to scan the repo and fill in the docs.

# GitHub Copilot CLI
copilot
/agent     # then pick "buddy"

# — or — Claude Code CLI
claude
@buddy

# — or — Codex CLI
codex      # Buddy instructions pre-loaded via AGENTS.md

# — or — OpenCode
opencode   # press Tab to switch to the "buddy" agent

Plain files. Nothing magic.

Open the folder. Read it. Edit it. Diff it. Commit it. It's just Markdown and a tiny JSON index — designed to live in your git history forever.

.buddy/ ├── README_FOR_HUMANS.md ← start here (the home page) ├── GETTING_STARTED.md ← prerequisites, install, build, run, test ├── ARCHITECTURE.md ← components, responsibilities, data flow ├── TECH_STACK.md ← languages, frameworks, build tools ├── INTEGRATIONS.md ← DBs, queues, auth, external APIs ├── CHANGELOG_SUMMARY.md ← human-friendly recent changes ├── STARTER_TASKS.md ← curated warm-ups + auto-found TODOs ├── LINKS.md ← curated team links (with “why it matters”) ├── tour.html ← interactive onboarding webpage (self-contained) ├── manifest.json ← last_indexed_commit + timestamps ├── MAP/ │ ├── repo_map.md ← top-folder purposes; where to start reading │ ├── entry_points.md ← servers, CLIs, jobs, schedulers │ └── data_flow.md ← request comes in → where it goes ├── INDEX/ │ └── links.json ← machine-readable mirror of LINKS.md └── NOTES/ ├── open_questions.md ← what Buddy couldn't infer, and where to look └── assumptions.md ← assumptions, never presented as fact

Six small commands

buddy init

Create .buddy/, install the agent, open the home page. Safe to re-run — it never overwrites your edits.

buddy open [doc]

Open any Buddy doc by name: home, architecture, getting-started, links, etc.

buddy status

Show whether .buddy/ is up to date with the latest commit. Lists what changed since the last index.

buddy link <url>

Capture a doc link. Adds a friendly entry to LINKS.md and a tagged record to INDEX/links.json. Secrets in URLs are redacted automatically.

buddy precheck

Before you commit, see which Buddy docs are likely stale based on the files you changed.

buddy agent install

(Re)install for Copilot CLI. Use --claude for Claude Code, --codex for Codex CLI, --opencode for OpenCode, --all for all four. buddy agent list shows what's installed where.

buddy tour

New in 0.5. Build the interactive .buddy/tour.html and open it in your default browser. Self-contained, no server, double-clickable.

Boring, on purpose

🔒 Won't leak secrets

Buddy redacts tokens, API keys, passwords, and OAuth fragments from any URL it captures — even if you paste them by accident.

📍 Stays in your repo

No external databases. No embeddings. No global caches. No home-directory state. If you delete .buddy/, Buddy forgets — by design.

📝 Cites its evidence

When Buddy answers a question, it points to the file (and line range) it learned from. If it's guessing, it says so.

🤲 Hands you the wheel

Every doc is plain Markdown. Edit anything. Buddy treats your edits as truth on the next run.

A teammate for day one,and every day after