Harness Forge

Harness Forge enhances AI coding agents by continuously improving their performance and visibility.

<p align="center"> <img src="https://img.shields.io/badge/%F0%9F%94%A8_harness--forge-v1.5.2-6C3FC5?style=for-the-badge" alt="version" /> </p> <h1 align="center">🔨 Harness Forge</h1> <p align="center"> <strong>Your AI coding agent is only as good as its harness.</strong> <br /> One command to scan, equip, and continuously improve any AI coding agent in your repository. </p> <p align="center"> <img src="./assets/demo.gif" alt="Harness Forge demo" width="700" /> </p> <p align="center"> <a href="https://github.com/ldilov/harness-forge/actions/workflows/ci.yml"> <img alt="Build" src="https://img.shields.io/github/actions/workflow/status/ldilov/harness-forge/ci.yml?branch=main&style=for-the-badge&logo=githubactions&label=build&color=2ea44f" /> </a> <a href="https://www.npmjs.com/package/@harness-forge/cli"> <img alt="npm" src="https://img.shields.io/npm/v/@harness-forge/cli?style=for-the-badge&logo=npm&color=CB3837" /> </a> <a href="https://www.npmjs.com/package/@harness-forge/cli"> <img alt="downloads" src="https://img.shields.io/npm/dm/@harness-forge/cli?style=for-the-badge&logo=npm&label=downloads&color=0070f3" /> </a> <a href="https://github.com/ldilov/harness-forge/stargazers"> <img alt="stars" src="https://img.shields.io/github/stars/ldilov/harness-forge?style=for-the-badge&logo=github&color=f5c518" /> </a> <a href="./LICENSE"> <img alt="license" src="https://img.shields.io/badge/license-GPL--3.0-EF4444?style=for-the-badge" /> </a> <img alt="node" src="https://img.shields.io/badge/node-22+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" /> </p> <p align="center"> <a href="#-get-started-in-60-seconds">🚀 Get Started</a> &bull; <a href="#-the-living-loop--your-harness-gets-smarter">🔄 Living Loop</a> &bull; <a href="#-real-time-dashboard">📊 Dashboard</a> &bull; <a href="#-your-daily-workflow">⌨️ Commands</a> &bull; <a href="#-real-world-scenarios">💡 Scenarios</a> &bull; <a href="#-supported-targets">🎯 Targets</a> &bull; <a href="#-faq">❓ FAQ</a> </p>
<!-- LAYER 1: What is this? (5 seconds) --> <table> <tr> <td align="center" width="33%">

🔍 Scans & Equips

Your AI agent gets your repo's languages, frameworks, and patterns from the first prompt

</td> <td align="center" width="33%">

🔄 Self-Improves

A closed feedback loop learns what works, tunes itself, and gets smarter every session

</td> <td align="center" width="33%">

📊 Full Visibility

Real-time dashboard shows every decision, token spend, and compaction — no black boxes

</td> </tr> </table> <br />
Without Harness ForgeWith Harness Forge
🧠 ContextAgent guesses at project structureAgent knows your languages, frameworks, boundaries
⚡ PerformanceStarts fresh every sessionSelf-improves over time via the Living Loop
📊 VisibilityBlack box — no idea what the agent decidedReal-time dashboard with 20 live panels
💰 CostWasted tokens on retries and wrong pathsCompaction + auto-tuning saves 20-40%
📤 PortabilityStuck on one machine, one setupExport & import learned patterns as .hfb bundles
<p align="center"> <img src="https://img.shields.io/badge/🎯_targets-4-6C3FC5?style=for-the-badge" alt="4 targets" /> <img src="https://img.shields.io/badge/🌐_languages-14-0070f3?style=for-the-badge" alt="14 languages" /> <img src="https://img.shields.io/badge/🏗️_frameworks-12-2ea44f?style=for-the-badge" alt="12 frameworks" /> <img src="https://img.shields.io/badge/🛠️_skills-45+-f97316?style=for-the-badge" alt="45+ skills" /> <img src="https://img.shields.io/badge/📊_commands-50+-EF4444?style=for-the-badge" alt="50+ commands" /> </p> <p align="center"> <img alt="Loop" src="https://img.shields.io/badge/loop-self--improving-brightgreen?style=flat-square" /> <img alt="Patterns" src="https://img.shields.io/badge/patterns-auto--learned-blue?style=flat-square" /> <img alt="Tunings" src="https://img.shields.io/badge/tunings-guardrailed-orange?style=flat-square" /> </p>
<!-- LAYER 2: The differentiators (15 seconds) -->

