Site  ·  Docs  ·  Live demo  ·  Claude plugin  ·  Docker image

Your coding agent works out how your system fits together — why the service exists, what the metric actually measures, which line of the schema is load-bearing — and then the session ends and all of it is gone. Next session it works the same things out again, from the same code, and reaches slightly different conclusions.

okf gives that reasoning somewhere to live. Plain Markdown files in your repo, next to the code they explain, written and kept current by the agent itself rather than by you.

It adds nothing to your stack. No database, no service, no new place to keep knowledge — just files, reviewed in the same pull request as the code. If you stop using okf tomorrow, everything it wrote is still Markdown your team can read.

See it in sixty seconds

This repository documents itself in OKF, so you can walk a real bundle before installing anything:

gem install okf
git clone https://github.com/serradura/okf && cd okf
okf server .okf          # the whole ecosystem as an interactive graph

No Ruby on the machine? The published image runs the same commands — docker.okfgem.com. Or skip the clone entirely and open demo.okfgem.com.

Why it doesn't rot

Notes decay because keeping them current is a separate act from doing the work. Here it isn't:

• The agent writes it, not you. An Agent Skill ships with the gem, so curation happens inside the work rather than after it.
• Drift is a failing build. okf validate and okf lint return exit codes, so a stale or malformed bundle breaks CI the same way a broken test does.
• The agent reads only what it needs. okf index reads the map and okf search pulls the handful of files a task touches, so the knowledge outgrows the context window instead of filling it.

How it compares

Knowledge already has several homes near an agent, and each holds something different. None of the others is built for curated, durable team knowledge:

	OKF bundle (this)	CLAUDE.md / AGENTS.md	Agent auto-memory	Wiki / Notion
Holds	curated team knowledge	standing instructions	what one agent picked up	human docs
Versioned with the code	✅	✅	❌	❌
Portable across agents	✅ plain Markdown + YAML	⚠️ per-harness conventions	❌ per-agent store	⚠️ export needed
Typed and queryable	✅ frontmatter + graph	❌ prose	❌	⚠️ partially
Reviewed in PRs	✅	✅	❌ implicit	⚠️ rarely
Scales past one context window	✅ progressive disclosure (okf index + search)	❌ loaded whole	⚠️ partially	n/a
Checked by tooling	✅ exit codes for CI (okf validate + lint)	❌	❌	❌

The last two rows are this gem's job.

OKF is an open, vendor-neutral format (Google Cloud, 2026). This repository is a complete implementation of it, distributed as four gems, a Docker image, and a Claude Code plugin.

What a bundle looks like

A bundle is just a directory; each concept is one Markdown file whose path is its id. This repo documents itself in OKF, so the tree below is real:

.okf/
├── index.md                       # progressive-disclosure map (root carries okf_version)
├── log.md                         # ISO-dated change history, newest first
├── overview.md
├── gems/okf-mcp.md                # one concept = one file
├── decisions/monorepo-layout.md
└── format/frontmatter.md

The only hard requirement is YAML frontmatter with a non-empty type; everything else is optional and tolerated when missing. A concept reads as below — this is the real capabilities/graph-server.md from the baseline gem's own bundle, gems/okf/.okf/, with its body trimmed:

---
type: Capability
title: Interactive graph server (server)
description: A self-contained HTML knowledge graph — served over HTTP as a mountable Rack app, one bundle or many behind a hub, or written to a single static file.
resource: gems/okf/lib/okf/server/app.rb
tags: [server, graph, rack, diagram]
generated:
  by: human:maintainer
  at: 2026-08-13T12:00:00Z
---

# Overview

`okf server` boots an interactive view of the [graph](../model/graph.md) …

The .okf/ above is the ecosystem's map — a concept per gem, per plugin item, per skill — and each gem carries its own bundle beside its code. Clone the repo and run okf server .okf to browse the map as an interactive graph, or okf server gems/okf/.okf for the baseline gem's.

Trust, provenance, and lifecycle — OKF v0.2

Knowledge written continuously by agents raises questions a static corpus never had to answer: who wrote this, who checked it, is it still current? OKF v0.2 makes them frontmatter — generated (who produced the content, and when), verified (who confirmed it, deriving the trust tier every surface shows: unverified · machine-confirmed · human-reviewed), sources with per-claim footnote attribution, status, and stale_after — and this gem reads all of it: as catalog columns and --status/--trust filters, as the graph page's third visual channel, and as lint's provenance, attestation and migration findings. Every family is optional, and a v0.1 bundle keeps reading forever — two lint findings tell you exactly what a migration would change, and never fail you for not having done it.

