A self-improving operations layer for Claude Code — it wraps the agent in a senior engineering process so non-trivial work is designed before it's built and verified before it's called done.
English · 한국어
Claude Code is already a capable agent. khaness adds the discipline of a senior engineering process on top of it — structure, gates, and memory — so that the agent designs before it builds and verifies before it claims done.
It is a meta-layer: you keep using Claude Code as normal, and khaness wraps each substantial task in a DGE loop:
- Designer — "are we building the right thing?" For architectural decisions, a 3-agent debate (Planner → Critic → Architect) converges on a design, deterministically.
- Generator — "did we build it as designed?" Implement the agreed design, nothing more.
- Evaluator — "does it actually work?" A 3-tier stack: mechanical validators → a semantic LLM evaluator → optional multi-model consensus. Verification gates the next step.
Claude Code is powerful. khaness makes it disciplined.
- You state a goal. A prompt hook detects design-class work and surfaces the debate engine.
- Design converges.
/harness-debatespins up Planner / Critic / Architect subagents. The Critic attacks the proposal on assumption, failure, and over-simplification axes; the Architect renders a verdict. Convergence is deterministic — two consecutive approvals with an identical ontology-snapshot hash — and every step is appended to an event log so the decision is replayable. - Generation proceeds against the locked design, with lifecycle hooks enforcing guardrails (destructive-command denial, sensitive-file protection, branch/PR conventions).
- Evaluation gates done. ~40 mechanical validators run as a regression suite; a semantic evaluator scores 5 axes plus a strict completeness boolean; a paradox guard stops an agent from grading its own work as finished.
- The harness improves itself. A repeated failure becomes a permanent skill or hook rule (the 2-Strike Rule), so the same mistake can't recur.
As a Claude Code plugin (recommended):
claude plugin marketplace add github:trevi00/khaness
claude plugin install khaness@khanessThe plugin bundles the commands, agents, skills, and hooks; Claude Code resolves the bundled scripts via ${CLAUDE_PLUGIN_ROOT}, and runtime state lives in your ~/.claude. pip install -r requirements.txt once for the PyYAML dependency.
Or as a ~/.claude clone (for hacking on the harness itself):
git clone https://github.com/trevi00/khaness ~/.claude
cd ~/.claude && bash install.shinstall.sh generates a portable settings.json from the template (interpolating your clone location into the hook paths), installs Python deps, and runs the regression suite to prove the install is sound. Then open a new Claude Code session in that directory.
A few commands to try:
/harness-debate <a design decision> # 3-agent design convergence
/harness-autopilot # drive a task through the DGE phases
/harness-audit # 6-axis harness self-check
First thing in any project: create
.claude/tech-stack.yamldeclaring your stack, so the skill tree filters to what's relevant.
| 42 subagents | Planner / Critic / Architect debate roles, evaluators, researchers, and project-workflow agents |
17 harness-* commands |
debate, autopilot, audit, interview, team, ultrawork, … |
69 kha-* workflow skills |
spec → plan → execute → verify project lifecycle |
| ~40 validators | mechanical pass/fail gates run as a regression suite |
| 254 skill docs total | the 69 kha-* above + per-stack trees (java, kotlin, typescript, flutter, …) + the always-on _common/ set |
The scripts/ codebase is a one-directional 4-layer stack — lib/ → validators/ → handlers/ → engine/ — and is Open/Closed by design: a new provider, worker, or validator is a new file + one registry line, never an edit to existing code.
📖 Documentation: ARCHITECTURE.md (the full map) · CONTRIBUTING.md (get started) · CLAUDE.md (the operating contract loaded each session)
v0.1 / experimental. It works and its regression suite is green (run_all + run_units, verified from a fresh clone), but it is opinionated, developed primarily on Windows (cross-platform paths are guarded but less battle-tested), and APIs may shift.
Runtime data — state/, memory/, brain/, atlas/, your live HANDOFF.md — is per-user and git-ignored; the repo ships templates and machinery, not session state.
This harness was built by an engineer who distrusts absolute claims, and the design reflects it:
- The mutation-gate is defense-in-depth, not a security boundary. It surfaces and blocks accidental writes to runtime-policy files (a direct
Writeto.claude/settings.jsonis denied), but a shell-capable agent can bypass token gates. The real boundary is operator review of committed diffs. - Hooks fail open. A crashing hook exits cleanly rather than blocking your tools — availability over enforcement.
- Completeness is quantified, not asserted. "Done" is reported with known-defect count and coverage; words like "perfect" are avoided on purpose.
If you find a claim stronger than the code that backs it, that's a bug — please open an issue.
khaness stands on ideas from three projects, and is built referencing them:
- get-shit-done (GSD) — the spec-driven, phase-loop project workflow. khaness's
kha-*commands and the bundledget-shit-done/subsystem derive from it. - Ouroboros — the event-sourcing / stateless-resumption pattern behind the debate engine and the Ralph verify-fix loop (see
scripts/engine/debate.py,scripts/engine/ralph.py). - OMC — the orchestration model and the one-directional 4-layer
scripts/architecture (lib/→validators/→handlers/→engine/).
MIT.
Design it. Build it. Verify it.