🔄 The Living Loop — Your Harness Gets Smarter

Most tools configure once and forget. Harness Forge keeps learning.

<p align="center"> 
  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
  │ 🔍       │    │ 🧠       │    │ ⚡       │    │ 📤       │    │ 📥       │
  │ OBSERVE  │───▶│  LEARN   │───▶│  ADAPT   │───▶│  SHARE   │───▶│  IMPORT  │
  │          │    │          │    │          │    │          │    │          │
  │ Tracks   │    │ Finds    │    │ Auto-    │    │ Export   │    │ Bootstrap│
  │ sessions │    │ patterns │    │ tunes    │    │ bundles  │    │ anywhere │
  └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
        ▲                                                              │
        └──────────────────────────────────────────────────────────────┘
</p> <table> <tr> <td width="50%">

📅 Day 1 — You install

npx @harness-forge/cli

Scans your repo. Installs skills, rules, knowledge packs. Default settings. Everything works out of the box.

</td> <td width="50%">

📅 Day 3 — After ~10 sessions

🧠 Pattern found: "Summarize" saves 40% more tokens
   than "Trim" in this repo (confidence: 82%)

⚡ Auto-tuned: compaction threshold 75% → 65%
   Result: 20% fewer budget warnings
</td> </tr> <tr> <td width="50%">

📅 Day 5 — Share with your team

hforge export --bundle my-team.hfb
# Send to a teammate →
hforge import my-team.hfb
# They get your learned patterns instantly
</td> <td width="50%">

📅 Ongoing — Dashboard shows it all

hforge dashboard

Loop health ring, effectiveness scores, pattern list, tuning log — live in your browser.

</td> </tr> </table>

The more you use it, the better it gets. After ~10 sessions, Harness Forge has learned your repo's patterns and tuned itself for optimal performance. No manual configuration needed.

<details> <summary><strong>🛡️ Guardrails — auto-tuning is safe</strong></summary>
  • Every tunable parameter has hard min/max bounds — the tuner can't go wild
  • Every change is logged with before/after values and the pattern that triggered it
  • If the next 3 sessions score worse, the tuning is automatically reverted
  • Your manual config overrides are sacred — the tuner won't touch them
  • The dashboard shows every tuning with a one-click revert button
</details>

📊 Real-Time Dashboard

hforge dashboard — see everything, live in your browser.

<p align="center"> <img src="./assets/dashboard.jpeg" alt="Harness Forge Dashboard" width="700" /> </p> <p align="center"> <img src="https://img.shields.io/badge/📊_dashboard-20_live_panels-6C3FC5?style=for-the-badge" alt="20 panels" /> <img src="https://img.shields.io/badge/🔔_notifications-desktop_alerts-2ea44f?style=for-the-badge" alt="notifications" /> <img src="https://img.shields.io/badge/🔌_connection-websocket_realtime-0070f3?style=for-the-badge" alt="realtime" /> </p> <table> <tr> <td align="center" width="25%">

🔄 Loop Ring

Live status of each loop stage with health score

</td> <td align="center" width="25%">

📈 Effectiveness

Session score trend — are things getting better?

</td> <td align="center" width="25%">

🧠 Insights

Discovered patterns with confidence bars

</td> <td align="center" width="25%">

⚡ Tuning Log

Policy changes with one-click revert

