{"id":51506026,"url":"https://github.com/mikevalstar/okq","last_synced_at":"2026-07-08T01:00:16.772Z","repository":{"id":367652481,"uuid":"1281656238","full_name":"mikevalstar/okq","owner":"mikevalstar","description":"Fast, deterministic CLI to search and navigate Open Knowledge Format (OKF) doc bundles — for humans and AI agents. Find by frontmatter, traverse the link graph, surface orphans/deadlinks. (planning)","archived":false,"fork":false,"pushed_at":"2026-07-07T16:59:20.000Z","size":707,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T18:06:48.490Z","etag":null,"topics":["ai-agents","cli","documentation","knowledge-graph","llm","markdown","okf","open-knowledge-format","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikevalstar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T19:29:17.000Z","updated_at":"2026-07-07T16:59:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikevalstar/okq","commit_stats":null,"previous_names":["mikevalstar/okq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mikevalstar/okq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikevalstar%2Fokq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikevalstar%2Fokq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikevalstar%2Fokq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikevalstar%2Fokq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikevalstar","download_url":"https://codeload.github.com/mikevalstar/okq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikevalstar%2Fokq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35247742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","documentation","knowledge-graph","llm","markdown","okf","open-knowledge-format","rust"],"created_at":"2026-07-08T01:00:15.442Z","updated_at":"2026-07-08T01:00:16.753Z","avatar_url":"https://github.com/mikevalstar.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# okq\n\nA fast, local command-line tool for searching and navigating [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) bundles: directories of Markdown files with YAML frontmatter, cross-linked into a knowledge graph.\n\n\u003e Beta. Every command is implemented and tested. The `--json` shapes and exit codes are stable enough to script against. See the [design overview](docs/guides/design-overview.md) for how it's shaped and the [CHANGELOG](CHANGELOG.md) for releases.\n\nokq runs full-text search, frontmatter queries, and graph navigation over a tree of docs. It is deterministic and local: no embeddings, no network, no API key, same answer every time. The same command works whether a person runs it or a program does, because every command has a `--json` mode and documented exit codes.\n\n## What's an OKF bundle?\n\nOKF is a small, vendor-neutral convention: one concept per Markdown file, a handful of well-known YAML frontmatter keys (`type`, `title`, `tags`, …), and links between files. ADRs, design docs, runbooks, and wikis all fit it. okq works on any OKF bundle, and degrades gracefully on any Markdown-with-frontmatter tree.\n\n## Install\n\n```sh\ncargo install okq\n```\n\n**Latest release (0.4.0+):** crates.io is paused at 0.3.0 while okq tracks a\ntemporary [`okf` fork](docs/adrs/0010-okf-unicode-filenames-fork.md) — crates.io\ndoesn't allow git dependencies, so `cargo install okq` will fetch 0.3.0 until the\nfork lands upstream. To get the latest, install from GitHub instead:\n\n```sh\n# build from source\ncargo install --git https://github.com/mikevalstar/okq\n\n# or grab a prebuilt binary (needs cargo-binstall)\ncargo binstall --git https://github.com/mikevalstar/okq okq\n```\n\nPrebuilt binaries for macOS, Linux, and Windows are also attached to each\n[GitHub release](https://github.com/mikevalstar/okq/releases/latest).\n\nOr with [mise](https://mise.jdx.dev):\n\n```sh\nmise use -g cargo:okq\n```\n\n## Usage\n\nPoint okq at a bundle with `--bundle` (default: the current directory).\n\n```sh\n# full-text search, ranked by relevance\nokq search \"retrieval latency\"\n\n# filter by frontmatter\nokq find --type adr --tag security\n\n# read one concept, or a single section of it\nokq get adrs/0002-library-stack --section Decision\n\n# follow the links\nokq neighbors adrs/0002-library-stack\nokq backlinks features/search\nokq path features/search features/get\n\n# health and overview\nokq deadlinks\nokq orphans\nokq stats\nokq validate          # OKF conformance report (alias: okq doctor)\n```\n\nYou don't need the full path. A unique suffix is enough: `okq get 0002-library-stack`.\n\n## Scripting and agents\n\nEvery command takes `--json` and writes one JSON document to stdout; messages and progress go to stderr. Exit codes are documented (below), so a script can branch on `$?` without parsing output. That makes okq a clean tool call for an LLM assembling context: it returns the relevant locations instead of dumping whole files.\n\n```sh\nokq search auth --json | jq -r '.results[].path'\nokq find --tag security --json | jq '.count'\nokq deadlinks --check        # exit 3 if any dead links, for CI\n```\n\n`okq schema \u003ccommand\u003e` prints the JSON Schema for that command's output, generated from the code, so you can validate against it.\n\n## Agent skills\n\nokq ships [Agent Skills](https://agentskills.io) that teach an AI agent to use okq well — so adopting okq also onboards the agents that work in your bundles. They follow the open `SKILL.md` standard and work in Claude Code and other compatible agents.\n\n| Skill | What it does |\n|-------|--------------|\n| `okq-explore` | Search and navigate a bundle to assemble context before work. |\n| `okq-write-okf` | Author OKF docs from okq's templates, with cross-links and verification. |\n| `okq-maintain` | Find and fix bundle rot; audit a doc against the code. |\n| `okq-reference` | The okq CLI contract — loaded automatically as background knowledge. |\n\nInstall them with okq itself:\n\n```sh\nokq skills install            # into this project (.agents + .claude)\nokq skills install --global   # into ~/.agents + ~/.claude, for every project\n```\n\nThis writes the skills to a canonical `.agents/skills/` and symlinks them into `.claude/skills/` (the same layout [skills.sh](https://www.skills.sh) uses). The skills are embedded in the binary, so this works offline; re-run any time to update. Prefer the registry, or want the latest between okq releases?\n\n```sh\nokq skills install --via-skills-sh   # delegates to: npx skills add mikevalstar/okq\nokq skills install --from-repo       # fetch the latest from GitHub (the one networked command)\n```\n\nThen invoke one with `/okq-explore`, `/okq-write-okf`, or `/okq-maintain`; `okq-reference` loads on its own when okq or OKF comes up. Run `okq skills list` to see what's bundled.\n\n**These are complete, working skills — but treat them as a starting point.** You'll get the most out of them by tailoring each `SKILL.md` to your own documentation setup: your bundle layout, your frontmatter keys and status lifecycle, the conventions your team already follows. The defaults are sensible; your edits make them sharp.\n\n**A note on scale.** Skills like these earn their keep on **large bundles — roughly 100+ documents** — where an agent genuinely needs ranked search and graph navigation to find the right context without reading everything. On a small bundle, an agent is just as effective reading and grepping the files directly, and the skills add little. Reach for them when the docs have outgrown what fits comfortably in a single look.\n\n## Commands\n\n| Command | What it does |\n|---------|--------------|\n| `okq search \u003cquery\u003e` | Ranked full-text search over section text (BM25). |\n| `okq find` | Filter concepts by `--tag`, `--type`, `--where field=value`, `--match` (`--regex`). |\n| `okq get \u003cconcept\u003e` | Print a concept's frontmatter and/or body, or one `--section`. |\n| `okq neighbors \u003cconcept\u003e` | Adjacent concepts via the link graph (`--depth`, `--direction`, `--edge`). |\n| `okq backlinks \u003cconcept\u003e` | Concepts that link to this one. |\n| `okq path \u003ca\u003e \u003cb\u003e` | Shortest link path between two concepts (`--undirected`). |\n| `okq orphans` | Concepts with no inbound links (`--check` for CI). |\n| `okq deadlinks` | Broken links pointing at missing concepts (`--check` for CI; `--phantoms` also lists bare `[[wikilinks]]` to not-yet-created notes). |\n| `okq stats` | Counts by type and tag, link density, edge types, hubs. |\n| `okq validate` | Check OKF conformance; report unparseable/untyped/malformed docs (alias `doctor`, `--check` for CI). |\n| `okq schema [\u003ccmd\u003e]` | JSON Schema for a command's `--json` output. |\n| `okq init` | Scaffold a new bundle: `adrs/` + `features/`, a seed ADR, a README. |\n| `okq new \u003ctype\u003e [title]` | Add one concept from a template (`adr` numbers itself, `feature` slugifies). |\n| `okq index` | Regenerate the `index.md` directory listings (`--check` for CI). |\n| `okq skills install` | Install/update the okq-* agent skills (`--global`, `--from-repo`, `--via-skills-sh`). |\n\nRun `okq \u003ccommand\u003e --help` for flags and examples.\n\n## Starting a bundle\n\n```sh\nokq init                       # scaffold an OKF bundle in the current directory\nokq new adr \"Adopt Tantivy\"    # add a numbered ADR from a template\nokq index                      # refresh the index.md directory listings\n```\n\n`init` is non-destructive: it creates only the files that are missing, and adds its section to an existing README between markers rather than overwriting it. `index` is the maintenance counterpart — re-run it after adding docs to keep each directory's `index.md` listing current; it rewrites only a fenced block, leaving your prose intact.\n\n## Ignoring files\n\nNot every Markdown file in the tree is a concept. Drop a `.okqignore` file in the bundle (full `.gitignore` syntax — comments, `!` negation, anchoring, `**`, and per-directory nesting) and matching files drop out of every command:\n\n```gitignore\n# fixtures and scratch notes aren't real concepts\ntests/\ndrafts/\n!drafts/keep.md\n```\n\nIgnored files are treated as if they weren't in the bundle: they don't show up in `search`, `find`, `stats`, or `orphans`; `get` on one reports \"not found\"; and a link pointing at one becomes a dead link. Pass `--no-ignore` on any command to query the full tree.\n\n## How it works\n\n- Search uses a BM25 index (Tantivy), cached per-bundle under your XDG cache directory and rebuilt when files change. okq never writes into the bundle itself.\n- The graph is built from inline Markdown links, from frontmatter relations (`related`, `supersedes`, `depends-on`, …), and from Obsidian-style `[[wikilinks]]` / `![[embeds]]` in the body (edge type `wikilink`; bare names resolve by filename, case-insensitively). Filter to any of them with `--edge`.\n- Results are locations, not document dumps: ranked `path:line` plus a short snippet. You expand what you want with `get`.\n- Frontmatter is optional: a Markdown file with no frontmatter is still a concept, and its `title` falls back to the filename (so plain note folders are searchable and navigable too).\n- **Obsidian-friendly.** Frontmatter `aliases:` resolve a note by any of its alternate names (`okq get Hooman`, `[[Hooman]]`) — below filenames, so a real file always wins. Inline `#tags` in the body count as tags alongside frontmatter `tags:`, so `find --tag` and `stats` see a vault's real tag set. And `deadlinks` separates a genuinely **broken** link from a **phantom** — a bare `[[Note]]` to a note you simply haven't written yet — listing only broken ones by default so it isn't thousands of false alarms on a vault.\n- Parsing and the data model come from the [`okf`](https://crates.io/crates/okf) crate; okq adds the query and navigation layer on top.\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success, including an empty result (a query that found nothing still ran). |\n| 1 | Internal error: bad bundle, I/O, or index failure. |\n| 2 | Usage error: bad flags, a malformed `--where`, or an invalid query. |\n| 3 | A `--check` run found issues (`orphans`/`deadlinks`). |\n| 4 | Concept not found. |\n| 5 | Section not found or ambiguous. |\n\n## License\n\n[Apache-2.0](LICENSE), matching OKF and the `okf` crate.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikevalstar%2Fokq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikevalstar%2Fokq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikevalstar%2Fokq/lists"}