FreeHarness

FreeHarness is an agnostic agentic-engineering harness for AI Engineering, Software Engineering for AI Systems and Data Engineering work. A single neutral canonical source (behavior rules, skills, agents, hooks, MCP list, spec-driven schema) is translated by per-harness adapters into each tool's layout: Claude Code, OpenCode, or a Claude Code plugin directory. It vendors the engines it depends on (OpenSpec for spec-driven development, the vendored claude-mem engine for memory), tracks them against upstream, and harvests ideas from other projects (Superpowers, ECC, Ruflo, the official Claude Code plugins) rewritten in its own style. Goals: efficiency, quality, token economy, modular and confirmable install. License: MIT.

Status

v0.4.1 — v1, v2, v3, v4 and v4.1 shipped (v4 sandbox-complete; the [machine] measurements are listed in Documents/ROADMAP.md); 19 capability specs published in openspec/specs/ (the v4 change is archived under openspec/changes/archive/freeharness-v4).

• v1: canonical content (rules with the Tool Routing contract, skills, agents, MCP, hooks) and the installer with the claude-code and opencode adapters.
• v2: hexagonal core with a dependency-rule linter, two-pass confirmable install, bootstrap, doctor --fix, vendored OpenSpec engine (own openspec bin), vendored claude-mem daemon, sync check, one-command install.sh.
• v3: memory installed from our build and slimmed (engine trimmed, short hooks, own viewer), node:test suites + CI, npm tarball + hosted install.sh + --target plugin, sync adopt, rich doctor / uninstall / update, content harvest from the official plugins, cost tracker, weekly upstream radar.
• v4: harness intelligence (rules under 200 lines, language density rule + doctor lint, output contracts, subagent briefs and validated handoffs, verification grounding, CoT-leakage standard), token-economy hooks (output pruner, context monitor, config guard, repeat-tool reminder, post-compaction re-injection, cache-hygiene settings, cost prefix, cost report --sinks), upstream claude-mem 13.24 ports + PreCompact checkpoint, OpenSpec 1.12 ports + supersession/EARS/task annotations + converge hook, 45 skill eval cases with a runner and plugin validate in CI, opt-in local-model and MCP profiles.

Next: the v4 [machine] measurements (compare weeks, recall re-verify, first eval run, GPU profiles); v5 moves to an own CLI on the Claude Agent SDK plus OpenCode. Details: Documents/ROADMAP.md.

Quickstart

Only Node.js >= 18 and git must be present.

1. Install once per machine (builds, links freeharness + the vendored openspec into ~/.local/bin, installs the global set into ~/.claude, sets up memory, removes leftovers of earlier installs, runs doctor):

bash install.sh --yes --with-memory
# or, without a checkout:
curl -fsSL https://raw.githubusercontent.com/anegrelli/FreeHarness/main/install.sh | bash -s -- --yes --with-memory

2. Activate in each project (writes CLAUDE.md from the template, the /fh-context command and the SDD set openspec/ + /opsx; skills, agents, hooks, memory and MCP stay global):

cd <project> && freeharness bootstrap
# then, in Claude Code: /fh-context   (fills CLAUDE.md from the codebase; never /init)
# commit CLAUDE.md + openspec/

Details, reference and troubleshooting: Documents/INSTALL.md; manual and advanced paths: Documents/ADVANCED.md.

Commands

| Command | What it does | | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | freeharness init | Install capabilities into the target harness(es).--target claude-code,opencode,plugin, --scope user\|project, --only <caps>, --project <dir>, --dry-run, --yes | | freeharness update [--check] | Compare the install manifest with the running CLI / repo HEAD; re-emit idempotently | | freeharness bootstrap | Activate a project:CLAUDE.md (template, if absent) + /fh-context + SDD (openspec/, /opsx, openspec-* skills). Global-only capabilities are refused at project scope unless init --allow-project-copies | | freeharness cleanup | Remove leftovers/duplicates from a fixed list (--scope user: parked upstream claude-mem, its backups, upstream claude-mem hook entries in settings.json once the plugin is registered, legacy /openspec commands, global @fission-ai/openspec, a global npm freeharness link; --scope project: legacy /openspec commands, project copies of global agents/skills, duplicate hook entries). Your own skills/agents are never listed. Preview -> confirm | | freeharness doctor [--fix] | Version and resolved binaries (shadowing, a CLI running from outside~/.local/bin), hooks, skills/agents (yours listed as INFO), manifest drift, runtime deps, PROVENANCE baselines, memory verdict (stale worker version), leftovers (user) / duplicates and unresolved placeholders (project) | | /fh-context (in Claude Code) | Project command written bybootstrap: fills the <placeholder> fields of the project CLAUDE.md from the codebase | | freeharness list | Capabilities, required/optional, targets | | freeharness uninstall | Remove only what the install manifest lists; never ~/.claude-mem data or user files | | freeharness memory status\|backup\|activate\|restart [--if-running] | Which memory build is active; copy the data dir; make the FreeHarness build the only active one; restart the worker (--if-running: no-op without one) | | freeharness cost report [--sinks]\|prefix\|prices | Aggregate the cost-tracker log per project and model; rank token sinks per project / task class; estimate the prompt prefix vs budget; print the editable price table path | | freeharness sync check\|adopt <sdd\|memory> | Report drift of the vendored trees vs upstream; adopt tracked paths with preview + confirm + baseline bump |

What gets installed (user scope, Claude Code)