</td> </tr> </table> <details> <summary><strong>📋 All 20 dashboard panels</strong></summary>
PanelWhat it shows
🔢 KPI CardsTotal events, tokens, enforcement level, budget gauge
📈 Event TimelineScatter plot of all events over time, color-coded by category
💾 Memory PressureToken usage line chart with threshold marklines
📊 Budget BreakdownDonut chart of budget allocation (hot-path, output, tools, safety)
📋 Live Event FeedSearchable, expandable table of every harness decision
🤖 Subagent BriefsDelegated tasks, their context, and outcomes
📊 Brief MetricsSubagent activity summary and success rates
🔇 Suppression GaugeHow many duplicate context items were removed
🚪 Expansion GateHistory access requests — granted vs denied
⚙️ Config EditorEdit memory-policy, context-budget, load-order live
🔄 Loop Health RingSelf-improvement cycle status with stage counts
📈 Effectiveness TrendSession score sparkline (last 20 sessions)
🧠 Insights PanelDiscovered patterns with confidence and "NEW" badges
⚡ Tuning LogPolicy changes with before/after and revert button
📊 Event DistributionBar chart of top event types
⏱️ Event RateEvents per minute over time
🗺️ Event HeatmapCategory × time heatmap
💰 Tokens SavedRunning counter of tokens saved by compaction
📊 Profile DistributionOutput profile selection breakdown
ℹ️ Session InfoSession ID, uptime, version, connection status
</details>

🔔 Desktop notifications for critical events — budget exceeded, memory rotation, tuning applied, pattern discovered.

🏢 Multi-project support — switch between projects in one dashboard. Your project list is saved in the browser.

<!-- LAYER 3: Getting started and daily use (1 minute) -->

🚀 Get Started in 60 Seconds

<table> <tr> <td width="55%"> 
npx @harness-forge/cli

The CLI walks you through:

  1. 🎯 Which AI targets (Codex, Claude Code, or both)
  2. 📊 How deep (quick / recommended / advanced)
  3. 👀 Preview of exactly what gets created
  4. ✅ One confirmation and you're done

Then make hforge available on your PATH:

npx @harness-forge/cli shell setup --yes
</td> <td width="45%" align="center">

One-liner for CI / scripts:

hforge init \
  --root . \
  --agent codex \
  --agent claude-code \
  --setup-profile recommended \
  --yes

Verify everything is healthy:

hforge doctor --root . --json
</td> </tr> </table>

⌨️ Your Daily Workflow

Commands organized by when you use them — not alphabetically.

🌅 Starting a session

CommandWhat it does
💡hforge nextRecommends the single most useful action right now
🏥hforge doctorFull health check with evidence
🔄hforge refreshRegenerate runtime after code changes
📋hforge statusReview what's installed

🔄 While working

CommandWhat it does
📊hforge dashboardOpen the real-time browser dashboard
📈hforge scoreShow recent session effectiveness scores
🧠hforge insightsBrowse learned patterns with confidence
⚡hforge adaptView/manage auto-tunings
🔍hforge traceView recent session traces
🔄hforge loopLiving Loop health summary

📤 Sharing & maintenance

CommandWhat it does
📦hforge export --bundle team.hfbExport tuned harness as portable bundle
📥hforge import team.hfbBootstrap from a shared bundle
🔧hforge updateUpdate harness to latest version in place
🔬hforge auditVerify install integrity
🔎hforge diff-installCheck what drifted since last install
🧹hforge pruneClean up unused artifacts

🧬 Advanced

CommandWhat it does
🗺️hforge cartographMap repo structure and boundaries
🔍hforge recommendEvidence-backed setup recommendations
🧬hforge recursive plan "..."Structured recursive analysis for hard problems
🎯hforge target compare codex claude-codeSide-by-side target comparison

💡 Real-World Scenarios

<table> <tr> <td width="50%">

📂 "Just cloned a repo, want AI help"

cd my-project
npx @harness-forge/cli
# Done — AI assistant understands this project
</td> <td width="50%">

🤝 "I use both Codex and Claude Code"

hforge init --agent codex --agent claude-code --yes
hforge target compare codex claude-code

Both agents share .hforge/ but get their own config bridges.

</td> </tr> <tr> <td width="50%">

🔙 "Coming back to a project after a break"

hforge next
# Tells you: refresh runtime, review stale artifacts
</td> <td width="50%">

👥 "Standardize AI setup across my team"

hforge export --bundle our-team.hfb
# Teammate runs:
hforge import our-team.hfb
# Same learned patterns, instant bootstrap
</td> </tr> </table>

🎯 Supported Targets

