agentwrangler 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and its Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submit" means any form of electronic, verbal, or
+      written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of submitting and
+      discussing improvements to the Work, but excluding communication that is
+      conspicuously marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent contributions
+      Licensable by such Contributor that are necessarily infringed by
+      their Contribution(s) alone or by the combined work (in which
+      their Contribution(s) were combined with the Work). If You institute
+      patent litigation against any entity (including a cross-claim or
+      counterclaim in a lawsuit) alleging that the Work or any patent
+      applicable to the Work (the "Work") constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your own modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Derivative
+      Works, and to permit persons to whom the Derivative Works is
+      furnished to do so, subject to the following conditions:
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      NONINFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+      You are solely responsible for determining the appropriateness of
+      using or reproducing the Work and assume any risks associated with
+      Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (even if such Contributor has been advised of the possibility
+      of such damages).
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations on
+      conditions that are not contradictory to and consistent with this
+      License, and you must indemnify each Contributor for any claim
+      asserted against such Contributor by reason of your accepting any
+      such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format please see the license. The
+      text should be enclosed in the appropriate comment syntax for the
+      file format please see the license.
+
+   Copyright 2026 AgentWrangler contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,116 @@
+# AgentWrangler
+
+Local-first observability for Claude Code that **joins your token spend to the pull requests it
+actually merged or closed** — entirely on your machine — and ships **installable guardrails** (a
+dangerous-command block, a pre-compaction checkpoint, a context-budget warning) you turn on from the
+dashboard. See where your agent budget goes, whether the work shipped, and cut the waste.
+
+## Local-only — your data never leaves your machine
+
+AgentWrangler runs entirely on your computer: a daemon bound to **`127.0.0.1`** and a dashboard in
+your browser that talks only to that loopback address. **No cloud backend, no telemetry, nothing
+phones home.** It reads your local Claude Code transcripts, stores only aggregates in a local SQLite
+file (`~/.agentwrangler/db.sqlite`), and never persists raw transcript or PR content — only counts,
+ids, and structural anchors (the SEC-101 privacy invariant). An optional GitHub token, used only for
+the outcomes feature, is read locally, never logged, and never leaves your machine.
+
+**Privacy exception (opt-in):** `npm run evidence:judge-g2 -- --execute` is the only path where PR
+content leaves the machine. It calls the Claude API with your local Claude Code OAuth credential to
+adjudicate G2 deferral findings, and runs only when `g2_claude_judge_opt_in` is enabled; otherwise it
+refuses to run. No rationale text is persisted.
+
+![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
+
+<!--
+  Captured from a SANITIZED instance (Vite test-mode fixtures — anonymized names, no
+  live data) so no real workspace/repository names/paths are committed (SEC-101).
+  Regenerate with the ce-demo-reel skill against `npx vite --mode test`.
+-->
+
+## Quick start
+
+Requirements: **Node `>=22 <25`** and npm.
+
+```sh
+git clone https://github.com/Doogit/AgentWrangler && cd AgentWrangler
+npm ci
+npm run build:ui       # build the dashboard
+npm run daemon         # starts the daemon and opens your browser
+```
+
+Then open **http://127.0.0.1:47821** (the daemon opens it for you unless `AW_NO_OPEN=1`).
+
+After installing dependencies you can also do it in one step:
+
+```sh
+npm ci                 # required first — the CLI runs via tsx, a devDependency
+npx agentwrangler      # builds the UI if needed, then launches the daemon + browser
+```
+
+On first launch the daemon binds the port immediately and serves a loading page, then scans your
+`~/.claude/projects/**/*.jsonl` transcripts in the background — the dashboard appears right away and
+fills in as the scan completes, so a large history won't block the page from opening.
+
+## Optional setup
+
+- **GitHub outcomes sync** — links sessions to the PRs/commits they produced. Provide a read-only
+  GitHub PAT via the `AW_GITHUB_TOKEN` environment variable (works on all platforms). On Windows you
+  may instead store it in Credential Manager as `AgentWrangler-GithubToken`. Without a token the
+  outcomes feature stays inert and Settings tells you so — nothing fails silently.
+- **Usage reader** — reads your Claude Code OAuth credentials locally to calibrate the weekly limit
+  and burn forecast. Sign in through Claude Code as usual; Settings shows the reader status.
+- **Context-budget hook** — an optional PreToolUse hook that warns before long sessions balloon.
+  Install it from the Settings page (or `npm run install-hook`).
+
+## Configuration (environment variables)
+
+All are optional; sensible defaults apply. See [`.env.example`](.env.example) for the full list.
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `AW_PORT` | Daemon HTTP port | `47821` |
+| `AW_DB_PATH` | SQLite database path | `~/.agentwrangler/db.sqlite` |
+| `AW_SCAN_ROOT` | Transcript corpus to scan | `~/.claude/projects` |
+| `AW_UI_ROOT` | Directory the built UI is served from | `<repo>/dist/ui` |
+| `AW_GITHUB_TOKEN` | Read-only GitHub PAT for outcomes sync | *(unset)* |
+| `AW_NO_OPEN` | Set to `1` to not auto-open the browser | *(unset)* |
+
+## What it measures
+
+AgentWrangler ingests your transcripts and surfaces cost trends, cache-efficiency, session hygiene
+findings (e.g. long sessions never `/clear`ed, limit-burn risk), and — with a GitHub token — outcome
+linkage between sessions and the work they shipped. Numbers are cap-weighted and honesty-tiered: the
+UI is explicit about what is measured versus estimated, and never invents a proxy it can't ground.
+Definitions live in [`docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md`](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md).
+
+## Limitations
+
+- **Platform support.** Tested on Windows; macOS/Linux are believed working — reports welcome.
+- **Transcript-format coupling.** AgentWrangler reads Claude Code's JSONL transcript format; a change
+  to that format upstream can require an ingestion update.
+- **Outcomes credential sources.** The cross-platform path is `AW_GITHUB_TOKEN`; the OS credential
+  store integration currently covers Windows Credential Manager only (macOS/Linux keychain is a
+  follow-on).
+- **Single local user.** It observes one machine's Claude Code history; there is no multi-user or
+  team-aggregation mode by design.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE). Copyright 2026 AgentWrangler contributors.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to build and test, [SECURITY.md](SECURITY.md) to report a
+vulnerability, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Documentation index
+
+| Path | Purpose |
+|---|---|
+| `docs/adr/ADR-100-stack.md` | Accepted MVP stack: Node 22 LTS + TypeScript + better-sqlite3, localhost UI (no Tauri/Electron for MVP) |
+| `docs/adr/ADR-100-shell-research-2026-08-21.md` | External research backing the localhost-UI decision |
+| `docs/planning/AgentWrangler_PRD_v0_7_0.md` | Product requirements v0.7.0 |
+| `docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md` | Architecture v4.5.0 |
+| `docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md` | SQLite schema + metric definitions v2 |
+| `docs/planning/AgentWrangler_Ingestion_and_Findings_Spec_v1.md` | Transcript ingestion + findings extractor spec |
+| `docs/planning/AgentWrangler_Recommendations_Engine_Spec_v1.md` | Recommendations engine spec |
+| `docs/planning/AgentWrangler_Spike_Plan_v2.md` | Spike exit criteria (authoritative) |
+| `docs/planning/AgentWrangler_PreImplementation_Plan_v1.md` | Session map + session prompts |