The whole ecosystem

Knowledge an agent writes dies in four places, and a tool that fixes one of them only gets to watch it die in the next. It never gets written, because writing it up is a separate act from doing the work. It rots, and nothing says so until someone acts on a claim that stopped being true. It cannot be found, because the corpus outgrew the person who would have to read it all. And it is stuck in whichever tool wrote it, so the next tool starts over.

The pieces below are one answer per failure. They are separate gems because they install separately, not because they are separate products: every one of them reads the same folder of Markdown, none of them is required by any other, and what you would lose by dropping all of them is tooling, never the knowledge.

One install — gem install okf — carries three pieces:

• an Agent Skill, so the knowledge gets written at all: your agent curates inside the work rather than promising to write it up afterwards, and you stay the editor;
• a CLI and Ruby library, so you can ask the corpus a question instead of reading it — what is in here, which types and which tags, what links to what, what nothing links to, where the term you half-remember appears — and so drift is a failing build rather than a feeling: validate and lint answer with exit codes CI already knows how to fail on;
• a Graph, so the shape of what the team knows is a thing you can look at — live on your machine, or one self-contained HTML file you can host anywhere or hand to someone who will never install this.

Three sibling gems extend that same command rather than adding another one:

• okf mcp (okf-mcp), so the knowledge is not stuck in whichever terminal wrote it: any MCP host reads it with no shell and nothing pasted into context — fourteen read tools, over stdio or Streamable HTTP;
• okf tui (okf-tui), so looking around costs a keystroke instead of four commands: six views over one bundle or every registered one, and you can read one while searching all of them;
• okf pro (okf-pro), so the practice holds on the days nobody is watching: it writes an agent's knowledge repository and then refuses to let it rot, at three doors that each fail closed.

gem install okf-pro and you type okf pro. Packaging multiplies; the interface does not, and a sibling ships no second binary to learn.

The second bundle costs nothing

Nobody stops at one. The service you documented last month, the team handbook, the gem you maintain on the side — each is its own bundle in its own repository, and that is the right answer rather than a filing problem to clean up later.

So a bundle gets a name. okf registry set ./handbook makes it @handbook, and anywhere a directory goes a @slug goes: okf lint @handbook, okf render @handbook -o graph.html. Groups collect the ones you think about together, and @all reaches every one you have registered — so the same four commands hold your whole corpus at once instead of one bundle of it:

okf search @all "rate limit"   # every bundle, ranked together in one list
okf server                     # all of them behind one hub, in the browser
okf tui                        # all of them in one terminal UI
okf mcp                        # all of them, to any MCP host

A project-local .okf.json replaces the machine-wide registry while you stand inside that repository. That is how this monorepo addresses its own five bundles as @okf-eco, @okf, @okf-mcp, @okf-tui and @okf-pro without anyone's ~/.okf ever hearing about them.

How the pieces fit together

Everything above the first divider is what one gem install okf gives you. Everything below it arrives through the same plugin seam, one gem at a time, and every door is listed in What is in this repository.

Tip

Browse this repository as knowledge, not just docs. This README is the front door; the depth lives in the five OKF bundles it carries. Start at the ecosystem map — the gems, the plugin, the skills, the decisions and the format itself — then open a gem's own bundle for its code: gems/okf/.okf/. Run okf server .okf to walk the map as an interactive graph, or okf search @all <term> to reach every bundle at once.

It installs on the Ruby your OS already ships — every Ruby since 2.4, three small dependencies, no native extension and no build step — so there is nothing to provision and nothing to keep up to date. The design constraints that hold that line are enforced by tests on every supported Ruby.

What is in this repository

Every top-level name is a boundary, and the whole menu is one row each. A directory under gems/ is a gem, named for the gem it ships; everything else at the root is named for what it is.

Door	What lives there
gems/okf/	the okf gem — the agent skill, the CLI and library, ranked search, the graph. Everything above describes this one
gems/okf-mcp/	okf mcp — the MCP server over the same kernel: 14 read tools, any MCP host
gems/okf-tui/	okf tui — the full-screen terminal UI, over one bundle or every registered one
gems/okf-pro/	okf pro — writes an agent's knowledge repository, then enforces it at three doors
plugin/	the Claude Code plugin: that skill, /okf:gem, and a post-edit curation hook
.claude-plugin/	the marketplace manifest — this repository is its own marketplace
skills/	the skills a generic installer reads: okf, and okf-principles
resources/	copy-paste recipes — today, CI that validates and lints your bundles on every push
.okf/	the ecosystem map: a concept per gem, per plugin item, per skill — plus the decisions and the format
.okf.json	every bundle in this tree, addressable as @slug from anywhere in it
Dockerfile	builds the published image from gems/okf/, from a root build context
.github/	the CI workflows, and the images this page renders
.claude/	one line, pointing Claude Code at AGENTS.md

