okfy

OKFy

Tooling that eases context assembly for models. When a full knowledge base is too large for any context window — or actively harmful, diluting the model's attention with task-irrelevant material — OKFy extracts knowledge from corpora (codebases, docs, research collections) into purpose-shaped OKF Bundles and gives models precise access to just the slice a task needs. An OKF Bundle is a self-contained directory of Markdown concepts with YAML frontmatter, shaped by a declared Purpose and consumable by any agent — even one without OKFy installed: raw file traversal works, the CLI makes it fast, MCP makes it a tool surface.

The pipeline is split by responsibility. Everything deterministic — validation, indexing, BM25 retrieval, lexicon-driven query expansion, segmentation, eval records, write gates, packaging — lives in an agent-neutral Python core (core/, PyYAML is its only dependency, zero LLM calls). The LLM-driven work — the Purpose Interview, schema design, blind parallel extraction, consolidation, and the judgment inside a lexicon or an eval verdict — is an agent workflow driven by Claude Code plugin commands that call that core CLI. The core is the machine; the agents supply judgment on top of it. Retrieval is deliberately vector-free: BM25 plus a reviewed, machine-readable lexicon closes the cross-language gap deterministically, so the same query returns the same answer, every run, auditable.

Extraction quality is not self-certified. OKFy makes no claim that a bundle is good because the model that built it said so. Acceptance is a replayable artifact: okfy eval run replays the bundle's own test queries deterministically, an LLM-judge may propose verdicts, but only an owner verdict counts toward release — a bundle grading its own output is a closed loop this design refuses to trust. The verdicts, the query-expansion contract, and every "this concept is no longer current" flag are recorded inside the bundle, not in a chat transcript.

Install

Core CLI (Python 3.11+, uv):

git clone https://github.com/vsov/okfy && cd okfy
uv tool install ./core        # installs the `okfy` command

Claude Code plugin (adds /okfy:new, /okfy:extract, /okfy:eval and friends):

/plugin marketplace add vsov/okfy
/plugin install okfy@okfy

The plugin drives the interviews and extraction; it shells out to the okfy CLI for every deterministic step, so the core must be installed first.

Quickstart

/okfy:new    <corpus-path> <bundle-path>   # Purpose Interview → Survey → Extraction Plan
#   ↳ review and approve the plan  (the single mandatory checkpoint)
/okfy:extract <bundle-path>                # blind parallel Workers → Consolidate → Validate → package
/okfy:eval    <bundle-path>                # replay your test queries; you judge the verdicts

/okfy:new interviews you about what the Bundle is for, surveys the corpus, designs a schema from a Purpose Archetype (decision-support for prose corpora, codebase-map for changing code, api-reference for using an API), and writes an Extraction Plan you approve. /okfy:extract runs blind parallel extraction, consolidates drafts into final concepts, validates against the OKF spec with strict source checking, and packages the Bundle (index, README, AGENTS.md, silent git init, structured commits, an extraction ledger). /okfy:eval replays your ten test queries and records your verdicts — the bundle stays provisional until you have judged every one.

The User Guide walks both tracks end to end — §6 is the step-by-step procedure for OKFying a text corpus and a codebase, §11 explains how bundle quality is verified and why the owner, not the model, signs off.

CLI reference

The core CLI is agent-neutral and usable directly. Run okfy <command> --help for full options.