Quick Start

In 3 minutes you'll generate a knowledge bundle from any codebase and look up any function, class, or dependency — no LLM, no API key, no setup.

---

1. Generate a bundle

Run okf generate from your project root — it auto-detects the source directory:

cd my_project
okf generate

Or specify paths explicitly:

okf generate ./my_project ./okf_bundle

Auto-detection walks up the directory tree looking for project markers (pyproject.toml, Cargo.toml, package.json, go.mod, .git/, etc.) across all languages. If nothing is found, it uses the current directory.

This scans all recognized files using tree-sitter AST parsers (17 languages) and writes a structured knowledge bundle to ./okf_bundle/.

What you get: - Every function, class, method, and module as a concept card - Every dependency extracted from manifest files - Cross-reference edges (calls, called-by, imports, depends-on) - Pure markdown — diff cleanly, version alongside code

Example output:

  Class                  12
  Function               48
  Module                 14
  Dependency              8
  Interface               3
  Enum                    2
  ────────────────────────
  TOTAL                  87

---

2. Look up any concept

okf lookup --bundle ./okf_bundle MyFunction

Returns the full concept card — signature, parameters, docstring, return type, callers, callees, and source location — in milliseconds.

Filter by type:

okf lookup --bundle ./okf_bundle --type Function
okf lookup --bundle ./okf_bundle --type Class
okf lookup --bundle ./okf_bundle --type Dependency

Filter by language or ecosystem:

okf lookup --bundle ./okf_bundle --tag lang:python
okf lookup --bundle ./okf_bundle --tag ecosystem:pip

Fuzzy search — camelCase, snake_case, acronyms:

okf lookup --bundle ./okf_bundle repo        # Finds UserRepository, OrderRepo
okf lookup --bundle ./okf_bundle calc        # Finds Calculator
okf lookup --bundle ./okf_bundle ur          # Acronym match: UserRepository

JSON output for programmatic use:

okf lookup --bundle ./okf_bundle --json MyClass

---

3. Browse visually

Static visualization

okf visualize ./okf_bundle
# Opens an interactive HTML graph in your browser

Live dashboard (FastAPI)

# Install the dashboard extra first:
pip install "okf-generator[dashboard]"

okf dashboard ./okf_bundle --open
# Launches at http://127.0.0.1:8700

The dashboard provides: - Search — full-text search with type and language filters - Detail view — signature, params, docstring, source, tags, related links - Interactive graph — visual dependency graph per concept - REST API — all data available at /api/ endpoints

---

4. Diff and track changes

# Generate from two versions
okf generate ./project_v1 /tmp/v1
okf generate ./project_v2 /tmp/v2

# See what changed
okf diff /tmp/v1 /tmp/v2 --compact

# See dependency impact
okf diff /tmp/v1 /tmp/v2 --impact

The --impact flag traces changed dependencies to affected modules and their functions/classes — critical for CI/CD pipelines.

---

5. Use from Python

from okf.generator import scan_codebase, write_bundle
from okf.lookup import load_bundle, search
from pathlib import Path

# Scan a codebase
concepts = scan_codebase(Path("./my_project"))
print(f"Extracted {len(concepts)} concepts")

# Write a bundle
write_bundle(concepts, Path("./okf_bundle"), "my_project", ["initial scan"])

# Load and search
bundle = load_bundle(Path("./okf_bundle"))
results = search(bundle, tokens=["PaymentService"])
print(results[0].title)        # "PaymentService"
print(results[0].type)         # "Class"
print(results[0].signature)    # "class PaymentService"

---

6. Set up for AI agents

One command installs okf-generator into your preferred agent:

okf install claude        # Claude Code skill
okf install cursor        # Cursor rules
okf install copilot       # GitHub Copilot
okf install opencode      # OpenCode /lookup command
okf install all           # All of the above

After installation, when you ask your agent about any concept in your codebase, it will automatically run okf lookup instead of reading entire files — saving 80-95% tokens.

---

7. What's next?

If you want to...	Go here
Explore all commands	CLI Reference
Enrich with LLM descriptions	okf generate --enrich
Convert bundle to training data	okf pairs ./okf_bundle ./train.jsonl
Set up CI/CD pipeline	CI/CD Guide
Add a new language parser	Development Guide
Use with MCP-compatible tools	okf mcp ./okf_bundle