OKF Harness

English | 中文

An agent-first, local-first, terminal-native harness for maintaining OKF-compatible LLM Wikis from Claude Code, Codex, and future coding agents.

OKF Harness is an independent open-source project built on two upstream ideas: Andrej Karpathy's LLM Wiki pattern for agent-maintained living wikis, and Google's Open Knowledge Format / OKF specification for portable markdown knowledge bundles.

source files or URLs
        |
        v
raw/sources + .okfh/manifest.jsonl
        |
        v
wiki/*.md with citations
        |
        v
Claude Code or Codex uses okfh evidence/read/graph

OKF Harness does not ask you to learn a new knowledge-base app. You install one CLI package, create one local workspace per knowledge domain, then ask Claude Code or Codex to add sources, maintain the wiki, and answer from it.

Origins

OKF Harness builds on:

• Andrej Karpathy's LLM Wiki: the agent-maintained wiki pattern of index, log, linked pages, ingest, query, and lint.
• Google's Open Knowledge Format announcement and OKF specification: the markdown-plus-frontmatter bundle shape that keeps knowledge portable across tools.

This repository is not affiliated with or endorsed by Andrej Karpathy or Google.

Before You Start

Install the CLI once:

npm install -g @okf-harness/cli
okfh doctor --json

Normal use needs macOS, Windows, or Linux; Node.js 22 or newer; git; and the @okf-harness/cli package. Repository development additionally needs pnpm, but a normal installed okfh doctor --json does not check for it.

You can run that command yourself, or ask your agent to check whether okfh is installed. If an agent needs to install a global npm package, it must ask for your explicit approval first.

The recommended parent folder is only a convention, not a hidden CLI default. On macOS or Linux, use $HOME/Documents/OKF Harness. On Windows PowerShell, use $env:USERPROFILE\Documents\OKF Harness. On Command Prompt, use %USERPROFILE%\Documents\OKF Harness.

Start With Your Agent

Use the prefix for the agent you are already using.

No workspace yet:

Codex:

$okf-harness Set up a workspace for my AI research notes in my Documents folder, then check that this agent can use it.

Claude Code:

/okf-harness Set up a workspace for my AI research notes in my Documents folder, then check that this agent can use it.

Existing workspace:

Codex:

$okf-harness Check this workspace and tell me whether it is ready.

Claude Code:

/okf-harness Check this workspace and tell me whether it is ready.

To try the command without a global install:

npx --package @okf-harness/cli okfh doctor --json

Common Next Steps

Add a source:

Codex:

$okf-harness Add this PDF to my workspace, update the wiki with citations, then check the workspace again.

Claude Code:

/okf-harness Add this PDF to my workspace, update the wiki with citations, then check the workspace again.

Ask a question:

Codex:

$okf-harness What does my workspace say about LLM Wiki structure?

Claude Code:

/okf-harness What does my workspace say about LLM Wiki structure?

Why

Most personal knowledge tools make the app the center. OKF Harness makes the local folder the center:

• raw source material stays inspectable under raw/sources/
• synthesized knowledge lives in ordinary markdown under wiki/
• citations connect topic pages back to reference pages and source IDs
• okfh --json gives agents a deterministic tool surface
• the graph report is a local HTML file, not a hosted service

The recommended layout is one workspace per knowledge domain, research area, or privacy boundary. Keep them under a local Documents/OKF Harness/ folder unless you have a reason to separate them.

The product stays narrow on purpose: local files, terminal-native commands, bounded evidence, bounded reads, and explicit provenance come first. Broader surfaces such as GUI, cloud sync, Obsidian helpers, source connectors, and vector retrieval belong in the roadmap only when they preserve those guarantees.

What It Does

• Initializes a local OKF Harness workspace.
• Installs Claude Code and Codex guidance into the workspace.
• Registers files and URL pointers as raw sources.
• Produces ingest plans so an agent can update the wiki with citations.
• Prepares bounded evidence briefs from synthesized wiki pages before answers.
• Searches and reads synthesized wiki pages for debugging and bounded continuation.
• Checks OKF conformance and Harness lint findings.
• Generates a self-contained graph report.

What Happens Behind The Scenes

The agent uses okfh --json through your local shell. For example:

• setup calls okfh init with the current agent adapter
• ingest calls okfh source add and okfh ingest plan
• answers use okfh evidence, then at most one bounded okfh read when a continuation cue is needed
• validation uses okfh check
• graph reports use okfh graph

Developers can call the CLI directly when they need to script or debug a workspace:

okfh check --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh search "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh read topics/llm-wiki --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --json

Docs

• Workflows explains the user-facing Claude Code and Codex flows.
• CLI reference lists commands, options, and JSON behavior.
• Roadmap shows the current focus and demand-ranked ideas.
• LLM context gives AI tools a concise map of the public project docs.
• Full LLM context combines the public overview, terminology, workflows, CLI reference, roadmap, and package READMEs.
• Example workspace gives a small lintable workspace.
• Contributing explains project scope and verification.
• Security explains local data boundaries and reporting.

Development

pnpm install
pnpm docs:llms
pnpm test
pnpm typecheck
pnpm build

See CONTEXT.md for the project glossary and docs/adr for architecture decisions.

Acknowledgements

Thanks to Andrej Karpathy for publishing the LLM Wiki pattern, and to Google for publishing Open Knowledge Format as a simple, portable shape for markdown knowledge bundles. OKF Harness adapts those ideas for a local, agent-first workflow.

Thanks also to Tw93's Waza and Matt Pocock's Skills for Real Engineers for shaping the development workflow behind this project.

License

Apache-2.0. See LICENSE.