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.

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.

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.

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

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 — skill, CLI, library, graph and MCP server — distributed as a gem, a Docker image, and a Claude Code plugin.

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.

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.

One install carries the whole workflow, and that is the point:

• an Agent Skill, so your agent writes and curates the knowledge instead of you;
• a CLI and Ruby library, so it stays correct: validated, linted, and searchable in milliseconds;
• a Graph, so anyone can see the shape of what the team knows, live or as one static file you can host anywhere.

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

• okf mcp (okf-mcp) serves your bundles to any MCP host — fourteen read tools, over stdio or Streamable HTTP;
• okf tui (okf-tui) reads one bundle or every registered one, in a full-screen terminal UI;
• okf pro (okf-pro) writes an agent's knowledge repository — bundle, hooks, pre-commit, CI, skill — and then enforces it at three doors.

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 picture is the baseline gem — the kernel, and the CLI, Graph and MCP surfaces over it. okf tui and okf pro arrive through the same plugin seam, and every door is listed in What is in this repository.

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.

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.

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.

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.

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.

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.

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.

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.

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.