md2okf

Compile Markdown documents into an OKF knowledge base with a coding agent.

Point md2okf at a Markdown file or folder and a coding agent writes a wiki into the output directory: a page per topic, an index in every directory, links between them, and a log of what each run changed. OKF, the Open Knowledge Format by Google, is a tree of Markdown files with YAML frontmatter and nothing else — no schema registry, no server, nothing to install. The agent takes one source document per run and folds it into the wiki already on disk, so documents accumulate rather than overwrite. SPEC.md is the OKF specification the wiki is built against; the agent reads it at the start of every run, and it outranks any other instructions.

---
config:
  flowchart:
    nodeSpacing: 35
    rankSpacing: 45
---
flowchart LR
  subgraph IN[" "]
    direction TB
    SPEC@{ shape: doc, label: "okf spec<br>SPEC.md"}
    MD@{ shape: docs, label: "source documents<br>md/*.md"}
    STATE["session traces<br/>~/.local/state/md2okf/*/sessions"]
    DRV["host driver<br>md2okf -o okf/ md/"]
    KIT["kits/*/spec.yaml<br/>kits/*/files/"]
  end

  subgraph VM["sbx microVM"]
    AGENT["coding agent<br/>(Pi, Claude Code or Codex)"]
    LINT["okfctl linter"]
    TOOLS["skills<br>/inspect-md<br/>/compile-okf<br/>/inspect-okf<br/>/merkle-okf<br/>/curate-okf<br/>/size-okf"]
    PROXY["credential proxy"]
  end

  subgraph OUT[" "]
    direction TB
    OKF@{ shape: docs, label: "okf/<br/>the wiki"}
    NET("OpenRouter hub")
    NET3("Anthropic, OpenAI")
  end
  NET1("DeepInfra")
  NET2("...")

  SPEC -.->|"outranks all"| AGENT
  MD ==>|"read by"| AGENT
  STATE -.->|"mounts"| VM
  STATE ~~~ AGENT
  DRV -->|"sbx exec"| AGENT
  KIT -->|"builds"| VM
  AGENT -.->|"runs"| LINT
  LINT -.->|"must pass"| OKF
  AGENT ==>|"writes"| OKF
  AGENT -.->|"uses"| TOOLS
  AGENT -->|"calls"| PROXY
  PROXY -->|"injects key"| NET
  PROXY -->|"injects key"| NET3
  NET -->|"BYOK"| NET1 & NET2

  classDef data    fill:aliceblue,stroke:steelblue,stroke-width:2px,color:#10314F
  classDef host    fill:antiquewhite,stroke:darkgoldenrod,stroke-width:2px,color:#4A2E05
  classDef helper  fill:#E3F2F1,stroke:#0E7C86,stroke-width:2px,color:#0B3D40
  classDef agent   fill:mistyrose,stroke:firebrick,stroke-width:2px,color:#5A1710
  classDef ext     fill:whitesmoke,stroke:lightslategray,stroke-width:1.5px,color:#3A4250
  class MD,SPEC,STATE,OKF data
  class KIT,DRV host
  class TOOLS,LINT,PROXY helper
  class AGENT agent
  class NET,NET3,NET1,NET2 ext
  style VM fill:whitesmoke,stroke:lightslategray,stroke-width:1.5px
  style IN fill:none,stroke:none
  style OUT fill:none,stroke:none

Host tooling (amber) builds the microVM from the kit and drives it with one sbx exec per source document. Inside, the coding agent (red) runs the /compile-okf skill: it reads the source documents and SPEC.md (blue) and writes the wiki into okf/ (blue), the only content it may change. Skills and the linter (teal) support it — four of them survey the source markdown and wiki, curate-okf maintains its nodes and indexes, and the linter must pass before a run ends. Session state (blue) is mounted from the host, so transcripts outlive the sandbox. Model calls leave the VM only through the sbx credential proxy (teal), which injects the API key; OpenRouter routes them to DeepInfra or other providers (gray).

Contents

• Quickstart
• Install sbx
• Set up the OpenRouter key
• Further documentation
• License

Quickstart

md2okf needs sbx, which runs the sandbox, and uv, which installs the tool. Pi, the default agent, also needs an OpenRouter API key.

uv tool install md2okf       # Install from PyPI
md2okf --version

md2okf -v my-document.md     # The wiki lands in ./okf
md2okf -v md/ -o okf/

uv installs the tool from PyPI, so there is no need to clone the repository. Point md2okf at a single Markdown file or a folder of Markdown files, and it compiles them into an OKF wiki. The first run builds the sandbox; later runs reuse it. -v turns on verbose mode, which also shows the agent's tool calls and messages. Leave it out for a quieter run that prints only progress.

uvx md2okf -v my-document.md
uvx md2okf -v md/ -o okf/

Alternatively, skip the installation and run the tool directly with uvx.

MD2OKF_AGENT=claude md2okf -v md/ -o okf/     # Claude Code
MD2OKF_AGENT=codex md2okf -v md/ -o okf/      # Codex

Pi is the default agent. To compile with Claude Code or Codex instead, set MD2OKF_AGENT; each agent needs its own credential first. See Choosing an agent for the sign-in steps.

md2okf --shell               # Interactive shell at the wiki root
md2okf --agent               # Interactive agent session

The first flag opens a shell inside the sandbox, at the wiki root; the second opens an interactive session with the agent. Both are for inspecting the sandbox. Changes made in either session stay in the sandbox's working copy: they are not copied to okf/, and the next compile replaces them.

Install sbx

Install the sbx command-line tool, version 0.45.0 or newer, and sign in. md2okf refuses an older sbx.

macOS:

brew trust docker/tap
brew install docker/tap/sbx
sbx login

Linux:

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm "$USER" && newgrp kvm
sbx login

Set up the OpenRouter key

sbx keeps the key out of the virtual machine. It holds the real key on the host and swaps it into requests at its proxy, so inside the sandbox $OPENROUTER_API_KEY reads proxy-managed. Store the key with sbx twice:

export OPENROUTER_API_KEY=sk-or-...
echo "$OPENROUTER_API_KEY" | sbx secret set openrouter

# And again as a custom secret, to work around a known sbx issue:
# https://github.com/docker/sbx-releases/issues/25
sbx secret set-custom --sandbox md2okf-pi \
  --host openrouter.ai \
  --env OPENROUTER_API_KEY \
  --value "$OPENROUTER_API_KEY"

md2okf-pi is the sandbox Pi runs in; each agent gets its own, called md2okf-<agent>. The export only passes the key to the two sbx commands: md2okf reads it from sbx secret, never from your shell environment.

Further documentation

License

Released under the MIT License.