π¨ Harness Forge
Your AI coding agent is only as good as its harness.
One command to scan, equip, and continuously improve any AI coding agent in your repository.
π Get Started •
π Living Loop •
π‘οΈ Sentinel (preview) •
π· Double Diamond •
π Dashboard •
π§ Decisions •
β¨οΈ Commands •
π‘ Scenarios •
π― Targets •
β FAQ
---
|
### π Scans & Equips
Your AI agent gets your repo's languages,
frameworks, and patterns **from the first prompt**
|
### π Self-Improves
A closed feedback loop **learns** what works,
**tunes** itself, and gets smarter every session
|
### π Full Visibility
Real-time dashboard shows every decision,
token spend, and compaction β **no black boxes**
|
| | Without Harness Forge | With Harness Forge |
|---|---|---|
| π§ **Context** | Agent guesses at project structure | Agent knows your languages, frameworks, boundaries |
| β‘ **Performance** | Starts fresh every session | Self-improves over time via the Living Loop |
| π **Visibility** | Black box β no idea what the agent decided | Real-time dashboard with 20 live panels |
| π§ **Decisions** | ADRs get buried or forgotten | Chronological decision timeline with stale-decision checks |
| 𧩠**Complex tasks** | Agent wanders or over-delegates without clear thresholds | Automatic complex-task protocol keeps simple work light, bounds sidecars, verifies results, and captures durable learning |
| π° **Cost** | Wasted tokens on retries and wrong paths | Compaction + auto-tuning saves 20-40% |
| π€ **Portability** | Stuck on one machine, one setup | Export & import learned patterns as `.hfb` bundles |
---
## π The Living Loop β Your Harness Gets Smarter
> Most tools configure once and forget. Harness Forge **keeps learning.**
```
ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ
β π β β π§ β β β‘ β β π€ β β π₯ β
β OBSERVE βββββΆβ LEARN βββββΆβ ADAPT βββββΆβ SHARE βββββΆβ IMPORT β
β β β β β β β β β β
β Tracks β β Finds β β Auto- β β Export β β Bootstrapβ
β sessions β β patterns β β tunes β β bundles β β anywhere β
ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ
β² β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
|
#### π
Day 1 β You install
```bash
npx @harness-forge/cli
```
Scans your repo. Installs skills, rules, knowledge packs.
Default settings. Everything works out of the box.
|
#### π
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
```
|
|
#### π
Day 5 β Share with your team
```bash
hforge export --bundle my-team.hfb
# Send to a teammate β
hforge import my-team.hfb
# They get your learned patterns instantly
```
|
#### π
Ongoing β Dashboard shows it all
```bash
hforge dashboard
```
Loop health ring, effectiveness scores,
pattern list, tuning log β live in your browser.
|
> **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.
π‘οΈ Guardrails β auto-tuning is safe
- 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
---
## π Real-Time Dashboard
> `hforge dashboard` β see everything, live in your browser.
|
#### π Loop Ring
Live status of each loop
stage with health score
|
#### π Effectiveness
Session score trend β
are things getting better?
|
#### π§ Insights
Discovered patterns with
confidence bars
|
#### β‘ Tuning Log
Policy changes with
one-click revert
|
π All 20 dashboard panels
| Panel | What it shows |
|-------|-------------|
| π’ **KPI Cards** | Total events, tokens, enforcement level, budget gauge |
| π **Event Timeline** | Scatter plot of all events over time, color-coded by category |
| πΎ **Memory Pressure** | Token usage line chart with threshold marklines |
| π **Budget Breakdown** | Donut chart of budget allocation (hot-path, output, tools, safety) |
| π **Live Event Feed** | Searchable, expandable table of every harness decision |
| π€ **Subagent Briefs** | Delegated tasks, their context, and outcomes |
| π **Brief Metrics** | Subagent activity summary and success rates |
| π **Suppression Gauge** | How many duplicate context items were removed |
| πͺ **Expansion Gate** | History access requests β granted vs denied |
| βοΈ **Config Editor** | Edit memory-policy, context-budget, load-order live |
| π **Loop Health Ring** | Self-improvement cycle status with stage counts |
| π **Effectiveness Trend** | Session score sparkline (last 20 sessions) |
| π§ **Insights Panel** | Discovered patterns with confidence and "NEW" badges |
| β‘ **Tuning Log** | Policy changes with before/after and revert button |
| π **Event Distribution** | Bar chart of top event types |
| β±οΈ **Event Rate** | Events per minute over time |
| πΊοΈ **Event Heatmap** | Category Γ time heatmap |
| π° **Tokens Saved** | Running counter of tokens saved by compaction |
| π **Profile Distribution** | Output profile selection breakdown |
| βΉοΈ **Session Info** | Session ID, uptime, version, connection status |
> π **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.
---
## π‘οΈ Sentinel β always-on watcher (preview)
> Sentinel watches your project for you. It notices when key files change, when the build is wrong, or when an AI agent gets stuck β and writes it down. It never spends AI tokens on its own (default daily budget is **0**), and it never changes anything without your approval.
```
ββββββββββββ ββββββββββββββββ ββββββββββββ ββββββββββββββββ ββββββββββββ
β ποΈ WATCH ββββΆβ π OBSERVE ββββΆβ π¦ SIGNAL ββββΆβ β APPROVE ββββΆβ π§ ACT β
β drift / β β dedup + log β β classify β β authority β β sandbox β
β deps / β β by severity β β + route β β A0..A5 chain β β worktree β
β ADR mons β β β β β β + denylist β β +rollbackβ
ββββββββββββ ββββββββββββββββ ββββββββββββ ββββββββββββββββ ββββββββββββ
β² β
βββββββββββββββ side-effect ledger Β· panic-stop βββββββββββββββββββββ
```
|
### ποΈ Watches deterministically
Repo / dependency / ADR-drift monitors β
**0 LLM tokens** by default, fully offline
|
### β Never acts unasked
Tamper-evident SHA-256 approval chain,
denied paths & commands, instant panic-stop
|
### π§ Reversible by design
Approved actions run in isolated git
worktrees with a full side-effect ledger
|
```bash
hforge monitor init-defaults # one-time setup
hforge monitor once # run all watchers one tick
hforge observe # see what changed
hforge monitor status # check the cost meter
```
π What you get today (early preview) β full capability checklist
- β
**Repo Drift Monitor** β flags when `package.json`, lockfile, `tsconfig.json`, or your harness manifest change
- β
**Deduplicated observations** β no duplicate noise across runs
- β
**Hard cost ceiling** β `cadence.yaml` and `budget.yaml` cap how often watchers run and how much they may spend
- β
**Per-hour run cap enforced** β `maxMonitorRunsPerHour` blocks new ticks once exhausted
- β
**Severity rules in YAML** β each watcher maps `default` plus named rules (e.g. `manifest_changed: warning`)
- β
**Concurrent-safe** β in-process mutex protects hot files (`fingerprints.json`, ledgers)
- β
**Hardened PID file** β structured `{pid, startedAt, hostname, workspaceRoot}`, foreign-host detection, stale-PID recovery
- β
**Panic stop** β set `panicStop: true` and Sentinel halts immediately
- β
**Signal correlation** β `hforge signals` groups observations into prioritized signals with category routing (`maintenance`, `agent-health`, `regression`, etc.)
- β
**Suppression + resolution** β `hforge signals suppress --until 7d`, `--forever`, `resolve`
- β
**Action queue** β `hforge actions` shows proposed plans with risk + verification + rollback declared
- β
**First action template** β `refresh-harness-runtime` (drift signal β `hforge refresh` action plan)
- β
**Full autonomy CLI** β `hforge autonomy status | policy | explain | set-profile | set-level | panic-stop`
- β
**5 profiles** (observe β cautious β assisted β active β maintainer) with per-profile approval requirements
- β
**Tamper-evident approval chain** β `hforge actions approve --authority A3 --expires 2h` writes a SHA-256-chained record; tamper detected on next read
- β
**Denied paths + denied commands** enforced in the policy gate (defaults block `.env`, `**/secrets/**`, `npm publish`, `git push --force`, β¦)
- β
**Approved actions actually execute** in an isolated git worktree at `.hforge/runtime/actions/runs//worktree/`
- β
**Cross-platform safe executor** β `child_process.spawn({shell: false})`, AbortController timeouts, POSIX process-group + Windows `taskkill /F /T` killtree
- β
**Sandboxed env** β `HOME`/`USERPROFILE` redirected, only PATH + small allowlist passed through; secrets never leak
- β
**Verification** β 4 of 5 check types (`command`, `file_exists`, `no_diff_outside`, `schema_valid`); `agent_review` correctly skipped while LLM budget=0
- β
**Side-effect ledger** + **`actions diff/logs/rollback`** for forensic review and reversal
- β
**`actions rollback delete_worktree`** removes the worktree and flips status to `reverted`
- β
**World monitor** β `hforge world watch add npm:` / `runtime:nodejs:lts` + `hforge world sync` fetches real npm + Node.js Release schedule with ETag caching
- β
**Relevance scoring** against `package.json` drops events for unused packages and downgrades borderline ones to `info`
- β
**Network policy** baked in (`none` / `package-registry-only` / `github-only` / `allowlist`) β no surprise outbound calls
- β
**Long-running daemon** β `hforge monitor run` schedules each watcher on its own interval with jitter, polls panic-stop, exits cleanly on Ctrl+C / `hforge monitor stop`
- β
**Crash-recovery checkpoint** β orphan runs from a killed daemon get flipped to `failed` on the next boot
- β
**Panic-stop broadcast** β `autonomy panic-stop on` halts the daemon AND aborts every in-flight executor within one tick
- β
**Dashboard panels (8 of 8)** β `hforge dashboard` now serves the full Sentinel section: Status, World Feed, Signals, Approval Inbox, Action Queue, Verification Results, Autonomy Posture, Agent Watchdog, Side-Effect Ledger β backed by REST endpoints with a 5s page-visibility-gated React poll
- β
**Watchdog primitives** β intervention ladder (`observe β warn β constrain β pause β require_approval β terminate β rollback`), `hforge watchdog status / events / pause / resume / explain` CLI, persisted intervention ledger
- β
**`validate:sentinel` runtime gate** wired into `validate:runtime-gates` (now 7 gates) β Zod-validates default monitor + policy YAMLs and scans for inline comments across all sentinel paths
- β
**Dependency Risk Monitor** β flags deprecated direct/indirect dependencies and major-version-available upgrades; reads `package.json` + `node_modules` + the world-monitor cache, fully offline
- β
**ADR Drift Monitor** β walks `docs/adrs/`, `docs/adr/`, and `.hforge/runtime/decisions/`; emits a signal when an ADR references files that no longer exist, escalates to warning when 3+ refs are broken
- β
**300 unit + integration tests** including full daemon lifecycle, watchdog state machine, validate-sentinel gate, and both new monitors
- π§ **Coming next**: agent step types (`invoke_agent`, `write_file`, `apply_patch`, `open_pr`), GitHub releases + advisories adapter, CI Failure Monitor (needs the GitHub adapter), click-to-approve UI
π **New here?** Read [docs/sentinel/README.md](docs/sentinel/README.md) and [docs/sentinel/getting-started.md](docs/sentinel/getting-started.md) β both written in plain English with no jargon.
---
## π· Double Diamond β feature & bug workflows
> Most agents code the **first idea they have**. Double Diamond makes your agent *explore the problem before committing* and *compare options before delivering* β with just enough structure, never ceremony.
```
DISCOVER DEVELOP
β β
β± β² β± β²
β± β² defined β± β² shipped
βββββββΆ βββββββββββββββββββΆ ββββββββΆ
request β² β± problem β² β± change
β² β± β² β±
β β
DEFINE DELIVER
βββββ PROBLEM SPACE ββββ ββββ SOLUTION SPACE ββββ
diverge β converge diverge β converge
```
|
#### π· `/hforge-double-diamond`
For **meaningful feature work**. Discover evidence β
Define the smallest correct problem β Develop **β₯2 options**
β Deliver with validation, acceptance mapping & rollback.
Auto-reframes to the bug flow if the task is really a defect.
|
#### π `/hforge-bug-diamond`
For **defects, regressions, flaky tests, incidents**.
Triage & contain β reproduce β ranked hypothesis table β
smallest confirmed fix β verify β prevent recurrence.
**No root-cause claims without evidence.**
|
> **Lite** keeps small changes one-liner-light Β· **Standard** is the default for real features Β· **Deep** adds option matrices and human checkpoints for risky, ambiguous, or architecture-significant work. Host-agnostic and honest about parity: native slash skill in Claude Code, `/skills` or `$skill` in Codex β no overstated capabilities.
---
## π§ Decision Timeline
> `hforge review --root . --json` β see what your team decided, when it changed, and what needs attention.
AI work moves fast. The hard part is remembering **why** the team chose a path
three weeks later. Harness Forge now turns ASR and ADR records into a simple
timeline:
|
#### π What happened?
Decisions are sorted by creation time,
so the newest architecture choices are easy to find.
|
#### π What changed?
Superseded ADRs point to the newer decision,
so old notes do not fight new direction.
|
#### π¦ What needs review?
Stale proposals, broken links, and missing
decision coverage show up in review output.
|
```bash
# Review decision health, lineage, and architecture coverage
hforge review --root . --json
# Generate a readable decision log for handoff or onboarding
hforge runtime decision-log --root . --json
```
In plain words: if a task is architecture-significant, Harness Forge helps the
team answer:
- **Do we have a decision for this?**
- **Is it still current?**
- **Did another ADR replace it?**
- **Are we shipping with an uncovered architecture change?**
That makes ADRs useful day to day, not just documents people write once and
forget.
---
## π Get Started in 60 Seconds
|
```bash
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:
```bash
npx @harness-forge/cli shell setup --yes
```
|
**One-liner for CI / scripts:**
```bash
hforge init \
--root . \
--agent codex \
--agent claude-code \
--setup-profile recommended \
--yes
```
**Verify everything is healthy:**
```bash
hforge doctor --root . --json
```
|
---
## β¨οΈ Your Daily Workflow
> Commands organized by **when** you use them β not alphabetically.
### π
Starting a session
| | Command | What it does |
|---|---|---|
| π§ | `/hforge-init` | Ask the agent to read the compact Harness Forge brief and orient itself |
| π‘ | `hforge next` | Recommends the single most useful action right now |
| π₯ | `hforge doctor` | Full health check with evidence |
| π | `hforge refresh` | Regenerate runtime after code changes |
| π | `hforge status` | Review what's installed |
### π While working
| | Command | What it does |
|---|---|---|
| π | `hforge dashboard` | Open the real-time browser dashboard |
| π§ | `hforge review --root . --json` | Check decision health, lineage, and coverage |
| π | `hforge runtime decision-log --root . --json` | Generate a readable decision timeline |
| π | `hforge score` | Show recent session effectiveness scores |
| π§ | `hforge insights` | Browse learned patterns with confidence |
| β‘ | `hforge adapt` | View/manage auto-tunings |
| π | `hforge trace` | View recent session traces |
| π | `hforge loop` | Living Loop health summary |
### π€ Sharing & maintenance
| | Command | What it does |
|---|---|---|
| π¦ | `hforge export --bundle team.hfb` | Export tuned harness as portable bundle |
| π₯ | `hforge import team.hfb` | Bootstrap from a shared bundle |
| π§ | `hforge update` | Update harness to latest version in place |
| π¬ | `hforge audit` | Verify install integrity |
| π | `hforge diff-install` | Check what drifted since last install |
| π§Ή | `hforge prune` | Clean up unused artifacts |
### 𧬠Advanced
| | Command | What it does |
|---|---|---|
| πΊοΈ | `hforge cartograph` | Map repo structure and boundaries |
| π | `hforge recommend` | Evidence-backed setup recommendations |
| 𧬠| `hforge recursive plan "..."` | Structured recursive analysis for hard problems |
| π― | `hforge target compare codex claude-code` | Side-by-side target comparison |
---
## π‘ Real-World Scenarios
|
#### π "Just cloned a repo, want AI help"
```bash
cd my-project
npx @harness-forge/cli
# Done β AI assistant understands this project
```
|
#### π€ "I use both Codex and Claude Code"
```bash
hforge init --agent codex --agent claude-code --yes
hforge target compare codex claude-code
```
Both agents share `.hforge/` but get their own config bridges.
|
|
#### π "Coming back to a project after a break"
```bash
hforge next
# Tells you: refresh runtime, review stale artifacts
```
|
#### π₯ "Standardize AI setup across my team"
```bash
hforge export --bundle our-team.hfb
# Teammate runs:
hforge import our-team.hfb
# Same learned patterns, instant bootstrap
```
|
---
## π― Supported Targets
|
| | Codex | Claude Code |
|---|---|---|
| Runtime | β
Full | β
Full |
| Maintenance | β
Full | β
Full |
| Hooks | π Docs-driven | β
Native |
| Plugins | π Manual | β
Native |
| Shared `.hforge/` | β
Yes | β
Yes |
|
**Use both together** β they share the same `.hforge/` runtime.
```bash
hforge target compare codex claude-code
```
|
---
## π¦ What's Included
π 14 Language packs
TypeScript, Python, Java, Go, Kotlin, Rust, C++, .NET, PHP, Perl, Swift, Shell, Lua, PowerShell
ποΈ 12 Framework packs
React, Next.js, Vite, Express, FastAPI, Django, ASP.NET Core, Spring Boot, Laravel, Symfony, Gin, Ktor
π οΈ 45+ Skills
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.
---
## βοΈ How It Works Under the Hood
ποΈ What gets created in your repo
```
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.
---
## β FAQ
Do I need to install anything globally?
No. `npx @harness-forge/cli` runs directly. For the shorter `hforge` command, run `hforge shell setup --yes` once.
Does it change my source code?
Never. Harness Forge only creates its own files (`AGENTS.md`, `.agents/`, `.hforge/`, `.codex/`, `.claude/`). Your application code is untouched.
Can I use it in CI/CD?
Yes. Add `--yes` for non-interactive and `--json` for machine-readable output:
```bash
hforge init --root . --agent codex --setup-profile recommended --yes
hforge doctor --root . --json
```
How do I remove it?
Delete: `.hforge/`, `.agents/`, `.codex/`, `.claude/`, `AGENTS.md`. Your project is back to normal.
Does it send data anywhere?
No. Everything stays local under `.hforge/`. Nothing is ever sent to the internet. Inspect, delete, or back up anytime.
What Node.js version?
Node.js 22 or newer. Check with `node --version`.
---
## π Project Activity
---
## π€ Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
## π Acknowledgements
Harness Forge was inspired by [github/spec-kit](https://github.com/github/spec-kit). Credit to the GitHub team for shaping cleaner workflow models.
## π License
GPL-3.0 β see [LICENSE](./LICENSE).
---
Your AI agent deserves a better harness.
npx @harness-forge/cli