git-wiki

A self-maintaining knowledge wiki that lives in your own git repo. Your agent ingests sources, writes the pages, keeps cross-references current, and answers from the wiki. On-device hybrid search. No server, no SaaS, no DB — local commits by default, optional GitHub publishing.

bash <(curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh)

Features

• Compounds over time — every ingested source and answered query enriches the wiki.
• Your repo is the store — versioned, portable, shareable locally or via GitHub, diffs as a change log. Zero hidden state to corrupt.
• On-device hybrid search — BM25 + vector + LLM rerank via qmd. No external API, no embeddings uploaded anywhere.
• No server, no SaaS — the only runtime is bash, git, qmd, and optionally gh for GitHub sync.
• Agent-Skills standard — works with Claude Code, Cursor, Codex, Copilot, or any Agent-Skills-compatible agent.
• Lint for drift — stale dates, orphans, broken links, index drift, missing cross-references, and contradictions.

How it works

Three layers from the Karpathy LLM-wiki pattern:

1. Raw sources (sources/) — articles, papers, notes. Immutable; the LLM reads but never rewrites them.
2. Wiki pages (pages/, people/, concepts/) — LLM-owned markdown; synthesis accumulates here.
3. Schema (CLAUDE.md + SKILL.md) — conventions and workflows the LLM follows.

Two navigation files:

• index.md — content catalog, grouped by category. Read first on every query.
• log.md — append-only chronological record, grep-friendly (## [YYYY-MM-DD] <op> | <title>).

ingest                                        query
  │                                             │
  ▼                                             ▼
sources/ ──► wiki pages ──► index.md ──► answer with citations
                 ▲                  │
                 └───── qmd search ─┘

git-wiki vs classic RAG

Who this is for

• You read a lot (papers, articles, docs) and wish your agent remembered it.
• You want your knowledge portable, versioned, and yours — not locked in a vendor DB.
• You already work in an Agent-Skills-compatible editor (Claude Code, Cursor, Codex, Copilot…).
• You prefer plain markdown + git over proprietary formats.

This repo hosts the skill, not a wiki. Installing it gives your agent the git-wiki capability; running scripts/setup.sh creates your personal wiki as a separate repo. The installer creates a private GitHub repo by default, or a local-only repo with WIKI_VIS=local.

Pieces

Prerequisites

• gh authenticated (gh auth status) for GitHub-backed installs
• git with user.name and user.email configured
• node + npm (for npx skills add)
• qmd installed and available on PATH
• An Agent-Skills-compatible agent (Claude Code, Cursor, Copilot, …)

Install

One-shot (recommended)

bash <(curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh)

The installer will:

1. Check dependencies (git, node, npm, qmd, and authenticated gh unless using local-only mode).
2. Prompt for a wiki repo name, visibility (private, public, or local), local wiki path, and optional wiki subdirectory (blank = repo root).
3. Create the wiki repo: gh repo create --clone for GitHub-backed installs, or git init for WIKI_VIS=local.
4. npx -y skills add rarce/git-wiki — drops the skill into .agents/skills/git-wiki/ inside the wiki repo.
5. Runs the bundled scaffolder (.agents/skills/git-wiki/scripts/setup.sh), which lays out CLAUDE.md, config.yml, index.md, log.md, pages/, people/, concepts/, sources/, db/, registers the wiki with qmd under its own named index, commits, and pushes only when an origin remote exists. The scaffolder does not install external packages.

Non-interactive (env vars)

All four prompts can be pre-set (WIKI_SUBDIR defaults to the repo root; set it to e.g. wiki for a multi-purpose repo):

WIKI_REPO=my-wiki WIKI_VIS=private WIKI_DIR=~/wiki \
  bash <(curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh)

For a local-only wiki that is never published to GitHub:

WIKI_REPO=my-wiki WIKI_VIS=local WIKI_DIR=~/wiki \
  bash <(curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh)

Inspect-then-run (paranoid option)

curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh -o install.sh
less install.sh
bash install.sh

Manual install

If you prefer to run each step yourself — for example, to add the skill to a wiki repo you already have:

# 1. Create (or cd into) the wiki repo
gh repo create my-wiki --private --clone
cd my-wiki

# 2. Install the skill into this repo
npx -y skills add rarce/git-wiki

# 3. Run the bundled scaffolder
.agents/skills/git-wiki/scripts/setup.sh

For manual local-only setup:

mkdir my-wiki
cd my-wiki
git init -b main
npx -y skills add rarce/git-wiki
GIT_WIKI_LOCAL=1 .agents/skills/git-wiki/scripts/setup.sh

The scaffolder expects to be run from inside a git repo; it will not create or clone a repo for you.

Usage

From inside the wiki repo (or with WIKI_DIR set), invoke your agent and use any of:

• Ingest a source: "ingest this article: <url|path>"
• Query: "what do I know about <topic>?"
• Lint: "lint the wiki" — checks for stale dates, orphans, broken links, index drift, and missing cross-references.

The skill takes care of file layout, index/log updates, qmd re-embedding, and local commits. GitHub-backed repos can also push to origin.

Skill layout (this repo)

rarce/git-wiki/
├── README.md                      # this file
└── skills/
    └── git-wiki/                  # the Agent Skill itself
        ├── SKILL.md               # frontmatter + instructions
        ├── scripts/
        │   └── setup.sh           # bootstrap for the user's personal wiki
        └── assets/
            └── wiki-scaffold/     # files copied into the user's wiki on setup
                ├── CLAUDE.md      # wiki schema
                ├── config.yml     # wiki settings (qmd index, query logging)
                ├── README.md
                ├── index.md
                ├── log.md
                ├── gitattributes
                └── gitignore

See skills/git-wiki/SKILL.md for the full skill definition, triggering rules, and operation procedures.

Layout of the wiki setup.sh creates

<wiki-root>/
├── CLAUDE.md          # schema the LLM follows (loaded automatically)
├── config.yml         # wiki settings (qmd index name, query logging)
├── README.md          # short intro for humans browsing on GitHub
├── index.md           # categorized content catalog
├── log.md             # append-only chronological log
├── pages/             # general topic pages
├── people/            # one file per person (kebab-case)
├── concepts/          # one file per concept
├── sources/           # raw source notes (immutable)
└── db/                # reserved for the qmd index (gitignored)

<wiki-root> is the repository root for a dedicated wiki, or a subdirectory such as wiki/ for a multi-purpose repo (see below). The skill locates it by finding config.yml.

Wiki-only vs multi-purpose repos

By default the wiki occupies the whole repo. To keep a wiki alongside other content (code, docs) in the same repo, scaffold it into a subdirectory with WIKI_SUBDIR:

WIKI_SUBDIR=wiki \
  bash <(curl -sL https://raw.githubusercontent.com/rarce/git-wiki/main/install.sh)

or, when adding the skill to an existing repo manually:

WIKI_SUBDIR=wiki .agents/skills/git-wiki/scripts/setup.sh

This places config.yml and the wiki tree under wiki/. Each wiki uses its own qmd named index (set in config.yml as collection:), so several wikis can coexist without their search indexes colliding.

References

• Agent Skills — specification and overview
• skills.sh — the npx skills add CLI used to install this skill
• Karpathy's LLM-wiki gist
• qmd — Query Markdown
• GitHub CLI