@dzangolab/repokb

CLI tool that drops a knowledge base into a project: a knowledge/ directory in Open Knowledge Format (OKF) v0.2, four Claude Code skills that read from and write to it, and a CLAUDE.md section that tells every session to consult it.

The code is the source of truth for what the system does. The knowledge base is the source of truth for why, how we learned it, and what to watch out for.

Usage

Requires Node.js 20.12 or later. Run it from the root of the project you want to document - nothing to install:

npx @dzangolab/repokb init

To get the repokb binary on your PATH instead:

npm install -g @dzangolab/repokb
repokb init

Scaffolding a knowledge base

repokb init asks where the knowledge base should live, defaulting to knowledge/, then writes three things: the bundle itself, the four skills as a repokb plugin under .claude/skills/repokb/, and a knowledge base section into the project's CLAUDE.md.

repokb init

| Option | Effect | | ------------------ | ------------------------------------------------------------------------------- | | -d, --dir <name> | Directory to hold the knowledge base. Default knowledge, and skips the prompt | | -b, --bootstrap | Hand off to Claude Code when the scaffolding is done, skipping the prompt | | --no-bootstrap | Scaffold only, and never hand off | | -h, --help | Show help for the command | | -V, --version | Print the version (on repokb itself) |

repokb init --dir second-brain

The name must be a single directory name - no path separators, not . or .., not wiki (used inside the bundle), and not starting with _ (which marks an operational directory). Every template reference is rewritten to match the name you choose, so --dir second-brain produces skills that talk about second-brain/, not knowledge/.

The skills

repokb init installs all four as a single Claude Code plugin, so they share the repokb namespace and are invoked as /repokb:<skill>:

.claude/skills/repokb/
  .claude-plugin/plugin.json
  skills/
    load/ init/ ingest/ ingest-conversation/

Claude Code discovers the plugin when a session starts - restart any session that was already running before repokb init.

/repokb:load - read the knowledge base

Loads the index hierarchy first, then only the concepts that matter, and reports the trust and freshness of everything it loaded.

| Invocation | Loads | | ------------------------------- | --------------------------------------------------------------- | | /repokb:load | Indexes plus the orientation set, from wiki/ | | /repokb:load <topic> | Indexes, then everything relevant to <topic> | | /repokb:load --section <name> | Every concept in one section, e.g. --section architecture | | /repokb:load --full | Every concept document in the bundle, _sources/ included | | /repokb:load --audit | Health report only: staleness, trust, index drift, broken links |

Use it at the start of a session, before answering questions about how the repo works, and before changing an unfamiliar part of it.

/repokb:init - bootstrap from the repository

Run once, after scaffolding. Surveys the codebase, interviews you for what the code cannot tell you, plans, then writes the first concept documents.

| Invocation | Effect | | ------------------------------- | --------------------------------------------------------- | | /repokb:init | Survey, interview, plan, write | | /repokb:init --dry-run | Produce the plan and stop; write nothing | | /repokb:init --section <name> | Bootstrap one section only, e.g. --section ci | | /repokb:init --no-interview | Skip the questions - everything written is then inference | | /repokb:init --yes | Skip the plan confirmation and write |

/repokb:ingest - pull in external material

Extracts a source, distills it into concept documents under knowledge/_sources/external/, archives the original in knowledge/raw/, and updates the affected index.md and the day's log file.

| Invocation | Effect | | ----------------------------------------------- | ------------------------------------------------------ | | /repokb:ingest <url> | Web page or online document | | /repokb:ingest <path> | Local file: pdf, docx, image, md, txt, csv, video | | /repokb:ingest <path-or-url> --into <section> | Route to a section other than _sources/external | | /repokb:ingest <url> --deep | Follow and ingest linked sub-pages of a doc site | | /repokb:ingest <path> --verbatim | Also keep a full extraction alongside the distillation |

An ADR is archived verbatim under knowledge/raw/adrs/ whatever its status, and stays there - the record itself never becomes a wiki document. Only a decided one - accepted, rejected, deprecated, or accepted - is then distilled into _sources/, with the wiki concepts it bears on updated to match. An ADR still under discussion is archived and nothing else, so the wiki never presents a proposal as settled.

/repokb:ingest-conversation - capture a working session

Distills what a session established - decisions made, constraints discovered, bugs diagnosed, approaches ruled out - into concept documents, and writes a session record under knowledge/_sources/conversations/. The conversation itself is archived as verbatim as it can be under knowledge/raw/conversations/, named to match its session record, so the exact wording survives the distillation.

| Invocation | Effect | | -------------------------------------------- | ------------------------------------------------------------------------ | | /repokb:ingest-conversation | Triage the whole session and write what is durable | | /repokb:ingest-conversation <focus> | Only what relates to <focus> | | /repokb:ingest-conversation --dry-run | Show the triage and proposed routing, write nothing | | /repokb:ingest-conversation --session-only | Write only the transcript and session record, skip promoting to concepts |

What gets scaffolded

knowledge/
  index.md          # bundle root - table of contents, carries okf_version
  CLAUDE.md         # the authoring contract every writer reads first
  wiki/             # what this repository knows about itself
    architecture/ ci/ components/ conventions/ domain/
    local/ operations/ reference/ security/ troubleshooting/ ui/
  raw/              # originals behind ingested material - human-only
    images/ pdfs/ documents/ adrs/ conversations/ others/
  _log/             # change history, one file per day (YYYYMMDD.md)
  _sources/         # ingested external material
    external/ conversations/

Every concept document carries OKF provenance and trust metadata, and /repokb:load reports it on every load: status: draft means inferred rather than confirmed, a missing verified key means nobody has checked it, and a past stale_after means possibly out of date.