{
  "markdown": "# okf-kit\n\n**Build and serve [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) (OKF v0.1) knowledge bundles — via a CLI and an MCP server.**\n\nAn OKF bundle is a directory of Markdown files; each file is one *concept* (YAML\nfrontmatter + body), the file path is its id, and relative Markdown links form a\nknowledge graph. `okf-kit` is an agent-native toolkit for that format: a pure\nPython core exposed two ways — the **`okf` CLI** and the **`okf-mcp`** MCP server\n(the universal layer for Claude Code, Antigravity, and any MCP client) — plus\n**`okf-search`**, **`okf-author`**, and **`okf-code`** skills.\n\n> OKF is \"what knowledge looks like once loaded\" — designed for LLMs, not\n> SPARQL engines. `okf-kit` makes a folder of Markdown queryable, citeable, and\n> agent-addressable.\n\n## Install\n\nRequires Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/) (recommended).\n\n```bash\nuv sync --extra dev\n```\n\nThis creates a `.venv/` and installs two console entry points — **`okf`** (CLI)\nand **`okf-mcp`** (server) — into `.venv/bin/` (not your global `PATH`). Run them\nwith `uv run`, or activate the venv first:\n\n```bash\nuv run okf --help            # prefix with `uv run` …\nsource .venv/bin/activate    # …or activate once, then use `okf` / `okf-mcp` bare\n```\n\n> **No uv?** `python -m venv .venv && source .venv/bin/activate && pip install -e \".[dev]\"`\n> installs the same `okf` and `okf-mcp` commands.\n\nThe examples below use `uv run`; drop the prefix if you've activated the venv.\n\n### Optional code indexing\n\nCodebase indexing is opt-in because it pulls parser dependencies:\n\n```bash\nuv sync --extra dev --extra treesitter\n# or, from an installed package:\npip install \"okf-kit[treesitter]\"\n```\n\nCode indexing currently supports Python, Java, Scala, Rust, Go, Kotlin, Perl,\nC#, PHP, TypeScript, JavaScript, and HTML through `tree-sitter-language-pack`.\nIt generates normal OKF `CodeModule` concepts for documentation, code finding,\ncode-logic search, and syntax-grounded impact-analysis groundwork; it does not\nclaim complete semantic impact analysis.\n\n### Install `okf` as a uv tool\n\nTo install or reinstall the CLI on this machine from this checkout:\n\n```bash\nuv tool install --force --editable .\n```\n\nOr install directly from GitHub:\n\n```bash\nuv tool install --force git+https://github.com/phanijapps/okf-kit.git\n```\n\nBoth commands put `okf` and `okf-mcp` on uv's tool path. Verify with:\n\n```bash\nokf --help\nokf agent install codex --scope project --dry-run\n```\n\n## Install agent skills\n\nInstall the OKF Agent Skills into a project-local agent configuration:\n\n```bash\nuv run okf agent install claude-code --scope project\nuv run okf agent install codex --scope project\n```\n\nProject scope writes:\n\n- Claude Code: `.claude/skills/{okf-search,okf-author,okf-code}/SKILL.md`\n- Codex: `.codex/skills/{okf-search,okf-author,okf-code}/SKILL.md`\n\nUse `--dry-run` to preview writes. Re-running the command refreshes files\npreviously installed by OKF; unmanaged local files are still refused. This\ninstalls skills only: `okf-search` for read-only progressive context,\n`okf-author` for create/update authoring loops, and `okf-code` for codebase\nindexing/search/impact workflows. It does not install subagents, hooks, MCP\nconfig, or plugins.\n\nRun project-scope installs from the repository where you want the skills\navailable. The installer refuses to write inside an OKF bundle root or\nsubdirectory so agent skills do not become knowledge concepts by accident. Use\n`--scope user` to install into the user-level agent skill directory instead.\n\n## Quick start (build a knowledge base)\n\n```bash\nuv run okf init mykb --name \"My Knowledge Base\"\nuv run okf new mykb Table tables/users --title \"Users\" --desc \"User accounts.\"\nuv run okf new mykb Metric metrics/churn --title \"Churn\" --desc \"Monthly churn, see [users](../tables/users.md).\"\n\nuv run okf validate mykb                       # SPEC §9 conformance (exit 1 if not conformant)\nuv run okf search mykb churn                   # full-text search\nuv run okf read mykb metrics/churn --depth 1   # progressive context: concept + neighborhood\nuv run okf index regen mykb                    # regenerate per-directory index.md\n```\n\nBuilt-in concept types: `Table`, `Metric`, `Runbook`, `Playbook`, `API` (or any\ncustom value). The only required frontmatter field is `type`.\n\n## Index a codebase\n\nWith the `treesitter` extra installed, generate a compact code map from a\nrepository or multi-repository workspace into an OKF bundle:\n\n```bash\nuv run okf code index /absolute/path/to/workspace codekb\nuv run okf validate codekb\nuv run okf search codekb UserService --type CodeModule\nuv run okf read codekb code/pkg/service.py --depth 1\n```\n\n`okf code index` writes managed `CodeSummary` concepts under `code-summaries/`\nand managed `CodeModule` concepts under `code/`. The default `--profile compact`\nkeeps file concepts bounded while still synthesizing purpose, role, high-signal\nsymbols, dependency context, reverse dependents, impact hints, and citations.\nIt preserves source extensions in concept ids so polyglot repositories do not\ncollide (`src/app.py` becomes `code/src/app.py`); in multi-repository\nworkspaces, the repo id is included in generated ids and frontmatter. Repeat\n`--language` to limit languages, use `--repo` to narrow workspace repositories,\nuse repeatable `--include` / `--exclude` globs for scope, and add\n`--include-tests` only when test concepts matter. Re-running refreshes generated\nsections while preserving hand-authored narrative outside the managed block;\n`--update` is accepted for compatibility. Use the packaged `okf-code` skill for\nthe agent workflow: search summaries first, read one target at depth 0, then use\n`okf read --depth 1` for dependency and reverse-dependent impact context.\n\n## Use it from an agent (MCP)\n\nStart the server over stdio (it registers the bundle by its directory name):\n\n```bash\nuv run okf-mcp mykb\n```\n\nIf you installed with `uv tool install`, use the tool command directly:\n\n```bash\nokf-mcp /absolute/path/to/mykb\n```\n\nFor Codex, add OKF as a project-scoped MCP server from the repository where you\nwant Codex to use the bundle:\n\n```bash\ncodex mcp add okf -- okf-mcp /absolute/path/to/mykb\n```\n\nThis writes the MCP entry into Codex config. You can inspect active servers in\nCodex with `/mcp` or with:\n\n```bash\ncodex mcp --help\n```\n\nFor Antigravity, open **Manage MCP Servers** → **View raw config** and add OKF\nto the `mcpServers` object in `mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"okf\": {\n      \"command\": \"okf-mcp\",\n      \"args\": [\"/absolute/path/to/mykb\"]\n    }\n  }\n}\n```\n\nIf you have other MCP servers, merge the `okf` entry into the existing\n`mcpServers` object rather than replacing the file. See Antigravity's MCP docs:\n<https://antigravity.google/docs/mcp>.\n\nFor Claude Code, add an MCP server config (`.mcp.json`). Point `uv` at this repo\nand at your bundle (absolute paths):\n\n```json\n{\n  \"mcpServers\": {\n    \"okf\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--project\", \"/absolute/path/to/okf\", \"okf-mcp\", \"/absolute/path/to/mykb\"]\n    }\n  }\n}\n```\n\n(If you installed `okf-mcp` onto your `PATH` via `uv tool install` or pip, the config simplifies to\n`\"command\": \"okf-mcp\", \"args\": [\"/absolute/path/to/mykb\"]`.)\n\n## Browse in a browser (`okf serve`)\n\nOn demand, launch a read-only web UI over a bundle — tree navigation, search, the\ngraph, and a Markdown reader with backlinks. It binds `127.0.0.1`, picks a free\nport, prints the URL, and runs until you stop it (Ctrl-C). It is **not** started\nby `okf-mcp`; an agent harness runs it when a human wants the visual UI.\n\n```bash\nuv run okf serve mykb\n# -> okf serve: 'mykb' at http://127.0.0.1:54321  (Ctrl-C to stop)\n```\n\nThen open the printed URL. Editing (frontmatter form, Markdown editor, CRUD) is\nthe next milestone; this is read-only.\n\nThe server exposes five tools — **`search`**, **`read_concept`** (with `depth`\nfor progressive context), **`validate`**, plus **`create_concept`** (enforces a\nrichness floor: ≥120 words + a depth section, so MCP-authored concepts are rich\nby construction) and **`init_bundle`** — and an `okf://<bundle>/concepts/<id>.md`\nresource per concept.\n\n## Architecture\n\nOne pure core, two thin presentation layers (no duplicated logic):\n\n```\nokf_kit.core  (model · parse · validate · links · search · context · index · templates)\n      │\n      ├── okf_kit.cli   → `okf` CLI      (argparse: init/new/validate/search/read/index/code)\n      └── okf_kit.mcp   → `okf-mcp`      (FastMCP/stdio: search/read_concept/validate + okf://)\n```\n\nThe core is pure: deterministic, no network, no randomness. **Security:** every\ncaller-supplied concept id and link target is confined to the bundle root\n(segment-regex validation + resolved-path containment, including symlink\nescapes), on both the read and write paths. Code indexing lives outside\n`okf_kit.core` and imports Tree-sitter only when `okf code index` runs.\n\n## Status\n\n**v0.1 — build + use a single OKF bundle.** In scope: parse/validate (SPEC §9),\nsearch, progressive-context read, `init`/`new`/`index regen`, the MCP server,\nthe `okf-search`, `okf-author`, and `okf-code` skills, **`okf serve`** — a\nread-only browser UI (tree, search, graph, reader) launched on demand by an\nagent harness, and Tree-sitter-backed code indexing through\n`okf-kit[treesitter]` for Python, Java, Scala, Rust, Go, Kotlin, Perl, C#, PHP,\nTypeScript, JavaScript, and HTML.\n**Next:** web-UI editing\n(frontmatter form, Markdown editor, link autocomplete, CRUD) and bundle\nimport/export. **Later milestones (see the [`project/backlog`](wiki/project/backlog.md) wiki concept):** producer\n(extract/enrich), governance (RBAC/PII/signing), and multi-bundle federation —\nincluding the future multi-level `<domain>/<subdomain>` bundles the design\nanticipates. **Git integration** is the only intentionally-deferred Phase-2 item.\n\n## Documentation\n\n- [`wiki/format/okf-format.md`](wiki/format/okf-format.md) — OKF bundle and concept format.\n- [`wiki/format/conformance.md`](wiki/format/conformance.md) — validation and conformance behavior.\n- [`wiki/architecture/overview.md`](wiki/architecture/overview.md) — core architecture and progressive context.\n- [`AGENTS.md`](AGENTS.md) — build rules and structure.\n- [`wiki/`](wiki/) — the OKF knowledge bundle: tool reference, progressive context, URI scheme, authoring, backlog.\n- [`wiki/project/backlog.md`](wiki/project/backlog.md) — deferred findings and future work.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Gates (`ruff`, `mypy --strict`,\n`pytest`) must pass; core logic is written test-first.\n\n## License\n\nokf-kit is licensed under the MIT License — see [`LICENSE`](LICENSE).\n\nThe Open Knowledge Format specification is separate Apache-2.0 licensed\nmaterial published by Google Cloud. okf-kit is an independent implementation of\nOKF v0.1; it is not an official Google product and is not endorsed by Google.\nSee [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for OKF attribution and\nbundled browser asset notices.\n",
  "bytes": 11089,
  "sha": "63a5d4ed9b6e40219064e833fd48945d8072a2c85f0d1511e380d22d2eebaf47",
  "repo_slug": "phanijapps/okf-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_phanijapps_okf_kit_wiki_index_md_af9076e9/readme"
}