aiwatcher-local 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. aiwatcher_local-0.1.1/LICENSE +184 -0
  2. aiwatcher_local-0.1.1/PKG-INFO +421 -0
  3. aiwatcher_local-0.1.1/README.md +395 -0
  4. aiwatcher_local-0.1.1/aiwatcher_cli/__init__.py +3 -0
  5. aiwatcher_local-0.1.1/aiwatcher_cli/__main__.py +3 -0
  6. aiwatcher_local-0.1.1/aiwatcher_cli/ai_assist.py +1080 -0
  7. aiwatcher_local-0.1.1/aiwatcher_cli/analyst.py +739 -0
  8. aiwatcher_local-0.1.1/aiwatcher_cli/cli.py +10089 -0
  9. aiwatcher_local-0.1.1/aiwatcher_cli/compaction.py +453 -0
  10. aiwatcher_local-0.1.1/aiwatcher_cli/compaction_outcomes.py +621 -0
  11. aiwatcher_local-0.1.1/aiwatcher_cli/companion.py +392 -0
  12. aiwatcher_local-0.1.1/aiwatcher_cli/correlate.py +208 -0
  13. aiwatcher_local-0.1.1/aiwatcher_cli/evidence_capture.py +103 -0
  14. aiwatcher_local-0.1.1/aiwatcher_cli/handoff.py +805 -0
  15. aiwatcher_local-0.1.1/aiwatcher_cli/improve.py +210 -0
  16. aiwatcher_local-0.1.1/aiwatcher_cli/ledger.py +897 -0
  17. aiwatcher_local-0.1.1/aiwatcher_cli/local_state.py +2929 -0
  18. aiwatcher_local-0.1.1/aiwatcher_cli/metrics.py +348 -0
  19. aiwatcher_local-0.1.1/aiwatcher_cli/native_overlay.py +4119 -0
  20. aiwatcher_local-0.1.1/aiwatcher_cli/outcome_evidence.py +461 -0
  21. aiwatcher_local-0.1.1/aiwatcher_cli/pricing.py +205 -0
  22. aiwatcher_local-0.1.1/aiwatcher_cli/processes.py +331 -0
  23. aiwatcher_local-0.1.1/aiwatcher_cli/prompt_signals.py +448 -0
  24. aiwatcher_local-0.1.1/aiwatcher_cli/receipt.py +298 -0
  25. aiwatcher_local-0.1.1/aiwatcher_cli/runtime_attachment.py +490 -0
  26. aiwatcher_local-0.1.1/aiwatcher_cli/runtime_nudge.py +366 -0
  27. aiwatcher_local-0.1.1/aiwatcher_cli/scanner.py +2093 -0
  28. aiwatcher_local-0.1.1/aiwatcher_cli/session_health.py +467 -0
  29. aiwatcher_local-0.1.1/aiwatcher_cli/session_presence.py +387 -0
  30. aiwatcher_local-0.1.1/aiwatcher_cli/statusline.py +375 -0
  31. aiwatcher_local-0.1.1/aiwatcher_cli/survival.py +273 -0
  32. aiwatcher_local-0.1.1/aiwatcher_cli/ui.py +9390 -0
  33. aiwatcher_local-0.1.1/aiwatcher_cli/updater.py +488 -0
  34. aiwatcher_local-0.1.1/aiwatcher_cli/web/index.css +2193 -0
  35. aiwatcher_local-0.1.1/aiwatcher_cli/web/index.html +585 -0
  36. aiwatcher_local-0.1.1/aiwatcher_cli/web/index.js +6184 -0
  37. aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.css +112 -0
  38. aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.html +15 -0
  39. aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.js +291 -0
  40. aiwatcher_local-0.1.1/aiwatcher_local.egg-info/PKG-INFO +421 -0
  41. aiwatcher_local-0.1.1/aiwatcher_local.egg-info/SOURCES.txt +77 -0
  42. aiwatcher_local-0.1.1/aiwatcher_local.egg-info/dependency_links.txt +1 -0
  43. aiwatcher_local-0.1.1/aiwatcher_local.egg-info/entry_points.txt +2 -0
  44. aiwatcher_local-0.1.1/aiwatcher_local.egg-info/top_level.txt +1 -0
  45. aiwatcher_local-0.1.1/pyproject.toml +45 -0
  46. aiwatcher_local-0.1.1/setup.cfg +4 -0
  47. aiwatcher_local-0.1.1/tests/test_000_state_isolation.py +94 -0
  48. aiwatcher_local-0.1.1/tests/test_adapters.py +109 -0
  49. aiwatcher_local-0.1.1/tests/test_ai_assist.py +489 -0
  50. aiwatcher_local-0.1.1/tests/test_analyst.py +785 -0
  51. aiwatcher_local-0.1.1/tests/test_cli.py +7039 -0
  52. aiwatcher_local-0.1.1/tests/test_compaction.py +454 -0
  53. aiwatcher_local-0.1.1/tests/test_compaction_outcomes.py +456 -0
  54. aiwatcher_local-0.1.1/tests/test_companion.py +1395 -0
  55. aiwatcher_local-0.1.1/tests/test_correlate.py +250 -0
  56. aiwatcher_local-0.1.1/tests/test_evidence_capture.py +93 -0
  57. aiwatcher_local-0.1.1/tests/test_handoff.py +478 -0
  58. aiwatcher_local-0.1.1/tests/test_improve.py +158 -0
  59. aiwatcher_local-0.1.1/tests/test_improve_web.py +47 -0
  60. aiwatcher_local-0.1.1/tests/test_ledger.py +974 -0
  61. aiwatcher_local-0.1.1/tests/test_local_state.py +1407 -0
  62. aiwatcher_local-0.1.1/tests/test_metrics.py +280 -0
  63. aiwatcher_local-0.1.1/tests/test_native_overlay.py +728 -0
  64. aiwatcher_local-0.1.1/tests/test_outcome_evidence.py +359 -0
  65. aiwatcher_local-0.1.1/tests/test_pricing.py +260 -0
  66. aiwatcher_local-0.1.1/tests/test_processes.py +201 -0
  67. aiwatcher_local-0.1.1/tests/test_prompt_receipts.py +210 -0
  68. aiwatcher_local-0.1.1/tests/test_prompt_signals.py +315 -0
  69. aiwatcher_local-0.1.1/tests/test_receipt.py +383 -0
  70. aiwatcher_local-0.1.1/tests/test_refresh_status_runtime.py +62 -0
  71. aiwatcher_local-0.1.1/tests/test_runtime_attachment.py +324 -0
  72. aiwatcher_local-0.1.1/tests/test_runtime_nudge.py +257 -0
  73. aiwatcher_local-0.1.1/tests/test_scanner.py +1150 -0
  74. aiwatcher_local-0.1.1/tests/test_session_health.py +407 -0
  75. aiwatcher_local-0.1.1/tests/test_session_presence.py +482 -0
  76. aiwatcher_local-0.1.1/tests/test_statusline.py +483 -0
  77. aiwatcher_local-0.1.1/tests/test_survival.py +216 -0
  78. aiwatcher_local-0.1.1/tests/test_ui.py +5917 -0
  79. aiwatcher_local-0.1.1/tests/test_ui_assets.py +3390 -0
