okfm — OKF Manager
A Claude Code plugin for building and maintaining an Open Knowledge Format (OKF) knowledge base — a plain directory of markdown files with YAML frontmatter that a human can read, git can track, and any AI agent can consume without an SDK or server.
okfm gives you a set of commands to create that directory, keep its links and frontmatter consistent, generate concepts from existing sources, and read the whole thing back as a browsable HTML file. The engine is dependency-free stdlib Python 3, and every command previews its changes before writing.
What an OKF bundle is
A bundle is a folder of .md files. Each file (a "concept") has a YAML frontmatter block with at least a type, and a markdown body. Files link to each other with ordinary markdown links. Two filenames are reserved: index.md (a generated table of contents, one per directory) and log.md (a change log). That's the whole format — there's no database and no proprietary store. okfm is a manager for that folder, not a new storage system.
This plugin implements the OKF v0.1 spec. It is not affiliated with the upstream OKF project; it targets that spec and links to it above.
Who it's for
- Developers consolidating a repository's scattered knowledge into one agent-readable place.
- Anyone building a markdown "second brain" who wants structure and link-checking without adopting a heavier tool.
If you already keep notes as markdown (including in Obsidian — a folder of markdown is a valid vault), okfm works on that folder in place.
Install
In Claude Code:
/plugin marketplace add RadOrigin-LLC/okf-manager
/plugin install okfm@okf-manager
Requirements
- Python 3 on your PATH — nothing else to install: no
pip packages, no server, no API keys. (The enrich command is the exception: it uses Claude's own web-fetch capability; see its note below.)
Using it from other harnesses (the okf CLI)
The slash-commands below are the Claude Code surface, but the engine underneath is a plain command-line tool with no Claude dependency. Any agent — or you, in a shell — can drive it directly:
-
By path: python scripts/okf_check.py <bundle>, python scripts/okf_seed.py …, etc.
-
Via the unified dispatcher: python scripts <command> … (e.g. python scripts check <bundle>).
-
As a single zero-install file:
python build-okf-pyz.py # writes okf.pyz (stdlib only, no pip)
python okf.pyz check <bundle> # any platform
./okf.pyz check <bundle> # Unix (via the shebang)
Subcommands are the same operations as the slash-commands: new, add, convert, seed, move, check, map, find, scan. To use okfm from a non-Claude harness, point its instructions file (AGENTS.md, GEMINI.md, …) at the okf CLI and the bundle. enrich is the one flow that needs the harness's own web-fetch capability, since the engine never goes online.
Commands
Every command that writes shows you a preview first and asks before changing anything.
Get started
/okfm:start — guided onboarding: a short interview, an explanation of the capture filter (what's worth keeping), scaffolds a new bundle, and walks you through your first concepts./okfm:new — create one concept with valid frontmatter. --init bootstraps a fresh bundle (index.md, log.md, okf.json).
Bring existing material in
/okfm:add — import an existing markdown file: fill in only the missing frontmatter, place it, and wire it into the index. Your existing frontmatter and body are left as-is./okfm:convert — turn a single non-markdown file into a concept. Native formats: .txt, .html, .htm, .csv, .json. For PDF/docx, the agent extracts the text and writes it via new (the engine itself doesn't parse binaries). A # Citations section records the source./okfm:scan — walk a repo or notes folder and propose what's worth importing and where, applying the capture filter. Proposes only; you confirm before anything is written.
Generate concepts in bulk
/okfm:seed — create many concepts at once from a structured source. Three modes (auto-detected, or pass --mode):
- sqlite — one
Table concept per table, with a # Schema column listing.
- openapi — one
API Endpoint per path+method (OpenAPI), or one Schema per definition (JSON Schema).
- tree — one
File concept per file in a directory, preserving the directory structure; small text files embed their contents.