• Global behavior rules (~/.claude/CLAUDE.md) with a pointer to the Tool Routing table, plus the per-project context template. The table itself lives in canonical/rules/routing.md, printed as a <routing> block by the SessionStart hook on every source (Claude Code and plugin targets) and appended to AGENTS.md for OpenCode.
• 10 skills: test-driven-development, subagent-driven-development, systematic-debugging, verification-before-completion, code-review, git-workflow, agentic-architecture, agent-evaluation, local-code, report-formatting. report-formatting and agent-evaluation are owner-run: hidden from the model's skill list (disable-model-invocation: true) and dispatched by name (/report-formatting, /agent-evaluation; /<plugin>:report-formatting on a plugin install), never selected by the model.
• 8 agents: python-reviewer, database-reviewer, security-reviewer, pr-reviewer, agentic-architect, report-formatter, explorer-ai-engineer-analyst, test-writer (neutral tiers mapped to opus/sonnet/haiku).
• 12 hook registrations from 10 scripts: SessionStart pointer (compact/resume re-inject the checkpoint), PreCompact checkpoint, memory guard and config guard (PreToolUse, deny), repeat-tool reminder (PreToolUse + UserPromptSubmit, advisory), security guidance (PreToolUse, advisory), the opt-in converge loop (Stop; armed per project by .freeharness/converge.json), and from the cost capability (part of the default set) the cost tracker (Stop + SessionEnd), output pruner (PostToolUse Bash) and context monitor (Stop) plus the 1h prompt-cache TTL settings. Details and how to disable each: Documents/ADVANCED.md section 6.
• SDD: the spec-driven schema override (user-global) and the vendored openspec bin; /opsx commands, openspec-* skills and /fh-context per project via bootstrap.
• Memory (optional): the slim free-mem plugin built from the vendored claude-mem engine, installed into the Claude Code plugin cache and registered additively, with the FreeHarness viewer.
• MCP: servers from canonical/mcp/servers.json (context7) via claude mcp add.

Capabilities: rules, sdd, skills, agents, safety, mcp, cost (required; the token-economy hooks are core) + memory (optional).

Structure

FreeHarness/
├── package.json         npm workspaces root: build (sdd -> core -> cli), verify, test
├── install.sh           one-command installer (self-bootstrapping)
├── sources.yaml         upstream watch list + baselines (radar)
├── canonical/           neutral source of truth
│   ├── rules/           CLAUDE.md (global rules), safety.md, project-CLAUDE.template.md
│   ├── commands/        fh-context.md (project slash command written by bootstrap)
│   ├── skills/          10 skills (SKILL.md, reference/, scripts/)
│   ├── agents/          8 agents + README (tier map)
│   ├── hooks/           4 hook scripts + Claude Code fragments + cost-prices.json
│   ├── mcp/             servers.json
│   ├── profiles/        opt-in profiles: local-ollama, local-llamacpp, mcp catalog (`init --profile`)
│   ├── evals/           promptfoo red-team config (on demand); skills carry evals/cases.yaml
│   ├── openspec/        spec-driven schema override + templates
│   ├── HARVEST.yaml     classification of the official Claude Code plugins
│   └── PROVENANCE.yaml  upstream path/commit/hash per harvested file
├── packages/
│   ├── core/            @freeharness/core — pure domain, zero deps
│   ├── cli/             freeharness — CLI, composition root, adapters
│   ├── sdd/             @freeharness/sdd — vendored OpenSpec slice + openspec bin
│   └── memory/          vendored claude-mem (slim) + Bun build + viewer
├── scripts/             check-arch.mjs, upstream-radar.mjs, skill-evals.mjs, simulate-session.mjs
├── openspec/            FreeHarness's own specs and archived changes
├── .github/workflows/   ci.yml, upstream-radar.yml
├── Documents/           project documentation
├── LICENSE, NOTICE
└── README.md

Documents

• Documents/architecture.md — as-built architecture: canonical -> adapters -> harness, packages and dependency rule, capabilities per target, memory and SDD stacks, sync/radar, install manifest, cost tracker, harvest, tests and CI, distribution.
• Documents/INSTALL.md — install once per machine, activate per project, short reference.
• Documents/ADVANCED.md — manual build, single capabilities and project copies, memory switch by hand, cost tracking, OpenCode / plugin / npm targets, cleanup details, where things land.
• Documents/ROADMAP.md — v4 and v5 direction; v3 machine-only leftovers.
• Documents/TEST-MATRIX.md — every spec scenario mapped to a test or a machine-only tag.
• Documents/INTEGRATION.md — the Claude Code integration simulation (npm run simulate): what it proves, the M-items only a real session proves, the measured hook table.
• Documents/RELEASE-CHECKLIST.md — manual verifications (M1-M9) before a release.
• Documents/PUBLISHING.md — npm tarball contents, pack, publish, tag (owner only).
• Documents/UPSTREAM-RADAR.md — the weekly upstream report: sources, what it reports, from finding to work.
• Documents/Prompt_ClaudeCode_Global.md, Documents/Prompt_ClaudeCowork.md — reference copies of the global prompts.

Principles

• One neutral source; adapters do the translation. Model choice stays a tier, never a model name.
• Hexagonal-lite: a framework-free core and ports; harness and engine specifics only in adapters (enforced by check:arch).
• Own the engines: OpenSpec and claude-mem are vendored subsets with PROVENANCE, sync check/adopt, and a weekly radar; never auto-merged.
• Every side effect is previewed and confirmed; settings merges are additive; uninstall removes only what was emitted.
• Spec-first: FreeHarness evolves through its own openspec/ (/opsx). Nothing duplicates OpenSpec's job.
• Harvest, rewrite, credit: no verbatim third-party content; every derived file has provenance.

License

MIT (see LICENSE). Third-party attributions for the vendored OpenSpec (MIT), claude-mem (Apache-2.0) and the harvested Claude Code plugin concepts are in NOTICE.