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.
- aiwatcher_local-0.1.1/LICENSE +184 -0
- aiwatcher_local-0.1.1/PKG-INFO +421 -0
- aiwatcher_local-0.1.1/README.md +395 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/__init__.py +3 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/__main__.py +3 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/ai_assist.py +1080 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/analyst.py +739 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/cli.py +10089 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/compaction.py +453 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/compaction_outcomes.py +621 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/companion.py +392 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/correlate.py +208 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/evidence_capture.py +103 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/handoff.py +805 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/improve.py +210 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/ledger.py +897 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/local_state.py +2929 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/metrics.py +348 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/native_overlay.py +4119 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/outcome_evidence.py +461 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/pricing.py +205 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/processes.py +331 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/prompt_signals.py +448 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/receipt.py +298 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/runtime_attachment.py +490 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/runtime_nudge.py +366 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/scanner.py +2093 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/session_health.py +467 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/session_presence.py +387 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/statusline.py +375 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/survival.py +273 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/ui.py +9390 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/updater.py +488 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/index.css +2193 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/index.html +585 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/index.js +6184 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.css +112 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.html +15 -0
- aiwatcher_local-0.1.1/aiwatcher_cli/web/overlay.js +291 -0
- aiwatcher_local-0.1.1/aiwatcher_local.egg-info/PKG-INFO +421 -0
- aiwatcher_local-0.1.1/aiwatcher_local.egg-info/SOURCES.txt +77 -0
- aiwatcher_local-0.1.1/aiwatcher_local.egg-info/dependency_links.txt +1 -0
- aiwatcher_local-0.1.1/aiwatcher_local.egg-info/entry_points.txt +2 -0
- aiwatcher_local-0.1.1/aiwatcher_local.egg-info/top_level.txt +1 -0
- aiwatcher_local-0.1.1/pyproject.toml +45 -0
- aiwatcher_local-0.1.1/setup.cfg +4 -0
- aiwatcher_local-0.1.1/tests/test_000_state_isolation.py +94 -0
- aiwatcher_local-0.1.1/tests/test_adapters.py +109 -0
- aiwatcher_local-0.1.1/tests/test_ai_assist.py +489 -0
- aiwatcher_local-0.1.1/tests/test_analyst.py +785 -0
- aiwatcher_local-0.1.1/tests/test_cli.py +7039 -0
- aiwatcher_local-0.1.1/tests/test_compaction.py +454 -0
- aiwatcher_local-0.1.1/tests/test_compaction_outcomes.py +456 -0
- aiwatcher_local-0.1.1/tests/test_companion.py +1395 -0
- aiwatcher_local-0.1.1/tests/test_correlate.py +250 -0
- aiwatcher_local-0.1.1/tests/test_evidence_capture.py +93 -0
- aiwatcher_local-0.1.1/tests/test_handoff.py +478 -0
- aiwatcher_local-0.1.1/tests/test_improve.py +158 -0
- aiwatcher_local-0.1.1/tests/test_improve_web.py +47 -0
- aiwatcher_local-0.1.1/tests/test_ledger.py +974 -0
- aiwatcher_local-0.1.1/tests/test_local_state.py +1407 -0
- aiwatcher_local-0.1.1/tests/test_metrics.py +280 -0
- aiwatcher_local-0.1.1/tests/test_native_overlay.py +728 -0
- aiwatcher_local-0.1.1/tests/test_outcome_evidence.py +359 -0
- aiwatcher_local-0.1.1/tests/test_pricing.py +260 -0
- aiwatcher_local-0.1.1/tests/test_processes.py +201 -0
- aiwatcher_local-0.1.1/tests/test_prompt_receipts.py +210 -0
- aiwatcher_local-0.1.1/tests/test_prompt_signals.py +315 -0
- aiwatcher_local-0.1.1/tests/test_receipt.py +383 -0
- aiwatcher_local-0.1.1/tests/test_refresh_status_runtime.py +62 -0
- aiwatcher_local-0.1.1/tests/test_runtime_attachment.py +324 -0
- aiwatcher_local-0.1.1/tests/test_runtime_nudge.py +257 -0
- aiwatcher_local-0.1.1/tests/test_scanner.py +1150 -0
- aiwatcher_local-0.1.1/tests/test_session_health.py +407 -0
- aiwatcher_local-0.1.1/tests/test_session_presence.py +482 -0
- aiwatcher_local-0.1.1/tests/test_statusline.py +483 -0
- aiwatcher_local-0.1.1/tests/test_survival.py +216 -0
- aiwatcher_local-0.1.1/tests/test_ui.py +5917 -0
- 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
|
+
[](https://github.com/ai-watcher/aiwatcher-local/actions/workflows/ci.yml)
|
|
30
|
+
[](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
|
+

|
|
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
|
+

|
|
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)
|