Knowledge management for markdown knowledge bases ("brains"): a Claude Code skill, and the km
command and GitHub Action that keep a brain consistent.
- Answer a question from the brain, with sources.
- Save a note, decision or meeting transcript with validated frontmatter, in the right folder.
- Update or supersede a page, lint the brain, mount peer brains as submodules.
- Contribute to a brain you only read, as a pull request.
- Set up a shared team brain: one maintainer merges, the team reads the repo, CI validates
every PR, keeps each folder's
_index.mdgenerated and reachable, builds a per-audience bundle for AI tools, and demotes accepted docs whose review date has lapsed.
As a Claude Code plugin:
/plugin marketplace add pasrom/km
/plugin install km@km
/km init # bootstrap a personal knowledge repo
/km init --team # bootstrap a shared team brain
/km What do we know about thermal management? # search and summarize
/km We decided to use LTC6813 # save content (auto-detects type)
/km update sensor-fusion: add calibration # modify a document
/km brain add https://github.com/org/team-brain.git # mount another brain
/km @all Zephyr RTOS # search all mounted brains
/km upgrade # move the brain to the installed km version
/km check my setup # what this computer still needs for the brain (km doctor)
/km help # all commandsCross-repo brains: other knowledge repos are mounted as git submodules under brains/. Each
brain keeps its own access permissions, brains update when queried (if older than 15 minutes), and
every answer cites [brain@commit].
km validate [FILE ...] frontmatter, links, the gate, index completeness
km gen-index [--check] regenerate every '## Documents' list in _index.md
km demote [--apply] demote served docs past their review date
km serve build the per-audience bundle under dist/served/
km promote ... move a note into the brain as a review doc
km approve DOC... --by WHO sign review docs off; ai:<model> only where the doc says approval: ai
km init DIR [--team ...] create a brain from the templates
km upgrade move a brain's km pins to this version
km doctor [--offline] check this computer is set up for the brain
km doctor reads what to expect from the brain alone: its origin, the brains it mounts
(.gitmodules), the km version it pins, and the plugins its .claude/settings.json enables
(enabledPlugins, with the marketplaces in extraKnownMarketplaces). A brain lists its plugins there
for Claude Code anyway, which offers to add the marketplace when the folder is trusted. Each check
that fails names its fix; it needs no PyYAML, so it also runs on a computer that is half set up.
Every command takes --root DIR; the default is the git work tree around the current directory.
Install a release by its commit (git ls-remote https://github.com/pasrom/km refs/tags/v1.3.0 shows
it), not by the tag: pip install git+https://github.com/pasrom/km@<commit> # v1.3.0, or run it
without installing: uvx --from git+https://github.com/pasrom/km@<commit> km validate # v1.3.0.
Brains carry no km code. km init writes CONVENTIONS.md, CLAUDE.md, schema.local.yaml,
inbox/, a .gitattributes that keeps text files LF, and a pre-commit hook pinned to a km version. km init --team adds domain folders with
generated indexes, a README, and CI that installs km through this repository's GitHub Action:
- uses: pasrom/km@<commit> # v1.3.0, installs the km CLI at that commit
- run: km validate
- run: km gen-index --checkThe pre-commit hook works the same way (repo: https://github.com/pasrom/km,
rev: <commit> # frozen: v1.3.0, id: km-validate). Every pin names a release by its commit, so a
tag moved later cannot change what a brain runs; the version rides along as a comment, and
km upgrade checks that the commit is that release's. km's own dependencies are pinned to exact
versions. km init and km upgrade look a release's commit up by its tag once, so a release tag here
must never be moved or deleted; a repository ruleset on v* makes sure of it. Dependabot
and pre-commit autoupdate --freeze propose newer versions; /km upgrade moves the pins and turns
a brain from the copy-in days into one that pins km.
.claude-plugin/ plugin and marketplace manifests
action.yml GitHub Action: installs km at the action's version
.pre-commit-hooks.yaml pre-commit hook km-validate
src/km/ the package: cli, validate, gen_index, demote, serve, promote, init, upgrade, doctor
src/km/templates/ what `km init` writes
skills/km/SKILL.md the skill; skills/km/bin/km runs the package from the installed plugin
tests/ smoke tests
The smoke tests need Python 3.11+, PyYAML and git: bash tests/gate_smoke.sh, index_smoke.sh,
team_smoke.sh, doctor_smoke.sh. CI runs all four plus the GitHub Action on every pull request, and
encoding_smoke.sh on Windows (team_smoke runs it on macOS under non-UTF-8 locales). A release bumps
__version__ in src/km/__init__.py, version in .claude-plugin/plugin.json and the version in
this README together; merging that to main is the release, CI tags vX.Y.Z once main is green.
km started inside dotclaude and was moved here with its history.
MIT