mikevalstar/okq

A fast, local command-line tool for searching and navigating Open Knowledge Format (OKF) bundles: directories of Markdown files with YAML frontmatter, cross-linked into a knowledge graph.
> Beta. Every command is implemented and tested. The --json shapes and exit codes are stable enough to script against. See the design overview for how it's shaped and the CHANGELOG for releases.
okq 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.
What's an OKF bundle?
OKF 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.
Install
Or with mise, either from the aqua registry
(prebuilt, checksum-verified — needs mise 2026.8.6 or newer), straight from the
GitHub release, or compiled from crates.io:
aqua itself works too:
Prebuilt binaries for macOS, Linux, and Windows are also attached to each
GitHub release.
Usage
Point okq at a bundle with --bundle (default: the current directory).
You don't need the full path. A unique suffix is enough: okq get 0002-library-stack.
Scripting and agents
Every 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.
okq schema prints the JSON Schema for that command's output, generated from the code, so you can validate against it.
Agent skills
okq ships Agent Skills 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.
| Skill | What it does |
|-------|--------------|
| okq-explore | Search and navigate a bundle to assemble context before work. |
| okq-write-okf | Author OKF docs from okq's templates, with cross-links and verification. |
| okq-maintain | Find and fix bundle rot; audit a doc against the code. |
| okq-reference | The okq CLI contract — loaded automatically as background knowledge. |
Install them with okq itself:
This writes the skills to a canonical .agents/skills/ and symlinks them into .claude/skills/ (the same layout 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?
Then 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.
**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.
**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.