{
  "markdown": "# HarnessScope\n\n<!-- mcp-name: io.github.moongioh/hscope -->\n\n[![PyPI](https://img.shields.io/pypi/v/hscope)](https://pypi.org/project/hscope/)\n[![npm](https://img.shields.io/npm/v/hscope)](https://www.npmjs.com/package/hscope)\n[![CI](https://github.com/moongioh/harness-scope/actions/workflows/harnesses.yml/badge.svg)](https://github.com/moongioh/harness-scope/actions/workflows/harnesses.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](#)\n\n**Turn-level governance observability for agent harnesses.** HarnessScope reads the transcripts\nyour agent harness already writes, judges every turn against your workspace's own operating rules\n(plan-before-code, verify-before-done, context budget, path boundaries, …), and serves a local\nviewer that shows *how* each session traversed that governance structure — passes included, not\njust violations.\n\n![HarnessScope — replay, circuit, rule health, token loss](docs/demo.gif)\n\n*Every frame above is `hscope demo`: a synthetic corpus, generated locally. Real transcripts\ncarry full prompt text and are never demo material.*\n\n---\n\n## What it found\n\nA session is not one model talking to itself — it spawns subagents, they run on models the parent\ndoes not, and a streamed response writes the same request several times. Read that structure\nnaively and the numbers are wrong. These are the corrections, each measured on this project's own\ntranscripts:\n\n| Read naively | Actually | Why |\n|---|---|---|\n| Re-read waste | **42% of it was false** | A subagent reading a file the parent read has not re-read anything — it never had those tokens. Waste is charged per context window (`agent_id`), not per session. |\n| 90,957,147 output tokens | **32,348,242** (2.8× overcount) | A streamed response writes several usage records per `requestId`. Count the *last* one — the early ones are partial (2, where the finished response says 31,979). |\n| 3,121 turns | **2,438** (28% inflation) | A turn is one user prompt (`promptId`). Interrupt notices, `<command-name>` echoes and `<bash-input>` blocks are user records too. |\n| A stable format | **29 harness versions in one month** | The transcript format is undocumented and it moves. So `hscope doctor` fails loudly and names the version that broke it, instead of emitting a wrong number quietly. |\n| The re-read waste that survived that | **81% of it was false too** | Keyed on `(context, path)`, *paging* a large file (`offset=501`) is indistinguishable from reading it twice — and each new chunk was charged as tokens the context already held. 692,292 of 854,334 tok. The key now carries the span. |\n\nThe last row is the one that matters most, and it is the youngest: it was found **after v0.1.3\nshipped**, by pointing the tool at its own workspace and reading the answer. The same class of\nmistake as row one, one layer further down, in code that had already passed its own tests. A tool\nthat claims to catch a governance failure had better survive being aimed at itself — so that is now\nthe standing use of it, and what it said next was worse.\n\nIt cost three rules their default. R1 (index-first), R2 (inline-first) and R6 (approval-gate) ask\n**semantic** questions — *is this a domain question? was this fan-out warranted? is this code under\nthat plan?* — and answered them with **syntactic** tests: a keyword in the prompt, the prompt's\ncharacter count, the project folder. Measured against real sessions, 84% of R2's violations were\nturns invoking a command whose entire job is to fan out. That is not a threshold in need of tuning;\na proxy that does not track the concept cannot be tuned into one. **They now ship disabled, each\ncarrying the false-positive rate it was measured at** (`precision`, a first-class field on the rule,\nsurfaced in the model, in `rule_health`, and as a hoverable badge). Off is not the point — *off, and\nhere is why, with the number* is the point. A rule silently shipped on is how a governance screen\nbecomes noise nobody trusts, which is the failure this project exists to name.\n\nR8 stopped reporting a compliance rate for the same reason. Its opportunities *are* its violations by\nconstruction — a re-read counter never observes a *compliant* re-read — so \"0% compliance\" was an\nidentity, not a finding: a number that reads like an indictment and says nothing. It reports its\nquantity now, and no ratio.\n\nThese are observations of **one corpus, not a benchmark** — your numbers will differ. The point is\nthat they are *readable at all*: metrics know quantities, a bill knows money, and neither knows the\nword \"subagent\". Full reasoning: [`docs/MULTI-AGENT.md`](docs/MULTI-AGENT.md).\n\n## How HarnessScope compares\n\nHarnessScope watches a different layer than most \"LLM observability\" tools: not the app you\ninstrumented, but the **agent harness itself**, read from its own transcripts.\n\n| Tool | Watches | How it gets data | Runs |\n|---|---|---|---|\n| **HarnessScope (`hscope`)** | Governance compliance + token flow of Claude Code sessions, turn by turn | Reads transcript JSONL — after the fact, or live as the harness appends it (`--watch`). Zero instrumentation, no hooks into the session | Local, no LLM inside |\n| `ccusage` and similar CLIs | Token/cost totals from the same transcripts | Reads transcript JSONL | Local |\n| LangSmith / Langfuse | Traces of LLM calls **your application** makes | SDK instrumentation you write | SaaS (Langfuse also self-host) |\n| Arize Phoenix (OpenInference) | OTel traces of LLM apps you instrument | OTel SDK instrumentation | Local / self-host |\n| Claude Code `/cost`, OTel metrics | The current session's spend; aggregate counters | In-harness | In-harness |\n\nThe row nobody else covers: *did the session follow the workspace's operating rules* —\nplan-before-code, verify-before-done, path boundaries, context budget. Cost tools tell you\nwhat a session spent; tracing tools tell you what your app's LLM calls did; HarnessScope\ntells you whether the agent worked the way your workspace says agents must work.\n\n## Try it — 30 seconds, none of your data\n\n```bash\npipx install hscope        # or: pip install hscope · npx -y hscope  (Python 3.11+ either way)\nhscope demo --serve        # synthetic corpus → ingest → judge → viewer\n```\n\nThree invented sessions: one compliant, one wasteful (re-reads, dead context, a boundary read, a\ncompletion declared with nothing verifying it), and one fan-out (two subagents — one cites what it\nread, one does not; one spawned in the background — plus an off-host MCP round trip).\n\nThe corpus is held to the same standard as real data: it must satisfy `hscope doctor`, so a\ngenerator writing a shape the parser does not expect gets caught by the invariants. It already\nearned that twice — a `requestId` reused across sessions (which hscope correctly read as one API\ncall replayed by a fork), and a padded `agentId:` that the parser's regex swallowed whole.\n\n## Then point it at your own sessions\n\n```bash\nhscope                     # scan ~/.claude/projects → ingest → judge → check → open the viewer\n```\n\nNo flags, no config file. Two things it will not get wrong:\n\n- **The port is found, not assumed.** 8000 is a reasonable default and on some Windows machines it\n  is a reserved range (WinError 10013). A first impression should not be a stack trace.\n- **It says that transcripts expire.** The harness deletes them after about 30 days, and **ingest\n  is what makes them permanent**. Ingest less often than that and you lose sessions silently — a\n  session never ingested is indistinguishable from one that never happened. The first run prints\n  how old your oldest transcript is and prescribes a cadence.\n\nIt also announces which rules it is about to judge with — neutral presets, or the workspace model\nit found on disk. Claiming \"presets\" while quietly applying a model would be the same lie as a\nsilent fallback.\n\nEverything is **local-first**: no transcript data leaves your machine (the one exception — the\nopt-in Tier B LLM judge — is off by default and fires only on an explicit per-session click). The\ntool never writes to your projects, your `.mcp.json` or your harness settings: *a tool that observes\ngovernance must not reshape the surface it observes.*\n\n## Watch it live — and *only* watch\n\n```bash\nhscope --watch             # the circuit stays live: sessions are re-ingested and re-judged as they run\n```\n\nThe harness appends to the transcript while the session is still going, so the data for a live view\nwas always there — what was missing was the loop. `--watch` scans mtimes every 2s, hashes only the\nfiles that moved (mtime is the trigger; the hash is still the decision), re-judges only those\nsessions, and the viewer refreshes itself. A tick where nothing moved parses nothing, hashes nothing\nand prints nothing.\n\n**It observes; it does not intervene.** No hook is installed in your session, nothing is blocked,\nand a violation on screen is one *a human* has to act on. Blocking would mean a `PreToolUse` hook —\nwhich would make the \"no hooks into the session\" row above false, bind the tool to one harness, and\nlet a wrong verdict stop your work (post-hoc, a bad call is a bad badge; live, it is a stopped\nhand). Seeing a re-read loop or a fan-out at 5k tokens instead of 40k is worth having; it does not\nrequire the tool to hold the brake.\n\n**The turn that is still running is shown, not judged.** Judging it would break hscope's own rules:\na verification-gate rule would fire on the very turn that is *about* to run the check — a verdict\noverturned three seconds later — and a streamed response's token usage is not final until its last\nrecord lands. So the live turn wears an *in flight · not judged* badge and its verdict appears when\nthe turn ends. A verdict deferred must not become a verdict skipped: if you interrupt that turn the\nfile simply goes quiet, and hscope judges it once its liveness window lapses rather than leaving it\nwithheld forever.\n\n## What you get\n\n### Harness Circuit\n![Harness Circuit](docs/img/circuit.png)\n\nOne turn as a fixed-topology schematic: context sources → agent → action surfaces → governance\noutputs. Subagents are nodes with a spawn edge *and* a return edge — labelled with what came\n**back**, which is not what the subagent **spent** (one real turn: three agents burned 16.5k / 6.3k\n/ 5.3k output tokens and handed the parent 1.5k / 2.2k / 2.0k). Off-host MCP hops and write-capable\nservers are flagged on the wire.\n\n### Session Replay\n![Session Replay](docs/img/replay.png)\n\nThe turn timeline: what was loaded into context, which tools ran, and the rule verdict on each turn\n— passes included. A governance view that only lists violations cannot tell \"compliant\" from\n\"never checked\".\n\n### Rule Health\n![Rule Health](docs/img/health.png)\n\nCompliance × coverage, per rule. A rule at 100% compliance over 3 evaluable turns is not the same\nas one at 100% over 300, and a rule nothing can evaluate is reported as such rather than scored.\n\n### Token / Loop\n![Token and loss](docs/img/loop.png)\n\nPer-turn token burn with loss pinpoint markers — re-reads, dead context (loaded, never cited),\nerror churn, cache-window waste — attributed to the turn and the context window that actually paid.\n\n### Setup\n\nEvery hook, MCP server, skill and subagent you registered, next to what your transcripts show was\nactually called: `active` / `unused` / `unregistered-call`. Registration is a claim; the transcript\nis the evidence. (No screenshot here on purpose — this screen reads *your* machine's configuration,\nso any capture of it would be a picture of someone's real workspace.)\n\n## Rules you did not have to write\n\nNobody should hand-write rules to try a tool. When the first run finds no workspace model, it seeds\none from your repo's structure and leaves a page for the LLM you already have:\n\n```bash\nhscope                   # ...with no rules of your own, writes ~/.hscope/<id>/HSCOPE-SETUP.md\nhscope mcp --install     # prints an MCP snippet; paste it into .mcp.json\nhscope setup             # regenerate the page whenever your canon moves\n```\n\n`HSCOPE-SETUP.md` has two readers. For you: the canon, hooks, MCP servers, skills and subagents\nhscope found, and the canon clauses no rule cites yet. For your LLM: instructions to call\n`get_setup_guide` → `suggest_rules` → `set_rule` and write those rules. **You approve; it drafts.**\n\nThe whole journey is **three manual actions** — run `hscope`, paste the snippet, hand over the page.\nThe snippet carries `HSCOPE_MCP_WRITE=1`, so pasting it *is* the write consent; there is no second\nstep. And hscope never edits `.mcp.json` itself.\n\n## Did the onboarding actually work?\n\n```bash\nhscope onboard      # read-only, idempotent; exit 1 while incomplete\n```\n\nSix observed stages and a verdict. `hscope` prints it at the end of every run, so you meet it\nwithout knowing the command exists.\n\n```\n1  transcripts ingested             PASS   297 session(s), oldest 35d\n       -> oldest is 35d and the harness deletes transcripts at ~30d -- ingest more often\n2  hscope MCP registered            FAIL   not in your harness config\n       -> run `hscope mcp --install` and paste the snippet it prints\n3  workspace model exists           PASS   ~/.hscope/warp/workspace-model.json\n4  the model governs your sessions  PASS   289 of 297 session(s)\n5  the model is not empty           PASS   14 rule(s), 25 role(s)\n6  your rules actually fire         PASS   10 of 10 enabled rule(s) had an opportunity\n\ndisabled, so not judged at all: R1, R2, R6, B1\n\nINCOMPLETE -- next: step 2, hscope MCP registered\n```\n\nFour of those are a checklist. **Two of them fail silently, and they are why the command exists:**\n\n- **Step 4 — the model governs *your* sessions.** A model can sit on disk while its\n  `workspace.roots` claim none of the paths you actually work in. hscope then judges with the\n  neutral presets, and until this gate it said nothing about it — so you would read your own rule\n  names on a screen that never applied one. It now prints the cwds your sessions really ran in.\n- **Step 6 — your rules actually fire.** Twelve rules an LLM wrote for you that never get an\n  opportunity on your corpus are not an onboarding; they are a green check over nothing. Rules with\n  zero opportunities are **named**. A rule that is merely *disabled* is reported as off, not dead —\n  those are different facts and conflating them is the kind of lie this tool exists to catch.\n\nA dead rule is a finding, not a failure: coverage of zero can honestly mean \"no chance yet\", and\nfailing the gate on it would reward writing fewer rules. But if *nothing* you wrote ever fired,\nthe gate says INCOMPLETE — that is a vacuous pass, and `hscope doctor` already refuses to report one\nof those about your transcripts. This is the same refusal, pointed at your setup.\n\n## The workspace model (optional but recommended)\n\nWithout a model, HarnessScope runs on **neutral presets**: generic rules with empty domain values,\npath labels fall back to file names, sessions render as a flat list. Crash-free in any repo — that's\nthe de-domaining contract.\n\nWith a model (`~/.hscope/<workspace>/workspace-model.json`) you declare, in one JSON document, how\n*your* workspace is governed:\n\n- `rules[]` — archetype instances with your params (keywords, thresholds, markers)\n- `roles[]` — what each path / MCP server / subagent *means* (label, circuit node, host boundary)\n- `gates[]` — your governance pipeline (e.g. context-load → plan-approval → implement → verify → ledger)\n- `unmeasurable[]` — canon clauses no detector can check (surfaced honestly instead of faked)\n- `work_items` — optional grouping above sessions (this workspace: `plans/**` with a status\n  frontmatter; other repos can map issues/PRs into the same slot). Absent ⇒ flat sessions.\n\nSchema and a neutral example live in `hscope/schema/`. Validate yours:\n\n```bash\npython -m hscope.schema.validate_model ~/.hscope/<workspace>/workspace-model.json\n```\n\n## MCP surface\n\nAny MCP client can read what HarnessScope observed — and the loop closes: an agent opens a session\nby reading how the last one scored, instead of re-earning the finding.\n\n```jsonc\n// .mcp.json\n{ \"mcpServers\": { \"harness-scope\": {\n    \"command\": \"python\", \"args\": [\"-m\", \"hscope.cli\", \"mcp\", \"--db\", \"/path/to/harness_scope.db\"] } } }\n```\n\n| Tool | |\n|---|---|\n| `list_sessions` · `session_report` · `token_hotspots` · `rule_health` | the viewer's numbers |\n| `get_workspace_model` | how this repo is governed, as one document |\n| `get_setup_guide` · `suggest_roles` · `suggest_rules` | evidence for authoring rules |\n| `set_role` · `set_rule` | write them back |\n\n**No model runs inside this server.** The client *is* the model: `get_setup_guide` hands it the\nclosed archetype library and each archetype's param schema, `suggest_rules` hands it the canon\nclauses no rule cites, and the judgment comes back through `set_rule` — where the params are\nvalidated against that archetype's schema before anything is written. So the MCP path needs no\nprovider, no credential and no off-host consent. `hscope compile` does the same job in one batch\nLLM call; this is its conversational, incremental counterpart.\n\nWrites are **off by default** (`HSCOPE_MCP_WRITE=1`) and can only ever touch\n`~/.hscope/<workspace>/workspace-model.json`. There is no tool that writes a project file or steers\nanother agent — HarnessScope observes and judges; it does not drive.\n\n## Docs\n\n| | |\n|---|---|\n| [`MULTI-AGENT.md`](docs/MULTI-AGENT.md) | Why a session is not one model talking to itself — and every number in *What it found* |\n| [`DOCTOR.md`](docs/DOCTOR.md) | `hscope doctor`: nine invariants, and the two things it refuses to do |\n| [`FAILURE-MODES.md`](docs/FAILURE-MODES.md) | Graceful degradation — what happens when a transcript, DB or model is wrong |\n| [`VERIFICATION.md`](docs/VERIFICATION.md) | The verification harnesses (Definition of Done); CI runs them on 3 OSes |\n| [`CONFIG.md`](docs/CONFIG.md) | Environment variables · the opt-in Tier B judge |\n| [`RUN-FROM-SOURCE.md`](docs/RUN-FROM-SOURCE.md) | Contributors: requirements, the pipeline stage by stage, repo layout |\n\n## FAQ\n\n**What is HarnessScope?**\nA local-first observability tool for Claude Code: it parses your transcript JSONL files into\nSQLite, judges every turn against your workspace's own operating rules, and serves a web viewer\nshowing how each session traversed that governance structure. Install with `pip install hscope`\n(or `npx -y hscope`).\n\n**Does my transcript data leave my machine?**\nNo. Parsing, rule evaluation and the viewer are all local; the server binds `127.0.0.1`. The one\nexception is the opt-in Tier B LLM judge, which is off by default and sends a single per-session\ndigest only when you click that session's judge button.\n\n**Do I need an API key or an LLM to run it?**\nNo. There is no model inside HarnessScope — the rule engine is deterministic. An LLM only enters\nthe picture where you bring your own: the optional Tier B judge, or your coding agent authoring\nrules over the MCP surface.\n\n**How is this different from ccusage, LangSmith, or Phoenix?**\nDifferent layer (see the comparison table above). Cost CLIs total what a session spent; tracing\nplatforms instrument *your application's* LLM calls. HarnessScope reads the *harness's* own\ntranscripts and judges governance: whether sessions planned before coding, verified before\nclaiming done, stayed inside path boundaries, and where their tokens actually died.\n\n**Can my agent read the results?**\nYes — that is the point of the MCP surface. Any MCP client gets `session_report`,\n`token_hotspots`, `rule_health` and the workspace model, so the next session opens by reading\nhow the last one scored instead of re-earning the finding.\n\n**What happens when Claude Code changes its transcript format?**\n`hscope doctor` fails loudly, naming the harness version that broke an invariant, instead of\nquietly emitting a wrong number. This corpus alone declares 29 harness versions in one month;\ndrift is detected, not tuned away.\n\n**Which platforms does it run on?**\nWindows, macOS and Linux — the CI matrix runs the verification harnesses on all three.\nPython 3.10+ (3.11+ recommended).\n\n## Data & privacy\n\n- The SQLite DB contains **full prompt text** from your transcripts. It is gitignored (`*.db`) and\n  must stay local — never commit or upload it.\n- The server binds `127.0.0.1` by default and is read-only over the DB.\n- Tier B (LLM judge) sends a per-session digest off-host **only** when you click the judge button\n  for that session; the rule (`B1`) ships disabled.\n\n## License & open-core boundary\n\nHarnessScope is **Apache-2.0 open core**. Everything an individual user touches is free forever,\nwith no feature limits — paid tiers (if/when they exist) only ever add things an *organization*\nneeds, never remove things from individuals:\n\n| Layer | Free (Apache-2.0 core) | Enterprise (`ee/`, future) |\n|---|---|---|\n| Capture | Transcript ingestion + hooks | MCP gateway (cross-harness capture) |\n| Analysis | Rule engine · circuit · token loss · coverage — all of it | Multi-user aggregation, org dashboards |\n| Security | Local security-flow rules (self-audit) | Org compliance reports, audit logs |\n| Accounts | Local, single user | SSO / RBAC |\n\nSee [`LICENSE`](LICENSE) (Apache-2.0), [`ee/README.md`](ee/README.md) (boundary), and\n[`CONTRIBUTING.md`](CONTRIBUTING.md) (DCO).\n",
  "bytes": 21404,
  "sha": "e4042b2d4e2cec916a391c50a07670f4b4f6790d2ebfe4f10855f15ed0eeb0b6",
  "repo_slug": "moongioh/harness-scope",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_moongioh_hscope_a98d9915/readme"
}