The graph

The graph server on this repo's own .okf bundle, with the overview concept selected. Try it live at demo.okfgem.com.

What the page does, and how okf render bakes the same thing into one static file: gems/okf/README.md.

Claude Code plugin

This repository doubles as a Claude Code plugin marketplace, so the whole toolchain installs with two commands inside Claude Code:

/plugin marketplace add serradura/okf
/plugin install okf@okfgem

The plugin carries three pieces: the okf skill; /okf:gem, a front door that hands its arguments to the skill unchanged (no arguments: it orients on your bundle and recommends the next move, never auto-runs); and a curation hook that runs okf validate + okf lint after every edit inside a bundle and returns the findings as context. The checks are the CLI's own, so the feedback is deterministic.

The hook stays silent outside bundles, and it is config-free to switch off: OKF_CURATE_DISABLED=1 turns it off, OKF_CURATE_QUIET=1 keeps the findings without the install suggestion, and an <!-- okf-disable --> comment skips one file.

Prefer no plugin? gem install okf && okf skill .claude installs the skill alone, and the skill itself instructs the agent to run the same checks after editing a bundle.

The skill, without the gem

Without the gem, any agent that reads SKILL.md installs it straight from this repository:

npx skills add serradura/okf                          # choose from the list
npx skills add serradura/okf --skill okf -a codex     # or name skill and agent

That path installs a generated copy — rake skill:sync writes it from the same canonical tree the gem ships, and the build fails on any drift — so it tracks this repository rather than the okf on your machine. okf-principles sits beside it: the five structural principles the format implies, written to be pointed at any instruction artifact rather than at a bundle.

Extending okf, and running it safely

Publish a gem named okf-* carrying an okf/plugin.rb and installing it is the whole installation: your verb answers to okf and behaves like a built-in. Nothing an addon registers can displace one, and a broken addon is skipped rather than taking the CLI down. The three siblings above arrive exactly this way — okf-mcp, okf-tui and okf-pro each ship an okf/plugin.rb and no executable of their own — and none of them needs a line of the baseline to know it exists. Yours would be the fourth, on the same terms. Contract and threat model: extension points.

The graph page treats a bundle as untrusted content: inlined data is escaped, and every concept body is sanitized before it reaches the DOM, so a script hidden in Markdown is stripped rather than run. It still loads libraries from a CDN, so treat an unfamiliar bundle the way you would treat any document from a source you do not know. Full write-up: server trust boundary.

Development

From the repo root — plain rake, there is no root Gemfile:

rake              # every gem's default task (tests + RuboCop), then the repo-level lint
rake test         # every gem's test suite
rake okf          # validate + lint every registered .okf bundle
rake serve        # browse this project's own bundle as a graph

From any gem's directory, for work on that gem — cd gems/okf-mcp, cd gems/okf-tui or cd gems/okf-pro follows the same three commands, and each has its own README and CI job. From gems/okf, for work on the baseline itself:

cd gems/okf
bin/setup               # install dependencies
bundle exec rake        # tests + RuboCop (what CI runs)
bundle exec rake test   # just the test suite
ruby -Ilib exe/okf validate <dir>   # run the CLI from a checkout

The suite runs on every supported Ruby; to check the 2.4 floor locally, from the repo root:

docker run --rm -v "$PWD":/src:ro ruby:2.4 bash -c \
  "cp -a /src /build && cd /build/gems/okf && rm -f Gemfile.lock && bundle install --quiet && bundle exec rake test"

The graph page has its own suite in a real browser (bundle exec rake browser:setup, then rake test:browser, both from gems/okf/). See AGENTS.md for the maintainer guide.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/serradura/okf. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the Apache License 2.0 (see LICENSE.txt). The Open Knowledge Format specification bundled with the skill is authored by Google Cloud Platform and included under its own Apache-2.0 license, Copyright (c) Google LLC. See NOTICE and okf/lib/okf/skill/reference/APACHE-2.0.txt.

okf-skills by Marco Boffo, a Python OKF toolkit for Claude Code with a feature-rich interactive graph view, was an early inspiration for this gem's Claude Code plugin and for the knowledge-as-code comparison in How it compares. okf takes a different shape: a Ruby-native gem built around the okf CLI and an embeddable library.