opencode-okf

An OpenCode plugin for creating, maintaining, and validating Open Knowledge Format (OKF) v0.1 bundles.

The authoring commands make OpenCode inspect repository evidence before it writes knowledge. The bundled validator checks the actual format, so conformance does not depend on the model remembering every rule.

Features

• /okf-init inspects a repository and creates an evidence-backed OKF bundle.
• /okf-update [session|diff] updates concepts and indexes from full repo (no arg), git diff, or the current session.
• /okf-validate reports conformance errors and quality warnings, with opt-in fixes.
• /okf-compact [all] prunes logs, or the whole bundle (concepts, indexes, logs) with all.
• okf_validate, okf_capture, and okf_diff give agents deterministic OKF and git-diff tools.
• A command hook supplies the exact UTC timestamp to OKF workflows.
• A debounced file-event hook warns when edits make the bundle nonconformant.
• Existing commands and producer-defined OKF frontmatter are preserved.

Install

With OCX (recommended)

OCX manages OpenCode profiles and plugins.

Install OCX:

curl -fsSL https://ocx.kdco.dev/install.sh | sh

Initialize global OCX config (once):

ocx init --global

Add the plugin to your global config:

ocx add npm:opencode-okf -g

Or to a named profile:

ocx add npm:opencode-okf -p default

Launch OpenCode through OCX:

ocx oc
# or with a profile:
ocx oc -p default

Quit and restart OpenCode after changing plugin configuration.

Manual

Add the published plugin to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-okf"]
}

Quit and restart OpenCode after changing plugin configuration. OpenCode installs npm plugins with Bun at startup.

For local development, build this package and reference its compiled entry point with an absolute file URL:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/opencode-okf/dist/index.js"]
}

Usage

Create a bundle using repository-wide evidence:

/okf-init focus on revenue, subscriptions, and customer lifecycle knowledge

Update an existing bundle (hard source mode on the first arg):

/okf-update
/okf-update review schema migrations and dashboard changes
/okf-update diff
/okf-update diff origin/main
/okf-update session
/okf-update session focus on architecture decisions

| Args | Source | | --- | --- | | (none) or free-form focus | Full repository evidence | | diff [ref] [focus…] | Git changes via okf_diff (default HEAD) | | session [focus…] | This conversation + work — concepts/indexes first, not log-only |

Validate without editing:

/okf-validate

Compact accumulated knowledge, keeping only what remains useful:

/okf-compact
/okf-compact aggressive
/okf-compact all
/okf-compact all aggressive
/okf-compact conservative keep the migration decisions, drop everything before June

| Args | Scope | | --- | --- | | (none) or aggressiveness/focus only | logs only | | all [aggressiveness] [focus…] | all — concepts, indexes, and logs |

Optional aggressiveness: conservative | balanced (default) | aggressive. Ask OpenCode to repair format problems after validation:

/okf-validate fix conformance errors

The default output directory is okf/. The commands choose a hierarchy from the repository evidence rather than imposing a fixed SaaS template.

Configuration

Pass plugin options with OpenCode's tuple syntax:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "opencode-okf",
      {
        "bundleDirectory": "knowledge/okf",
        "validateOnEdit": false
      }
    ]
  ]
}

| Option | Default | Description | | --- | --- | --- | | bundleDirectory | okf | Bundle directory relative to the worktree. Paths outside the worktree are rejected. | | validateOnEdit | true | Debounce validation after bundle file events and show a warning only for conformance errors. |

Validation

The validator follows OKF v0.1 conformance rules:

• Every non-reserved Markdown file must have parseable YAML frontmatter with a non-empty string type.
• index.md files must provide progressive-disclosure headings and linked entries. Only the root index may have frontmatter, where it declares okf_version.
• log.md files must contain newest-first ## YYYY-MM-DD groups with list entries.
• Documents must decode as UTF-8.

Missing recommended metadata, malformed optional fields, empty bodies, and broken internal links are warnings. They do not fail validation because OKF consumers must tolerate those conditions.

Development

bun install
bun run check
bun test
bun run build

References

• OpenCode plugin documentation
• Open Knowledge Format v0.1 specification
• Introducing the Open Knowledge Format