A lightweight, file-first project engineering harness for coding agents.
Your repo is the system of record.
Your agent is the operator.
HarnessKit is the bridge.
Coding agents (Codex, Claude Code, Cursor...) already handle the agent runtime — model loops, tool execution, sandboxing, conversations. That layer is well-covered.
What's missing is the project engineering layer: structured documentation, design decision records, progressive context disclosure, docs health checks, and local history. Today, AGENTS.md and CLAUDE.md become dumping grounds. Project knowledge scatters across chat threads that get compacted, truncated, or lost.
Asking users to learn a new CLI to fix this defeats the purpose — it just shifts the burden.
HarnessKit is inspired by OpenAI's harness engineering philosophy: the repository itself should be the source of truth for project knowledge. But we take it further:
Build the tools for agents. Let agents serve the users.
Users install a skill. Their agent handles everything else — initializing docs, querying context, checking consistency, managing history. No CLI to memorize. No new workflow to learn.
┌─────────────────────────────────────────────────┐
│ User │
│ "What was the design rationale for auth?" │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ Agent (Codex / Claude Code / ...) │ │
│ │ │ │
│ │ ┌─────────┐ ┌────────────────────────┐ │ │
│ │ │ Skill │→ │ harnesskit CLI │ │ │
│ │ │ │ │ query / context / │ │ │
│ │ │ │ │ check / history / ... │ │ │
│ │ └─────────┘ └───────────┬────────────┘ │ │
│ └───────────────────────────┼───────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────┐ │
│ │ Repository (source of truth) │ │
│ │ AGENTS.md · docs/ · .harnesskit/ │ │
│ └───────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
| Principle | What it means |
|---|---|
| File-first | Repository files are project memory. No external databases, no cloud services. Everything is plain files in the repo. |
| SQLite is derived | .harnesskit/state is built from docs and can be rebuilt. .harnesskit/history is local checkpoint state; deleting it discards local doc snapshots. |
| Built for agents | The CLI is a tool surface that agents call. Users talk to their agent in natural language; the agent picks the right command. |
| Not a runtime | HarnessKit does not run models, manage conversations, or execute tools. It's the engineering harness, not the agent harness. |
| Lightweight | Rust CLI, no daemons, no MCP servers, no background processes. Alpha fact-store commands require the system sqlite3 CLI. |
Step 1 — Install the CLI and agent skill:
# Public alpha install
curl -fsSL https://raw.githubusercontent.com/qWaitCrypto/HarnessKit/main/install.sh | bashThis installs the latest public release by default. Use --version <tag> only when you intentionally need a pinned release.
If ~/.local/bin is not on your PATH, add it:
export PATH="$HOME/.local/bin:$PATH"For local development from this repository:
scripts/install-local-cli.sh
scripts/install-claude-skill.sh # Claude Code
scripts/install-codex-skill.sh # CodexAlpha notes:
- The public binary release currently supports Linux x86_64 and macOS x86_64/arm64.
- Fact-store-backed commands currently require
sqlite3onPATH:index,query,check,context,graph,inspect,refs,rank, andlist-docs. - The installer writes the Codex skill directly; Codex plugin packaging is optional.
- The installer can be rerun with a newer
--versiontag to upgrade. - After alpha.2,
harnesskit updatecan update the CLI and already-installed skills from GitHub releases.
Step 2 — Ask your agent to set up project docs:
> Initialize project documentation for this repo.
The agent runs harnesskit init, reads the entrypoint, and starts managing your project docs. That's it.
By default, init uses local mode: generated docs are added to .git/info/exclude so a trial does not change git status. For team-visible or open-source project memory, use harnesskit init --tracked. To inspect what would be written first, use harnesskit init --preview.
Step 3 — Work naturally:
> What was the design rationale for the auth module?
> Create a design doc for the new payment flow.
> Are our docs consistent? Anything broken?
> Snapshot the current docs before I refactor.
The agent calls the CLI behind the scenes. You never need to.
When an agent needs project context, it should not scan every doc. It asks HarnessKit for a context packet:
harnesskit context auth --jsonShape of the answer:
{
"anchor": {"path": "docs/design-docs/auth.md"},
"incoming": [
{"src_path": "docs/decisions/0003-auth-boundary.md"}
],
"outgoing": [
{"dst_path": "ARCHITECTURE.md"},
{"dst_path": "docs/product-specs/login.md"}
],
"recommended_reading_order": [
"ARCHITECTURE.md",
"docs/product-specs/login.md",
"docs/design-docs/auth.md",
"docs/decisions/0003-auth-boundary.md"
]
}The output is the smallest useful reading path for the task: architecture, product context, the focused design doc, and the decision record that constrains it.
your-repo/
├── AGENTS.md / CLAUDE.md # Agent entrypoints (thin routing tables)
├── ARCHITECTURE.md # High-level code map
├── docs/
│ ├── index.md # Docs manifest
│ ├── project.md # Project map
│ ├── DOCUMENTATION_SYSTEM.md # Documentation rules
│ ├── commands.md # Command reference
│ ├── product-specs/ # Canonical product specifications
│ ├── design-docs/ # Canonical design documents
│ ├── decisions/ # Architectural decision records
│ ├── exec-plans/ # Execution plans (active / completed)
│ ├── worklog/ # Work logs (active / archive)
│ ├── operations/ # Runbooks, operational docs
│ ├── generated/ # Auto-generated documentation
│ ├── references/ # External reference material
│ └── templates/ # Templates for new docs
└── .harnesskit/ # Internal state
├── state/ # Derived index/fact store; safe to rebuild
└── history/ # Local doc checkpoints; do not delete as cache
Agents navigate this through progressive disclosure: entrypoint → architecture → manifest → collection index → the smallest doc that answers the task. They never bulk-read everything.
CLI Reference (for agents — or curious humans)
harnesskit init [target_dir] [--schema <path>] [--docs-root <path>] [--force] [--local|--tracked] [--preview]Creates the docs scaffold. Existing files are skipped unless --force is passed. Default --local mode adds managed paths to .git/info/exclude for local isolation. Use --tracked to leave generated docs visible to git status, or --preview to print the plan without writing files.
harnesskit indexRefreshes the SQLite fact store from current docs. Incremental — only processes changed files.
harnesskit query "<terms>" [--json] # Full-text search across all docs
harnesskit context "<terms-or-path>" # Context packet with relation graph
harnesskit graph <doc_path> [--json] # Context packet for a specific docharnesskit inspect <doc_path> # Full metadata, relations, and checks for a doc
harnesskit refs <doc_path> # All incoming references to a docharnesskit list-docs # All managed docs with metadata
harnesskit rank # Top 20 most-referenced docsharnesskit check [--json] [--strict] [--rules <rule-list>]Validates all managed docs — missing required files, broken links, stale anchors, duplicate content, frontmatter issues, and more.
harnesskit doctor [--json]Checks the CLI, sqlite3, git, target path, .harnesskit/state, .harnesskit/history, installed agent skills, and PATH status. Use this when first installing or when a sandboxed environment reports a read-only fact store.
harnesskit history status # Changed since last snapshot?
harnesskit history snapshot -m "<message>" # Create a checkpoint
harnesskit history list # List all snapshots
harnesskit history diff <snapshot-id|latest> # What changed since snapshot
harnesskit history diff <snap-a> <snap-b> # Diff between two snapshots
harnesskit history restore <snapshot-id> [--apply] # Preview or restore a snapshotLightweight local versioning for docs — not a replacement for git, but useful for doc-level checkpoints during complex tasks.
harnesskit update # Update to the latest release
harnesskit update --version <release-tag> # Update to a pinned releaseThe agent skill is a single shared file that teaches Codex and Claude Code the HarnessKit workflow:
- When to trigger — Any task involving project docs, architecture, design, plans, or specs
- How to orient — Read
AGENTS.mdorCLAUDE.mdfirst, then follow progressive disclosure - When to use the CLI — Prefer
query/contextover manual file search; runcheckafter doc changes; usehistorybefore risky edits - How to update docs — Edit the narrowest relevant doc, create from templates when needed, keep entrypoints thin
The skill lives at agent-surfaces/skills/harnesskit/SKILL.md — one source of truth for both Codex and Claude Code.
src/ Rust CLI implementation
schemas/ Doc scaffold schema (file-first-v0.yaml)
templates/ Entrypoint, core doc, and collection templates
agent-surfaces/ Shared agent skill + Codex / Claude Code packaging
scripts/ Install, uninstall, sync, and release scripts
examples/ Example initialized repos
docs/ Internal development docs
examples/web-app-with-auth/shows a small auth documentation graph with a product spec, design doc, decision record, and sample context packet shape.
Try it after building or installing HarnessKit:
harnesskit index examples/web-app-with-auth
harnesskit context auth examples/web-app-with-auth --json- Not an agent runtime. It doesn't run models, manage threads, or call tools.
- Not a RAG pipeline. No embeddings, no vector stores. Just FTS5 and file structure.
- Not a SaaS product. Everything runs locally. No accounts, no cloud, no telemetry.
- Not a replacement for git. The history feature is for doc-level checkpoints, not source control.
Latest Release · Installer · Schema Reference · Agent Skill
MIT License · Built by qWait