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/        │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Step 1 — Install the CLI and agent skill:

# Public alpha install
curl -fsSL https://raw.githubusercontent.com/qWaitCrypto/HarnessKit/main/install.sh | bash

This 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         # Codex

Alpha notes:

• The public binary release currently supports Linux x86_64 and macOS x86_64/arm64.
• Fact-store-backed commands currently require sqlite3 on PATH: index, query, check, context, graph, inspect, refs, rank, and list-docs.
• The installer writes the Codex skill directly; Codex plugin packaging is optional.
• The installer can be rerun with a newer --version tag to upgrade.
• After alpha.2, harnesskit update can 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 --json

Shape 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.

harnesskit init [target_dir] [--schema <path>] [--docs-root <path>] [--force] [--local|--tracked] [--preview]

harnesskit index

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 doc

harnesskit inspect <doc_path>    # Full metadata, relations, and checks for a doc
harnesskit refs <doc_path>       # All incoming references to a doc

harnesskit list-docs    # All managed docs with metadata
harnesskit rank         # Top 20 most-referenced docs

harnesskit check [--json] [--strict] [--rules <rule-list>]

harnesskit doctor [--json]

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 snapshot

harnesskit update                         # Update to the latest release
harnesskit update --version <release-tag> # Update to a pinned release

The agent skill is a single shared file that teaches Codex and Claude Code the HarnessKit workflow:

1. When to trigger — Any task involving project docs, architecture, design, plans, or specs
2. How to orient — Read AGENTS.md or CLAUDE.md first, then follow progressive disclosure
3. When to use the CLI — Prefer query / context over manual file search; run check after doc changes; use history before risky edits
4. 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.