Okf Generator

OKF Generator & Lookup Skill

Generates structured OKF v0.2 knowledge bundles from codebases (Python, JS/TS, Go, Java, Rust, Ruby via tree-sitter AST), and provides fast concept lookup for AI agents like OpenCode.

Pipeline Overview

codebase
   |
   v
okf generate  -->  okf_bundle/          (domain/resource-path layout)
                       |
                okf lookup               (zero-LLM concept search)
                       |
                okf pairs          -->  okf_pairs.jsonl  (training data)

CLI Reference

All features via single okf CLI (installed from PyPI).

| Command | Purpose | |---------|---------| | okf generate | Scan codebase and write OKF bundle | | okf lookup | Search bundle and return exact concept | | okf pairs | Convert bundle to JSONL training pairs | | okf summarize | Regenerate SUMMARY.md from existing bundle |

Dependencies

pip install okf-generator
# With LLM enrichment:
pip install "okf-generator[llm]"

---

Task: Generate OKF Bundle

When: user says "index my codebase", "generate OKF bundle", "extract knowledge from code"

Static extraction (no LLM — always run this first)

okf generate  

With LLM enrichment (fills missing docstrings and descriptions)

OKF_ENRICH=1 \
OKF_BASE_URL="http://localhost:8080/v1" \
OKF_API_KEY="llamabarn" \
OKF_MODEL="ggml-org/gemma-3-4b-it-qat-GGUF:Q4_0" \
OKF_MAX_WORKERS=2 \
okf generate  

Enrichment is resumable — rerun safely if interrupted. Already-enriched concepts are skipped automatically (checks disk on every run).

Key env vars (enrichment only)

| Var | Default | Purpose | |-----|---------|---------| | OKF_ENRICH | 0 | Set 1 to enable LLM enrichment | | OKF_BASE_URL | https://api.anthropic.com/v1 | OpenAI-compat endpoint | | OKF_API_KEY | ` | API key | | OKFMODEL | claude-sonnet-4-6 | Enrichment model | | OKFMAX_WORKERS | 2` | Parallel workers (keep low for local LLMs) |

Output layout (mirrors source tree)

okf_bundle/
├── SUMMARY.md              /
    └── /
        ├── index.md        .md     .md   output.jsonl

# With LLM (QA, doc, summarize pairs)
SYNTH_BASE_URL="http://localhost:8080/v1" \
SYNTH_API_KEY="llamabarn" \
SYNTH_MODEL="ggml-org/gemma-3-4b-it-qat-GGUF:Q4_0" \
MAX_WORKERS=2 \
QA_PER_CONCEPT=3 \
okf pairs  output.jsonl

# Specific pair types only
PAIR_TYPES="codegen,qa" okf pairs  output.jsonl

Pair types

| Type | Static | LLM | Covers | |------|--------|-----|--------| | codegen | yes | yes | Functions, Classes | | qa | no | yes | All (purpose/params/return/edge) | | doc | no | yes | Functions, Classes | | summarize | yes | yes | Modules, Classes | | crosslink | yes | no | All with related concepts |

---

Task: Regenerate SUMMARY.md Only

okf summarize 

Use after enrichment finishes to refresh the summary without re-scanning.

---

OpenCode Integration

See references/opencode-integration.md for full setup.

Quick setup:

# 1. Add to AGENTS.md (auto-loaded by OpenCode)
echo "OKF bundle at ./okf_bundle — use: okf lookup " >> AGENTS.md

# 2. Add lookup command
mkdir -p .opencode/commands
echo "RUN okf lookup --bundle ./okf_bundle \$NAME" \
  > .opencode/commands/lookup.md

---

Supported Languages

| Language | Parser | Extracts | |----------|--------|---------| | Python | stdlib ast | functions, classes, params, return types, docstrings | | JS / TS | tree-sitter | functions, arrow fns, classes, JSDoc | | Go | tree-sitter | funcs, methods, structs, interfaces, GoDoc | | Java | tree-sitter | classes, methods, constructors, Javadoc | | Rust | tree-sitter | fns, structs, enums, traits, impl blocks, doc comments | | Ruby | tree-sitter | defs, classes, modules, hash comments |

---

Troubleshooting

No concepts found: Check that source dir is not inside a SKIPDIRS name (nodemodules, .venv, dist, etc). Leading path components like /tmp are no longer skipped (fixed in v0.1.3).

Enrichment slow: Use OKF_MAX_WORKERS=1. Local models process ~1 request at a time. At 32 tok/sec expect ~3-5s per concept.

Enrichment interrupted: Rerun same command. Enriched files are skipped.

JS/TS concepts missing: Ensure tree-sitter-typescript is installed. TypeScript uses a separate grammar from JavaScript.

Lookup wrong result: Add --type or --file to narrow the search scope.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: UmairBaig8
• Source: UmairBaig8/okf-generator
• License: MIT

Install and usage instructions live in the source repository linked above.