<p align="center"> <img src="https://img.shields.io/badge/Codex-full_support-2ea44f?style=for-the-badge" alt="Codex" /> <img src="https://img.shields.io/badge/Claude_Code-full_support-6C3FC5?style=for-the-badge" alt="Claude Code" /> <img src="https://img.shields.io/badge/Cursor-partial-f97316?style=for-the-badge" alt="Cursor" /> <img src="https://img.shields.io/badge/OpenCode-partial-f97316?style=for-the-badge" alt="OpenCode" /> </p> <table> <tr> <td width="50%">
CodexClaude Code
Runtime✅ Full✅ Full
Maintenance✅ Full✅ Full
Hooks📄 Docs-driven✅ Native
Plugins📄 Manual✅ Native
Shared .hforge/✅ Yes✅ Yes
</td> <td width="50%">

Use both together — they share the same .hforge/ runtime.

hforge target compare codex claude-code
</td> </tr> </table>

📦 What's Included

<p align="center"> <img src="https://img.shields.io/badge/🌐_languages-14-0070f3?style=for-the-badge" alt="14 languages" /> <img src="https://img.shields.io/badge/🏗️_frameworks-12-2ea44f?style=for-the-badge" alt="12 frameworks" /> <img src="https://img.shields.io/badge/🛠️_skills-45+-f97316?style=for-the-badge" alt="45+ skills" /> </p> <details> <summary><strong>🌐 14 Language packs</strong></summary>

TypeScript, Python, Java, Go, Kotlin, Rust, C++, .NET, PHP, Perl, Swift, Shell, Lua, PowerShell

</details> <details> <summary><strong>🏗️ 12 Framework packs</strong></summary>

React, Next.js, Vite, Express, FastAPI, Django, ASP.NET Core, Spring Boot, Laravel, Symfony, Gin, Ktor

</details> <details> <summary><strong>🛠️ 45+ Skills</strong></summary>

Language engineering, workflow orchestration, operational helpers, and specialized skills like incident triage, dependency upgrades, API contract review, database migration review, release readiness, and token-budget-optimizer for context-aware compaction.

</details>

⚙️ How It Works Under the Hood

<details> <summary><strong>🗂️ What gets created in your repo</strong></summary> 
Your Repo
  │
  ├── AGENTS.md              ← AI agents read this first
  ├── .agents/skills/        ← Discoverable skills
  ├── .codex/ or .claude/    ← Target-specific config
  └── .hforge/               ← Hidden canonical runtime
         ├── library/        ← Skills, rules, knowledge packs
         ├── runtime/        ← State, indexes, traces, insights
         ├── generated/      ← Command catalog, launchers
         └── templates/      ← Workflow templates

Visible bridges where AI agents need discovery. Hidden canonical layer where runtime content stays authoritative.

</details>

❓ FAQ

<details> <summary><strong>Do I need to install anything globally?</strong></summary>

No. npx @harness-forge/cli runs directly. For the shorter hforge command, run hforge shell setup --yes once.

</details> <details> <summary><strong>Does it change my source code?</strong></summary>

Never. Harness Forge only creates its own files (AGENTS.md, .agents/, .hforge/, .codex/, .claude/). Your application code is untouched.

</details> <details> <summary><strong>Can I use it in CI/CD?</strong></summary>

Yes. Add --yes for non-interactive and --json for machine-readable output:

hforge init --root . --agent codex --setup-profile recommended --yes
hforge doctor --root . --json
</details> <details> <summary><strong>How do I remove it?</strong></summary>

Delete: .hforge/, .agents/, .codex/, .claude/, AGENTS.md. Your project is back to normal.

</details> <details> <summary><strong>Does it send data anywhere?</strong></summary>

No. Everything stays local under .hforge/. Nothing is ever sent to the internet. Inspect, delete, or back up anytime.

</details> <details> <summary><strong>What Node.js version?</strong></summary>

Node.js 22 or newer. Check with node --version.

</details>

📈 Project Activity

<p align="center"> <a href="https://star-history.com/#ldilov/harness-forge&Date"> <img src="https://api.star-history.com/svg?repos=ldilov/harness-forge&type=Date" alt="Star History Chart" width="700" /> </a> </p>

🤝 Contributing

See CONTRIBUTING.md for development setup and guidelines.

🙌 Acknowledgements

Harness Forge was inspired by github/spec-kit. Credit to the GitHub team for shaping cleaner workflow models.

📄 License

GPL-3.0 — see LICENSE.

<p align="center"> <strong>Your AI agent deserves a better harness.</strong> <br /> <code>npx @harness-forge/cli</code> </p>