OKFy — The Fastest Way to Create OKF Bundles from Documentation

What Is OKFy?

OKFy (pronounced "OK-fy") is an open-source Python CLI tool by 0dust that automates the creation of Open Knowledge Format (OKF) bundles from your existing documentation. Instead of manually structuring directories, writing YAML frontmatter, and creating concept files, you point OKFy at your docs and it generates a fully conformant OKF bundle in seconds.

OKFy is the most-starred dedicated OKF conversion tool on BundleDex with 59 GitHub stars, licensed under MIT, and actively maintained (last updated July 2026).

Key Features

• Automated Conversion — Point OKFy at a directory of markdown files and get a validated OKF bundle with proper structure, frontmatter, and cross-links.
• MCP Server — Run okfy serve to expose OKF operations as a Model Context Protocol server, letting AI agents manage bundles directly.
• Single-File Support — Convert a single README or markdown file into a complete OKF bundle.
• Dry-Run Mode — Preview what OKFy will create without writing any files (--dry-run).
• OKF v0.1 Conformant — Generates bundles that follow the OKF specification and work with any OKF-compatible AI agent.
• Agent-Native — Designed for AI agent workflows. Claude Code, Cursor, and OpenCode can invoke OKFy to manage knowledge bundles.

Installation

OKFy is a Python package available via pip. It requires Python 3.8 or later.

Method 1: Install via pip (Recommended)

# Install globally
pip install okfy

# Verify installation
okfy --version

Method 2: Install via pipx (Isolated)

pipx installs OKFy in its own isolated environment, avoiding dependency conflicts:

# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install OKFy
pipx install okfy

# Verify
okfy --version

Method 3: Install from Source

# Clone the repository
git clone https://github.com/0dust/OKFy.git
cd OKFy

# Install in development mode
pip install -e .

