agent-harness
Health Pass
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 14 GitHub stars
Code Fail
- rm -rf — Recursive force deletion command in .claude/settings.json
- rm -rf — Recursive force deletion command in .github/workflows/deb.yml
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Performance layer for coding agents — skills, instincts, memory, security and research-first for Claude Code, Codex, OpenCode, Cursor, Kiro, Cline, Aider.
agent-harness
A performance layer for coding agents. Skills, instincts, memory, security, and a research-first workflow that works the same in Claude Code, Codex, Opencode, Cursor, Kiro CLI, Kiro, Cline, Aider and anything else.
I built this because I was tired of watching agents re-read the same codebase for 3 minutes every new session, re-research the same questions, and then guess at APIs anyway. Harness caches what matters and enforces a research step before code.
Early days. It works for me daily, API might still shift a bit. Issues and small PRs welcome.
What it does
Four things that actually moved the needle for me:
Skills: reusable markdown skills (SKILL.md + scripts). Write once, use in every harness. Follows the agent skills spec.
harness skill list
Instincts: hooks that fire on their own. Pre-tool checks, post-edit format + typecheck, session start hydration. Muscle memory so the agent does the right thing without you prompting it.
Memory: persistent context that survives between sessions. MEMORY.md stays under ~8k tokens and loads in a couple seconds. No more 3 minute cold start re-explaining your project.
memory/
MEMORY.md # long term, always loaded
SOUL.md # who the agent is
USER.md # who you are
sessions/ # raw session notes, pruned after a bit
decisions/ # ADRs when we pick between options
On my main repo cold start went from ~180s to about 13s.
Security: default deny. Prompt injection checks, secret scanning before commits, bash allowlist, file write boundaries. Nothing fancy, just catches the dumb mistakes before they ship.
Research first: the agent has to look things up before it edits. Checks research/findings/ first, then codebase, then web. Writes a short plan in research/plans/ and waits for a quick ok. Sounds strict but it cuts rework a lot.
research/
findings/ # one file per topic, cached
plans/ # short plan per task
evidence/ # links, repros, citations
More detail in skills/, instincts/, memory/, security/, research/.
Performance
Numbers below are from my own setup (250k LOC TS monorepo, M2 Max), not universal claims. Independent A/B runs on other models and hardware live on the Benchmark tab, raw rows in docs/benchmarks.md.
- cold start 180s -> 13s
- tokens per task down ~65 percent
- tool calls down ~40 percent
- hook overhead p99 under 100ms
Run it yourself:
harness bench --quick
harness bench --compare # diffs against .harness/bench.json (first run saves it)
Notes and how it works in docs/performance.md. One measured caveat from an M4 Mac mini: guards run ~5ms, the post-edit check ~300ms in JS repos, details on the Benchmark tab.
Verified regardless of model (file arithmetic, not behavior): optimize shrinks overgrown memory 3-11x to budget, and the repo index compresses orientation 13.5x vs reading everything. Method in docs/benchmarks.md.
Works with
You write skills and memory once, harness installs to each tool.
- Claude Code ->
.claude/settings.json+.claude/skills/ - Opencode ->
.opencode/plugins/harness.js+.opencode/skills/ - Codex ->
.codex/hooks.json+.agents/skills/ - Cursor ->
.cursor/hooks.json+.cursor/rules/*.mdc - Kiro CLI ->
.kiro/hooks/+.kiro/skills/ - Kiro (Desktop) ->
.kiro/hooks/+.kiro/steering/ - Cline ->
.clinerules/*.md+AGENTS.md - Aider ->
.aider.conf.yml+CONVENTIONS.md - anything else ->
.harness/+AGENTS.md
agent-harness/
skills/ # shared
instincts/ # shared
memory/ # shared
research/ # shared
adapters/
claude/
opencode/
codex/
cursor/
kiro-cli/
kiro-desktop/
cline/
aider/
See adapters/ for the per-tool mappings.
Quick start
# one line, the default (macOS + Linux, needs Node >= 20)
curl -fsSL https://theelephantcoder.com/agent-harness/install.sh | bash
# pin a release instead of main, or install user-local
curl -fsSL ... | HARNESS_REF=v0.2.1 bash
HARNESS_PREFIX=$HOME/.local bash scripts/install-cli.sh
# from source (macOS + Linux, needs Node >=20)
git clone https://github.com/TheElephantCoder/agent-harness.git
cd agent-harness
npm install
npm run build
npm link
Those are the only two ways to install: the curl script (default), or a source checkout. npm, npx, pip, apt, and brew installs are retired; existing ones keep updating through harness upgrade.
On Ubuntu, if node --version is under 20, grab a newer Node first:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git bash python3
In your project:
cd your-project
harness init
# detects harnesses from project files, or:
harness init --auto # tries to detect what you use
harness init --migrate # add to existing project without overwriting
harness doctor # check everything wired up
harness bench --quick # seconds, measures hooks/skills/cold-start
What init creates:
your-project/
.harness/config.json
.harness/hooks/
AGENTS.md
MEMORY.md
.claude/skills/*/SKILL.md # if you picked claude
opencode.json # if you picked opencode
.cursor/rules/ # if you picked cursor
Day to day:
harness optimize # prune MEMORY.md to budget, archive overflow
harness optimizations # cost controls, all on (menu item 4 too)
harness doctor # verify install, scan staged for secrets
harness bench --compare # measure against baseline
harness skill list # skills with ~token cost
harness skill search "hook" # grep skills
harness memory sync "note" # append + re-prune
harness security audit # run the audit script here
CLI
harness init [--harness <name>] [--auto] [--migrate] [--dry-run] [--force]
harness doctor [--fix] [--strict] [--json]
harness status
harness bench [--compare] [--quick]
harness optimize
harness optimizations [enable|disable] [name|all]
harness map
harness skill <list|search|info|add|remove|verify|lint|update> ...
harness memory <show|prune|sync|edit|stats|search|backup> [note]
harness instinct <list|enable|disable|test> [name]
harness research [query|search|remove] ...
harness security <audit|scan> [--staged]
harness adapter <list|add|remove> [name]
harness upgrade [--check]
Run harness to open the workspace. Click a section, then click anywhere on an action row to open it. In submenus, click a setting to toggle it or click ‹ Back to return. The scroll wheel moves through long lists. Tab and Shift+Tab switch between Project, Tools, and Application. Use the arrow keys to highlight an action and Enter to open it. Type part of any command name to search across all three sections. Esc goes back.
When a newer version is available, click the Update available callout on the home screen or press Ctrl+U. Restart harness after a successful update. npm and Python installs use their existing updater. Official source checkouts update by fast-forwarding a clean main branch.
Use harness --reduced-motion to skip the animated wordmark. For screen readers, harness --plain prints the menus and Settings descriptions as ordinary terminal lines. Enter a command by name or by a unique part of its name.
harness --help has the rest. Also docs/cli.md.
How it fits together
adapter layer: Claude Code | Codex | Opencode | Cursor | Kiro CLI | Kiro | Cline | Aider
-------------------------------------------------------------------------
harness core: skills | instincts | memory | security | research
cache + batch + compress (perf bits)
---------------------------------------------------------
your project: .harness / MEMORY.md / AGENTS.md
No lock in. Adapters are just file mappings. Remove harness and your project still works, you just lose the caching and guardrails.
Research first flow
For anything that touches more than a couple files:
- research -> check
research/findings/, grep codebase, web search if needed - plan -> write
research/plans/<task>.md(approach, files, risks) - approve -> you give a quick ok (small low risk edits auto approve)
- build -> implement
- verify -> tests +
harness bench+harness doctor - remember ->
harness optimizeprunes MEMORY.md to budget (overflow archived)
instincts/research-first blocks multi-file edits until the plan exists. Annoying at first, saves time later.
Examples
# new next app with harness from the start
npx create-next-app@latest my-app && cd my-app
harness init --auto # needs harness installed, see quick start
harness doctor --fix
Custom instinct after a TS edit:
# instincts/my-check/SKILL.md
---
name: my-check
trigger: post-edit
when: "file =~ \\.ts$"
---
Run `npm run typecheck` after TS edits. Block commit on failure.
Contributing
Small PRs are easiest to review. See CONTRIBUTING.md.
Good first issues are labeled skill, adapter, instinct.
If you touch perf, include a before/after harness bench.
Security
See SECURITY.md. For vulns DM @theelephantcoder on Discord or open a GitHub issue and note it's private.
License
MIT - TheElephantCoder
https://github.com/TheElephantCoder/agent-harness
Contact
Business inquiries: [email protected]
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found