# codex-okf

[OpenAI Codex](https://developers.openai.com/codex) **plugin** for [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

Full parity with [opencode-okf](https://github.com/kaishin/opencode-okf) / [claude-okf](https://github.com/kaishin/claude-okf) / [pi-okf](https://github.com/kaishin/pi-okf):

| Feature | Mechanism |
| --- | --- |
| Init / update / compact workflows | Bundled skill (`skills/okf`) |
| `okf_validate`, `okf_capture`, `okf_diff` | MCP server (`.mcp.json`) |
| Validate-on-edit | `PostToolUse` hooks on apply_patch/Edit/Write |
| Session hint when bundle exists | `SessionStart` hook |
| CLI | `scripts/okf.mjs` |

## Install (local marketplace)

```sh
cd /Users/kaishin/Developer/Spikes/codex-okf
npm install

# Personal marketplace entry
mkdir -p ~/.agents/plugins ~/.codex/plugins
ln -sfn /Users/kaishin/Developer/Spikes/codex-okf ~/.codex/plugins/okf
```

Create or merge `~/.agents/plugins/marketplace.json`:

```json
{
  "name": "local-kaishin",
  "interface": { "displayName": "Local (Kaishin)" },
  "plugins": [
    {
      "name": "okf",
      "source": { "source": "local", "path": "./.codex/plugins/okf" },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}
```

Then in Codex / ChatGPT desktop: **Plugins** → your local marketplace → install **OKF**.

Trust plugin hooks when prompted (`/hooks` in CLI) so validate-on-edit runs.

Remove any old skill-only symlink if present:

```sh
rm -f ~/.agents/skills/okf
```

## Usage

- `$okf` or ask about OKF / knowledge bundles
- MCP tools: `okf_validate`, `okf_capture`, `okf_diff`
- CLI:

```sh
node scripts/okf.mjs validate
node scripts/okf.mjs diff origin/main
node scripts/okf.mjs capture --summary "…" --decision "…"
node scripts/okf.mjs init
```

Workflow hard args (same as siblings):

```text
update                 # full repo
update diff [ref]
update session
compact
compact all [aggressive]
```

## Layout

```text
.codex-plugin/plugin.json
.mcp.json
hooks/{hooks.json,post-edit-validate.mjs,session-start.mjs}
skills/okf/
scripts/{okf.mjs,mcp-server.mjs,lib/*}
```

## License

MIT