# Or build and install
python -m build
pip install dist/*.whl

System Requirements

• Python 3.8 or later
• pip (Python package manager)
• Git (optional, for source installation)
• No external dependencies — OKFy bundles are plain markdown files

Creating Your First OKF Bundle with OKFy

Let's walk through converting a documentation directory into an OKF bundle using OKFy. This is the fastest path from "I have docs" to "my AI agent has knowledge."

Step 1: Prepare Your Documentation

OKFy works best with markdown files. If your docs are in a different format (reStructuredText, plain text, HTML), convert them to markdown first. For this example, assume you have a directory like this:

my-docs/
├── README.md
├── getting-started.md
├── api-reference.md
├── configuration.md
└── troubleshooting.md

Step 2: Run the Conversion

Point OKFy at your docs directory and specify an output directory for the bundle:

# Basic conversion
okfy convert ./my-docs --output ./my-okf-bundle

# Preview what will be created (dry run)
okfy convert ./my-docs --output ./my-okf-bundle --dry-run

Step 3: What OKFy Creates

After conversion, your output directory will have a complete OKF bundle structure:

my-okf-bundle/
├── index.md              # Entrypoint with auto-generated frontmatter
├── concepts/
│   ├── getting-started.md
│   ├── api-reference.md
│   ├── configuration.md
│   └── troubleshooting.md
└── .okf/
    └── okf.yaml          # Bundle manifest (OKF version, metadata)

Step 4: Convert a Single File

You can also convert a single README or markdown file into a minimal OKF bundle:

# Convert a single README
okfy convert README.md --output ./single-bundle

# This creates:
# single-bundle/
# ├── index.md
# ├── concepts/
# │   └── readme.md
# └── .okf/
#     └── okf.yaml

Step 5: Validate Your Bundle

After conversion, validate the bundle to ensure it's OKF-conformant. You can use any OKF validator:

# Option A: Use OKFy's built-in validation (if available)
okfy validate ./my-okf-bundle

# Option B: Use openknowledge CLI
okf validate ./my-okf-bundle

# Option C: Manual check
# ✓ index.md exists with YAML frontmatter
# ✓ concepts/ directory has at least one file
# ✓ .okf/okf.yaml manifest present
# ✓ All cross-links resolve

Step 6: Use with Your AI Agent

Point your AI agent at the bundle directory:

# Claude Code
claude /path/to/my-okf-bundle

# Cursor
cursor /path/to/my-okf-bundle

# OpenCode
opencode /path/to/my-okf-bundle

Using OKFy as an MCP Server

One of OKFy's most powerful features is its MCP server mode. Instead of running CLI commands manually, your AI agent can invoke OKFy operations directly through the Model Context Protocol.

Starting the MCP Server

# Start OKFy as an MCP server
okfy serve

# The server starts on the default MCP port
# AI agents can now discover and invoke OKFy operations

Configuring Your AI Agent to Use OKFy MCP

Add OKFy to your agent's MCP configuration. Example for Claude Code:

# In your Claude Code MCP config:
{
  "mcpServers": {
    "okfy": {
      "command": "okfy",
      "args": ["serve"]
    }
  }
}

What AI Agents Can Do via OKFy MCP

When connected via MCP, AI agents can:

• Convert docs to bundles — "Convert my docs/ directory to an OKF bundle"
• Validate bundles — "Check if this bundle is OKF conformant"
• List concepts — "Show me all concepts in this OKF bundle"
• Create concept files — "Add a new concept about prompt engineering"
• Update frontmatter — "Update the description and tags for this bundle"

OKFy vs okf-builder — Which Tool Should You Use?

The OKF ecosystem has two main tools for creating bundles: OKFy (conversion-focused) and okf-builder (authoring-focused). Here's how to choose:

When to Use OKFy

• You already have documentation in markdown format
• You want to convert in bulk — multiple files at once
• You need MCP server integration for agent-native workflows
• You want a one-command solution with minimal interaction

When to Use okf-builder

• You're creating a brand-new bundle from scratch
• You want guided, step-by-step authoring
• You prefer interactive prompts over automated scanning
• You're already in the Node.js ecosystem

Real-World Use Cases

Here are concrete examples of how teams use OKFy to create AI-ready knowledge bundles:

1. Open-Source Project Documentation

Scenario: You maintain an open-source library with a docs/ directory full of markdown files. Users want their AI coding agents to understand your library.

# Convert your docs to an OKF bundle
okfy convert ./docs --output ./okf-bundle

# Push to GitHub
cd okf-bundle
git init && git add -A && git commit -m "OKF bundle for my-library"
git push

# Submit to BundleDex
# → Users can now point Claude Code at your bundle

2. Internal Company Knowledge Base

Scenario: Your team has a wiki with onboarding guides, architecture docs, and runbooks. You want your AI coding agents to have access to this knowledge.

# Export wiki to markdown, then convert
okfy convert ./wiki-export --output ./company-knowledge

# Run as MCP server for your team
okfy serve

# Now every developer's AI agent can query company knowledge
# through the MCP protocol

3. CI/CD Pipeline Integration

Scenario: You want your docs to automatically stay in sync as an OKF bundle on every push.

# .github/workflows/okf-sync.yml
name: Sync OKF Bundle
on:
  push:
    paths:
      - 'docs/**'
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install OKFy
        run: pip install okfy
      - name: Convert docs to OKF
        run: okfy convert ./docs --output ./okf-bundle
      - name: Validate
        run: okfy validate ./okf-bundle
      - name: Commit OKF bundle
        run: |
          git config user.name "okf-bot"
          git config user.email "bot@example.com"
          git add okf-bundle/
          git diff --staged --quiet || git commit -m "chore: sync OKF bundle"
          git push

4. Agent-Native Documentation Management

Scenario: You run OKFy as an MCP server. Your AI agent (Claude Code, Cursor) manages your documentation autonomously — creating, updating, and validating bundles without manual intervention.

# You: "OKFy, serve"
okfy serve

# Claude Code (via MCP): "I'll convert the docs/ to OKF and validate"
# Claude Code: "found 12 markdown files, generated bundle with 12 concepts"
# Claude Code: "all validations passed. bundle ready for BundleDex submission"

Related Bundles

OKFy is part of a growing ecosystem of OKF tools. Here are related bundles you might find useful:

Browse all 583 bundles on the BundleDex directory to discover more OKF tools and knowledge bundles.

Frequently Asked Questions About OKFy