@@ -0,0 +1,184 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction, and
10
+ distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright
13
+ owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all other entities
16
+ that control, are controlled by, or are under common control with that entity.
17
+ For the purposes of this definition, "control" means (i) the power, direct or
18
+ indirect, to cause the direction or management of such entity, whether by
19
+ contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
20
+ outstanding shares, or (iii) beneficial ownership of such entity.
21
+
22
+ "You" (or "Your") shall mean an individual or Legal Entity exercising
23
+ permissions granted by this License.
24
+
25
+ "Source" form shall mean the preferred form for making modifications, including
26
+ but not limited to software source code, documentation source, and configuration
27
+ files.
28
+
29
+ "Object" form shall mean any form resulting from mechanical transformation or
30
+ translation of a Source form, including but not limited to compiled object code,
31
+ generated documentation, and conversions to other media types.
32
+
33
+ "Work" shall mean the work of authorship, whether in Source or Object form,
34
+ made available under the License, as indicated by a copyright notice that is
35
+ included in or attached to the work (an example is provided in the Appendix
36
+ below).
37
+
38
+ "Derivative Works" shall mean any work, whether in Source or Object form, that
39
+ is based on (or derived from) the Work and for which the editorial revisions,
40
+ annotations, elaborations, or other modifications represent, as a whole, an
41
+ original work of authorship. For the purposes of this License, Derivative Works
42
+ shall not include works that remain separable from, or merely link (or bind by
43
+ name) to the interfaces of, the Work and Derivative Works thereof.
44
+
45
+ "Contribution" shall mean any work of authorship, including the original
46
+ version of the Work and any modifications or additions to that Work or
47
+ Derivative Works thereof, that is intentionally submitted to Licensor for
48
+ inclusion in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes of this
50
+ definition, "submitted" means any form of electronic, verbal, or written
51
+ communication sent to the Licensor or its representatives, including but not
52
+ limited to communication on electronic mailing lists, source code control
53
+ systems, and issue tracking systems that are managed by, or on behalf of, the
54
+ Licensor for the purpose of discussing and improving the Work, but excluding
55
+ communication that is conspicuously marked or otherwise designated in writing
56
+ by the copyright owner as "Not a Contribution."
57
+
58
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
59
+ of whom a Contribution has been received by Licensor and subsequently
60
+ incorporated within the Work.
61
+
62
+ 2. Grant of Copyright License. Subject to the terms and conditions of this
63
+ License, each Contributor hereby grants to You a perpetual, worldwide,
64
+ non-exclusive, no-charge, royalty-free, irrevocable copyright license to
65
+ reproduce, prepare Derivative Works of, publicly display, publicly perform,
66
+ sublicense, and distribute the Work and such Derivative Works in Source or
67
+ Object form.
68
+
69
+ 3. Grant of Patent License. Subject to the terms and conditions of this License,
70
+ each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
71
+ no-charge, royalty-free, irrevocable (except as stated in this section) patent
72
+ license to make, have made, use, offer to sell, sell, import, and otherwise
73
+ transfer the Work, where such license applies only to those patent claims
74
+ licensable by such Contributor that are necessarily infringed by their
75
+ Contribution(s) alone or by combination of their Contribution(s) with the Work
76
+ to which such Contribution(s) was submitted. If You institute patent litigation
77
+ against any entity (including a cross-claim or counterclaim in a lawsuit)
78
+ alleging that the Work or a Contribution incorporated within the Work
79
+ constitutes direct or contributory patent infringement, then any patent licenses
80
+ granted to You under this License for that Work shall terminate as of the date
81
+ such litigation is filed.
82
+
83
+ 4. Redistribution. You may reproduce and distribute copies of the Work or
84
+ Derivative Works thereof in any medium, with or without modifications, and in
85
+ Source or Object form, provided that You meet the following conditions:
86
+
87
+ (a) You must give any other recipients of the Work or Derivative Works a copy of
88
+ this License; and
89
+
90
+ (b) You must cause any modified files to carry prominent notices stating that
91
+ You changed the files; and
92
+
93
+ (c) You must retain, in the Source form of any Derivative Works that You
94
+ distribute, all copyright, patent, trademark, and attribution notices from the
95
+ Source form of the Work, excluding those notices that do not pertain to any part
96
+ of the Derivative Works; and
97
+
98
+ (d) If the Work includes a "NOTICE" text file as part of its distribution, then
99
+ any Derivative Works that You distribute must include a readable copy of the
100
+ attribution notices contained within such NOTICE file, excluding those notices
101
+ that do not pertain to any part of the Derivative Works, in at least one of the
102
+ following places: within a NOTICE text file distributed as part of the
103
+ Derivative Works; within the Source form or documentation, if provided along
104
+ with the Derivative Works; or, within a display generated by the Derivative
105
+ Works, if and wherever such third-party notices normally appear. The contents of
106
+ the NOTICE file are for informational purposes only and do not modify the
107
+ License. You may add Your own attribution notices within Derivative Works that
108
+ You distribute, alongside or as an addendum to the NOTICE text from the Work,
109
+ provided that such additional attribution notices cannot be construed as
110
+ modifying the License.
111
+
112
+ You may add Your own copyright statement to Your modifications and may provide
113
+ additional or different license terms and conditions for use, reproduction, or
114
+ distribution of Your modifications, or for any such Derivative Works as a whole,
115
+ provided Your use, reproduction, and distribution of the Work otherwise complies
116
+ with the conditions stated in this License.
117
+
118
+ 5. Submission of Contributions. Unless You explicitly state otherwise, any
119
+ Contribution intentionally submitted for inclusion in the Work by You to the
120
+ Licensor shall be under the terms and conditions of this License, without any
121
+ additional terms or conditions. Notwithstanding the above, nothing herein shall
122
+ supersede or modify the terms of any separate license agreement you may have
123
+ executed with Licensor regarding such Contributions.
124
+
125
+ 6. Trademarks. This License does not grant permission to use the trade names,
126
+ trademarks, service marks, or product names of the Licensor, except as required
127
+ for reasonable and customary use in describing the origin of the Work and
128
+ reproducing the content of the NOTICE file.
129
+
130
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
131
+ writing, Licensor provides the Work (and each Contributor provides its
132
+ Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
133
+ KIND, either express or implied, including, without limitation, any warranties or
134
+ conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
135
+ PARTICULAR PURPOSE. You are solely responsible for determining the
136
+ appropriateness of using or redistributing the Work and assume any risks
137
+ associated with Your exercise of permissions under this License.
138
+
139
+ 8. Limitation of Liability. In no event and under no legal theory, whether in
140
+ tort (including negligence), contract, or otherwise, unless required by
141
+ applicable law (such as deliberate and grossly negligent acts) or agreed to in
142
+ writing, shall any Contributor be liable to You for damages, including any
143
+ direct, indirect, special, incidental, or consequential damages of any character
144
+ arising as a result of this License or out of the use or inability to use the
145
+ Work (including but not limited to damages for loss of goodwill, work stoppage,
146
+ computer failure or malfunction, or any and all other commercial damages or
147
+ losses), even if such Contributor has been advised of the possibility of such
148
+ damages.
149
+
150
+ 9. Accepting Warranty or Additional Liability. While redistributing the Work or
151
+ Derivative Works thereof, You may choose to offer, and charge a fee for,
152
+ acceptance of support, warranty, indemnity, or other liability obligations
153
+ and/or rights consistent with this License. However, in accepting such
154
+ obligations, You may act only on Your own behalf and on Your sole
155
+ responsibility, not on behalf of any other Contributor, and only if You agree to
156
+ indemnify, defend, and hold each Contributor harmless for any liability incurred
157
+ by, or claims asserted against, such Contributor by reason of your accepting any
158
+ such warranty or additional liability.
159
+
160
+ END OF TERMS AND CONDITIONS
161
+
162
+ APPENDIX: How to apply the Apache License to your work.
163
+
164
+ To apply the Apache License to your work, attach the following boilerplate
165
+ notice, with the fields enclosed by brackets "[]" replaced with your own
166
+ identifying information. (Don't include the brackets!) The text should be
167
+ enclosed in the appropriate comment syntax for the file format. We also
168
+ recommend that a file or class name and description of purpose be included on
169
+ the same "printed page" as the copyright notice for easier identification
170
+ within third-party archives.
171
+
172
+ Copyright 2026 AIWatcher
173
+
174
+ Licensed under the Apache License, Version 2.0 (the "License");
175
+ you may not use this file except in compliance with the License.
176
+ You may obtain a copy of the License at
177
+
178
+ http://www.apache.org/licenses/LICENSE-2.0
179
+
180
+ Unless required by applicable law or agreed to in writing, software
181
+ distributed under the License is distributed on an "AS IS" BASIS,
182
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
183
+ See the License for the specific language governing permissions and
184
+ limitations under the License.
@@ -0,0 +1,421 @@
1
+ Metadata-Version: 2.4
2
+ Name: aiwatcher-local
3
+ Version: 0.1.1
4
+ Summary: Local-first control loop for AI coding cost, safety, and outcomes
5
+ Author: AIWatcher
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://www.getaiwatcher.com
8
+ Project-URL: Documentation, https://github.com/ai-watcher/aiwatcher-local
9
+ Project-URL: Repository, https://github.com/ai-watcher/aiwatcher-local
10
+ Project-URL: Issues, https://github.com/ai-watcher/aiwatcher-local/issues
11
+ Keywords: ai,observability,llm,coding-agents,cost
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Software Development :: Quality Assurance
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # AIWatcher Local
28
+
29
+ [![CI](https://github.com/ai-watcher/aiwatcher-local/actions/workflows/ci.yml/badge.svg)](https://github.com/ai-watcher/aiwatcher-local/actions/workflows/ci.yml)
30
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
31
+
32
+ Private guardrails for AI coding work. AIWatcher helps you review risky
33
+ prompts before they run, notice expensive or stuck sessions while they are
34
+ active, and prove whether the work became useful code afterwards.
35
+
36
+ It works with local history from tools such as Claude Code, Codex, and Cursor.
37
+ No account is required. No cloud upload happens by default. No LLM call happens
38
+ unless you explicitly configure optional AI Assist.
39
+
40
+ ![AIWatcher Local home dashboard](docs/readme-home-light.svg)
41
+
42
+ ## Contents
43
+
44
+ - [What You Get](#what-you-get)
45
+ - [First Look](#first-look)
46
+ - [Why Developers Use It](#why-developers-use-it)
47
+ - [Install](#install)
48
+ - [If Install Fails](#if-install-fails)
49
+ - [First Useful Checks](#first-useful-checks)
50
+ - [Optional Hooks](#optional-hooks)
51
+ - [Clone The Codebase](#clone-the-codebase)
52
+ - [Keep AIWatcher Updated](#keep-aiwatcher-updated)
53
+ - [What It Reads](#what-it-reads)
54
+ - [Common Commands](#common-commands)
55
+ - [Project Status](#project-status)
56
+ - [AIWatcher Local and Enterprise](#aiwatcher-local-and-enterprise)
57
+ - [Contributing](#contributing)
58
+ - [License](#license)
59
+
60
+ ## What You Get
61
+
62
+ In the first few minutes, AIWatcher gives one developer a local control loop for
63
+ AI coding work:
64
+
65
+ - **Before the run:** review risky or over-broad prompts before an agent spends
66
+ context.
67
+ - **During the run:** notice loops, context pressure, idle sessions, and work
68
+ waiting on you.
69
+ - **After the run:** connect AI sessions to commits, outcomes, receipts, and
70
+ improvement signals.
71
+
72
+ No signup is required, and the default install keeps data on your machine.
73
+
74
+ ## First Look
75
+
76
+ The Home view shows active AI work, context pressure, update status, and the
77
+ small Companion control. Plan helps narrow risky prompts before an agent spends
78
+ context:
79
+
80
+ ![AIWatcher Plan prompt gate](docs/readme-plan-light.svg)
81
+
82
+ ## Why Developers Use It
83
+
84
+ - **Catch expensive prompts early:** preflight broad, vague, destructive, or
85
+ high-context work before an AI agent starts spending tokens.
86
+ - **Stay out of runaway sessions:** get local nudges for context pressure,
87
+ loops, long-running work, and sessions waiting on you.
88
+ - **Start fresh without losing the plot:** create a compact Fresh Start brief
89
+ for continuing work in a new session.
90
+ - **Prove what was worth it:** connect local AI sessions to commits, outcomes,
91
+ receipts, and API-equivalent usage.
92
+ - **Keep trust visible:** label what is automatic, what is inferred, and what
93
+ the current tool surface cannot prove.
94
+
95
+ ## Install
96
+
97
+ Install AIWatcher Local as an isolated command-line application with `pipx`.
98
+ Use Python 3.10+ for the recommended path. AIWatcher also supports Python 3.9
99
+ when installed from source. Python 2 is not supported.
100
+
101
+ Pick one path and ignore the rest.
102
+
103
+ ### One-Line Install
104
+
105
+ Use this when Python 3.10+ and pipx are already installed.
106
+
107
+ macOS or Linux:
108
+
109
+ ```sh
110
+ pipx install aiwatcher-local && ~/.local/bin/aiwatcher setup && ~/.local/bin/aiwatcher start --open-ui
111
+ ```
112
+
113
+ Windows PowerShell:
114
+
115
+ ```powershell
116
+ py -3 -m pipx install aiwatcher-local; & "$env:USERPROFILE\.local\bin\aiwatcher.exe" setup; & "$env:USERPROFILE\.local\bin\aiwatcher.exe" start --open-ui
117
+ ```
118
+
119
+ Run `pipx ensurepath` later if you want to type `aiwatcher` without the full
120
+ path in a new terminal.
121
+
122
+ ### Missing Prerequisites
123
+
124
+ Use this if you are not sure what is already installed. These commands check
125
+ first and only install missing prerequisites.
126
+
127
+ macOS:
128
+
129
+ ```sh
130
+ command -v brew >/dev/null || { echo "Install Homebrew first: https://brew.sh"; exit 1; }
131
+ command -v python3 >/dev/null || brew install python
132
+ command -v pipx >/dev/null || brew install pipx
133
+ if [ -x ~/.local/bin/aiwatcher ]; then
134
+ pipx upgrade aiwatcher-local
135
+ else
136
+ pipx install aiwatcher-local
137
+ fi
138
+ ~/.local/bin/aiwatcher setup
139
+ ~/.local/bin/aiwatcher start --open-ui
140
+ ```
141
+
142
+ Ubuntu or Debian:
143
+
144
+ ```sh
145
+ if ! command -v python3 >/dev/null || ! command -v pipx >/dev/null; then
146
+ sudo apt update
147
+ fi
148
+ command -v python3 >/dev/null || sudo apt install -y python3 python3-pip
149
+ command -v pipx >/dev/null || sudo apt install -y pipx
150
+ if [ -x ~/.local/bin/aiwatcher ]; then
151
+ pipx upgrade aiwatcher-local
152
+ else
153
+ pipx install aiwatcher-local
154
+ fi
155
+ ~/.local/bin/aiwatcher setup
156
+ ~/.local/bin/aiwatcher start --open-ui
157
+ ```
158
+
159
+ For other Linux distributions, install Python 3.10+ and pipx with your
160
+ package manager, then use the one-line install.
161
+
162
+ Windows PowerShell:
163
+
164
+ ```powershell
165
+ if (-not (Get-Command py -ErrorAction SilentlyContinue)) {
166
+ winget install Python.Python.3.12
167
+ Write-Host "Open a new PowerShell after Python installs, then rerun these commands."
168
+ exit
169
+ }
170
+ py -3 --version
171
+ py -3 -m pipx --version *> $null
172
+ if ($LASTEXITCODE -ne 0) { py -3 -m pip install --user pipx }
173
+ $aiwatcher = "$env:USERPROFILE\.local\bin\aiwatcher.exe"
174
+ if (Test-Path $aiwatcher) {
175
+ py -3 -m pipx upgrade aiwatcher-local
176
+ } else {
177
+ py -3 -m pipx install aiwatcher-local
178
+ }
179
+ & $aiwatcher setup
180
+ & $aiwatcher start --open-ui
181
+ ```
182
+
183
+ To make the shorter command work in future terminals, run:
184
+
185
+ ```sh
186
+ pipx ensurepath
187
+ ```
188
+
189
+ Then open a new terminal and use:
190
+
191
+ ```sh
192
+ aiwatcher setup
193
+ aiwatcher start --open-ui
194
+ ```
195
+
196
+ `setup` detects local AI tools and prints copy/paste next steps. It is not an
197
+ interactive menu, so you do not need to type a number.
198
+ `start --open-ui` starts the browser Console, the background Companion, and the
199
+ small floating control on macOS and Windows.
200
+
201
+ ## If Install Fails
202
+
203
+ Use the row matching the error you saw.
204
+
205
+ | Error | Fix |
206
+ | --- | --- |
207
+ | Python reports `2.x` or below `3.10` | Install Python 3.10+ for the recommended `pipx` path. AIWatcher does not support Python 2. |
208
+ | `externally-managed-environment` | On macOS Homebrew Python, run `brew install pipx`, then use `pipx install ...`. Do not add `--break-system-packages`. |
209
+ | `brew: command not found` | Install Homebrew from [brew.sh](https://brew.sh), then rerun the macOS commands. |
210
+ | `pipx: command not found` | macOS: `brew install pipx`. Ubuntu/Debian: `sudo apt install pipx`. Windows: use `py -3 -m pipx ...` after installing pipx. |
211
+ | `python: command not found` | Use `python3` on macOS/Linux or `py -3` on Windows. |
212
+ | `python3: command not found` | Install Python 3.10+. macOS: `brew install python` or use python.org. Windows: use python.org or `winget install Python.Python.3.12`. |
213
+ | `py: command not found` | Install Python 3 from python.org or run `winget install Python.Python.3.12`, then open a new PowerShell. |
214
+ | `git: command not found` | Install Git. macOS: `xcode-select --install` or `brew install git`. Windows: install Git for Windows or run `winget install Git.Git`. |
215
+ | `No module named pip` | Run `python3 -m ensurepip --upgrade` on macOS/Linux or `py -3 -m ensurepip --upgrade` on Windows. |
216
+ | `No module named pip3` | Use `python3 -m pip install ...`, not `python3 -m pip3 install ...`. The module name is `pip`. |
217
+ | `aiwatcher: command not found` | Open a new terminal after `ensurepath`, or use `~/.local/bin/aiwatcher` / `& "$env:USERPROFILE\.local\bin\aiwatcher.exe"`. |
218
+
219
+ ## First Useful Checks
220
+
221
+ ```sh
222
+ aiwatcher doctor
223
+ aiwatcher hook-status
224
+ aiwatcher preflight "Refactor the checkout flow and delete old auth secrets" --tool codex --cwd "$(pwd)"
225
+ ```
226
+
227
+ - `doctor` shows which local tools AIWatcher can read.
228
+ - `hook-status` proves whether a tool actually invoked AIWatcher.
229
+ - `preflight` gives value immediately, even before hooks are installed.
230
+
231
+ ## Optional Hooks
232
+
233
+ Hooks let AIWatcher act before the AI tool spends context. Install only the
234
+ ones you use:
235
+
236
+ ```sh
237
+ aiwatcher install-claude-hook --write --scope user --gate
238
+ aiwatcher install-codex-hook --write --scope user --gate
239
+ aiwatcher install-cursor-hook --write --scope user --gate
240
+ ```
241
+
242
+ For Claude Code CLI, AIWatcher can also review risky shell commands before
243
+ they run:
244
+
245
+ ```sh
246
+ aiwatcher install-claude-command-gate --write --scope user
247
+ ```
248
+
249
+ Then send a small test prompt in your AI tool and verify:
250
+
251
+ ```sh
252
+ aiwatcher hook-status
253
+ ```
254
+
255
+ If a surface does not invoke hooks, use the Console or Companion **Plan** flow
256
+ to preflight prompts manually. AIWatcher does not claim silent protection on
257
+ tool surfaces that do not expose a verified lifecycle hook.
258
+
259
+ ## Clone The Codebase
260
+
261
+ Clone only if you want to contribute, inspect code locally, or use the
262
+ dashboard's source-update flow. Most users should use the `pipx` path above.
263
+
264
+ The source clone path creates a project-local virtual environment, so it does
265
+ not modify your Homebrew, system, or Windows Python packages.
266
+
267
+ macOS or Linux:
268
+
269
+ ```sh
270
+ git clone https://github.com/ai-watcher/aiwatcher-local.git
271
+ cd aiwatcher-local
272
+ python3 -m venv .venv
273
+ source .venv/bin/activate
274
+ python -m pip install -e .
275
+ python -m aiwatcher_cli setup
276
+ python -m aiwatcher_cli start --open-ui
277
+ ```
278
+
279
+ Windows PowerShell:
280
+
281
+ ```powershell
282
+ git clone https://github.com/ai-watcher/aiwatcher-local.git
283
+ cd aiwatcher-local
284
+ py -3 -m venv .venv
285
+ .\.venv\Scripts\Activate.ps1
286
+ python -m pip install -e .
287
+ python -m aiwatcher_cli setup
288
+ python -m aiwatcher_cli start --open-ui
289
+ ```
290
+
291
+ The key detail is `python -m pip` inside the virtual environment. Do not use
292
+ `python -m pip3`.
293
+
294
+ ## Keep AIWatcher Updated
295
+
296
+ | Install type | Update command |
297
+ | --- | --- |
298
+ | PyPI `pipx` install | macOS/Linux: `pipx upgrade aiwatcher-local`; Windows: `py -3 -m pipx upgrade aiwatcher-local` |
299
+ | PyPI `pip` install in a virtual environment | `python -m pip install --upgrade aiwatcher-local` |
300
+ | Source clone | `aiwatcher update --apply`, then `aiwatcher start --open-ui` |
301
+ | `uv` tool install | `uv tool upgrade aiwatcher-local` |
302
+
303
+ For source clones, the top-bar update badge checks GitHub only when clicked
304
+ unless you turn on automatic checks in Settings. Applying an update is a second
305
+ explicit step from Settings.
306
+
307
+ The recommended install/update path is:
308
+
309
+ ```sh
310
+ pipx install aiwatcher-local
311
+ pipx upgrade aiwatcher-local
312
+ ```
313
+
314
+ Users of the original `aiwatcher-cli` 0.1.0 package should migrate once:
315
+
316
+ ```sh
317
+ pipx uninstall aiwatcher-cli
318
+ pipx install aiwatcher-local
319
+ ```
320
+
321
+ Maintainers should use [docs/RELEASE.md](docs/RELEASE.md) before publishing.
322
+
323
+ ## What It Reads
324
+
325
+ AIWatcher reads local evidence that AI tools already store on your machine.
326
+
327
+ | Area | What AIWatcher uses |
328
+ | --- | --- |
329
+ | Claude Code | Local JSONL session history under `~/.claude` when present |
330
+ | Codex | Local rollout/session history when available |
331
+ | Cursor and other tools | Detected local history where the tool exposes it |
332
+ | Git repositories | Commit metadata, diffs, survival checks, and local working tree state |
333
+ | Runtime watch | Process metadata such as age, CPU/RAM, command, and known session flags |
334
+
335
+ AIWatcher stores local receipts, hashes, decisions, outcomes, and metadata. It
336
+ does not persist raw prompt text from Prompt Gate decisions. Optional AI Assist
337
+ can send bounded prompt/source context only when you configure it and choose a
338
+ workflow that uses it.
339
+
340
+ See [docs/AIWATCHER_LOCAL.md](docs/AIWATCHER_LOCAL.md) for the full privacy and
341
+ coverage boundary.
342
+
343
+ ## Laptop Footprint
344
+
345
+ AIWatcher is a Python package with static dashboard assets, not a native
346
+ background daemon. It does nothing in the background until you run
347
+ `aiwatcher start`, `aiwatcher companion start`, or install login autostart.
348
+
349
+ Measured from this repo on macOS with Python 3.14:
350
+
351
+ | Area | Observed footprint |
352
+ | --- | --- |
353
+ | Wheel artifact | 530 KB |
354
+ | Installed AIWatcher package | 3.9 MB, excluding the Python/pipx environment |
355
+ | Python dependencies | None declared by AIWatcher |
356
+ | Idle dashboard process | Usually tens of MB RSS, near 0% CPU when idle |
357
+ | Dashboard + Companion | Near 0% CPU between scans; short scan spikes depend on local history size |
358
+
359
+ On the measured machine, a Companion startup scan over recent local AI history
360
+ briefly used more CPU and memory, then settled back near idle. Larger local
361
+ Claude/Codex/Cursor histories can make that scan peak higher. The default
362
+ Companion interval is 30 seconds, and you can stop it any time:
363
+
364
+ ```sh
365
+ aiwatcher companion stop
366
+ ```
367
+
368
+ ## Common Commands
369
+
370
+ | Command | Purpose |
371
+ | --- | --- |
372
+ | `aiwatcher setup` | Detect tools and show recommended setup |
373
+ | `aiwatcher start --open-ui` | Start the Console and Companion |
374
+ | `aiwatcher doctor` | Check local detection and integration health |
375
+ | `aiwatcher hook-status` | Verify hook invocation |
376
+ | `aiwatcher preflight "..."` | Review a prompt manually |
377
+ | `aiwatcher sessions` | Review recent local AI sessions |
378
+ | `aiwatcher changes --days 30` | See AI-attributed commit evidence |
379
+ | `aiwatcher outcome useful` | Mark the latest session outcome |
380
+ | `aiwatcher update` | Check whether a source clone is behind GitHub |
381
+
382
+ Full command reference: [docs/CLI.md](docs/CLI.md).
383
+
384
+ ## Project Status
385
+
386
+ AIWatcher Local is an early open-source release. The local-first workflow is
387
+ usable today, but hook coverage depends on what each AI tool exposes on your
388
+ machine. The UI is moving quickly, so screenshots and docs may change while the
389
+ core privacy boundary stays stable.
390
+
391
+ Useful next reads:
392
+
393
+ - [Product and validation notes](docs/AIWATCHER_LOCAL.md)
394
+ - [CLI reference](docs/CLI.md)
395
+ - [HTTP API reference](docs/HTTP-API.md)
396
+ - [Release checklist](docs/RELEASE.md)
397
+
398
+ ## AIWatcher Local and Enterprise
399
+
400
+ AIWatcher Local is the open-source, developer-controlled loop for one machine.
401
+ It should be useful without signup, a cloud account, or a team admin.
402
+
403
+ AIWatcher Enterprise adds team policy, budgets, approvals, audit evidence,
404
+ SSO/RBAC, managed deployment, central retention, org dashboards, and
405
+ production-agent governance. Enterprise features are additive; Local is not a
406
+ locked demo.
407
+
408
+ The Apache-2.0 license covers this code. It does not grant rights to the
409
+ AIWatcher name, logo, hosted service, or Enterprise control plane. Learn more at
410
+ <https://www.getaiwatcher.com>.
411
+
412
+ ## Contributing
413
+
414
+ Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md).
415
+
416
+ For security reports, use [SECURITY.md](SECURITY.md). Please follow the
417
+ [Code of Conduct](CODE_OF_CONDUCT.md).
418
+
419
+ ## License
420
+
421
+ [Apache License 2.0](LICENSE)