centsible 0.10.0__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 (42) hide show
  1. centsible-0.10.0/LICENSE +21 -0
  2. centsible-0.10.0/PKG-INFO +215 -0
  3. centsible-0.10.0/README.md +192 -0
  4. centsible-0.10.0/centsible/__init__.py +4 -0
  5. centsible-0.10.0/centsible/__main__.py +12 -0
  6. centsible-0.10.0/centsible.egg-info/PKG-INFO +215 -0
  7. centsible-0.10.0/centsible.egg-info/SOURCES.txt +40 -0
  8. centsible-0.10.0/centsible.egg-info/dependency_links.txt +1 -0
  9. centsible-0.10.0/centsible.egg-info/entry_points.txt +2 -0
  10. centsible-0.10.0/centsible.egg-info/top_level.txt +2 -0
  11. centsible-0.10.0/core/__init__.py +5 -0
  12. centsible-0.10.0/core/budget.py +104 -0
  13. centsible-0.10.0/core/cli.py +104 -0
  14. centsible-0.10.0/core/cli_parser.py +157 -0
  15. centsible-0.10.0/core/commands.py +434 -0
  16. centsible-0.10.0/core/event_log.py +84 -0
  17. centsible-0.10.0/core/fact_audit.py +178 -0
  18. centsible-0.10.0/core/fact_helpers.py +819 -0
  19. centsible-0.10.0/core/fact_tune.py +197 -0
  20. centsible-0.10.0/core/facts_engine.py +803 -0
  21. centsible-0.10.0/core/hooks.py +371 -0
  22. centsible-0.10.0/core/install.py +204 -0
  23. centsible-0.10.0/core/loop_guard.py +841 -0
  24. centsible-0.10.0/core/share.py +146 -0
  25. centsible-0.10.0/core/transcript.py +197 -0
  26. centsible-0.10.0/core/triggers.json +93 -0
  27. centsible-0.10.0/pyproject.toml +40 -0
  28. centsible-0.10.0/setup.cfg +4 -0
  29. centsible-0.10.0/tests/test_attribution_and_metrics.py +302 -0
  30. centsible-0.10.0/tests/test_baseline.py +91 -0
  31. centsible-0.10.0/tests/test_budget.py +123 -0
  32. centsible-0.10.0/tests/test_claude_integration.py +294 -0
  33. centsible-0.10.0/tests/test_cli_integration.py +451 -0
  34. centsible-0.10.0/tests/test_concurrency.py +39 -0
  35. centsible-0.10.0/tests/test_event_log.py +81 -0
  36. centsible-0.10.0/tests/test_fact_audit.py +75 -0
  37. centsible-0.10.0/tests/test_fact_tune.py +88 -0
  38. centsible-0.10.0/tests/test_facts_engine.py +636 -0
  39. centsible-0.10.0/tests/test_hermes_integration.py +82 -0
  40. centsible-0.10.0/tests/test_loop_guard.py +319 -0
  41. centsible-0.10.0/tests/test_tool_recovery.py +232 -0
  42. centsible-0.10.0/tests/test_version_sync.py +27 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vi Nguyen (@ntrieuvi97)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,215 @@
1
+ Metadata-Version: 2.4
2
+ Name: centsible
3
+ Version: 0.10.0
4
+ Summary: Repo memory and loop guard for AI coding agents, with savings reported as verified vs estimated. Zero dependencies.
5
+ Author: Vi Nguyen
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/ntrieuvi97/centsible
8
+ Project-URL: Issues, https://github.com/ntrieuvi97/centsible/issues
9
+ Keywords: claude-code,ai-agents,agent-memory,loop-guard,token-savings
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.9
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Topic :: Software Development :: Quality Assurance
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # centsible 🪙
25
+
26
+ **Repo memory and loop guard for AI coding agents, with savings reported as *verified* vs *estimated*.** Centsible stores one-line repo facts, injects each only when the situation matches, stops runaway retry loops, and tells you how many tokens it actually saved. Standard library only.
27
+
28
+ [![CI](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml/badge.svg)](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml)
29
+ [![Version: 0.10.0](https://img.shields.io/badge/Version-0.10.0-orange.svg)](#)
30
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
31
+ [![Python: 3.9+](https://img.shields.io/badge/python-3.9%2B-green.svg)](https://www.python.org/)
32
+ [![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#)
33
+ [![Works with: Claude Code | Antigravity | OpenClaw | Hermes](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Antigravity%20%7C%20OpenClaw%20%7C%20Hermes-purple.svg)](#quickstart)
34
+
35
+ ---
36
+
37
+ ## The problem
38
+
39
+ Every session, an agent rediscovers the same things: which command runs the tests, which flag is mandatory, which file must never be edited by hand. It also retries failing commands far longer than it should. That is wasted time and tokens.
40
+
41
+ ## What Centsible does differently
42
+
43
+ | | Typical "memory" add-on | Centsible |
44
+ |---|---|---|
45
+ | **When a fact appears** | Loaded up front, always. | Injected for that turn only, when its trigger pattern matches the prompt or the tool call. |
46
+ | **What can be saved** | Anything. | One sentence, 240 characters max. Lone short keywords (`pytest`) and generic-word patterns are rejected because they would fire on unrelated prompts. |
47
+ | **Who writes facts** | You. | You, or the agent itself: it saves a hard-won gotcha in the same turn (no extra turn by default). |
48
+ | **Runaway loops** | Not handled. | Loop guard halts repeated errors and identical tool calls, with `ultra`, `normal` and `weak` presets. |
49
+ | **Savings claims** | A single headline number. | Separate lines for *trace-measured*, *attributed (verified)* and *heuristic* savings, so you can see how much is evidence and how much is an estimate. |
50
+
51
+ ## Measured on real usage
52
+
53
+ The numbers below come from `centsible stats` on one actively used repository (16 curated facts, 12,447 tool calls over several weeks). They are from real sessions, not a benchmark, and the "before/after" split is not a controlled experiment.
54
+
55
+ | Metric | Result | How it is measured |
56
+ |---|---|---|
57
+ | Tool calls observed | 12,447 | Transcript analysis |
58
+ | First-try success | 94.6% overall, 96.8% for shell commands | Transcript analysis |
59
+ | Runaway loops halted | 60 (about 120,000 trace tokens avoided) | Trace-measured |
60
+ | Net tokens saved, **verified** | **312,785** | Attributed: only facts the agent demonstrably applied |
61
+ | Facts verified as applied | 199 of 2,111 hits (9.4%) | Attribution |
62
+ | Exploration before first edit | median 31.0 calls / 22,109 tokens before facts, 28.0 calls / 18,138 tokens after (66 vs 20 sessions) | Measured split at the date facts were introduced |
63
+ | Net tokens saved, heuristic | 3,180,785 (upper bound) | Heuristic, unverified |
64
+
65
+ How to read this: the loop guard produces measured savings, and fact injection produces verified savings of a few hundred thousand tokens in this repo. The before/after split suggests roughly 4,000 fewer tokens (about 18%) of exploration per session, but the "after" group is only 20 sessions and other things changed over the same period. The large heuristic figure is an upper bound and should not be quoted as the benefit.
66
+
67
+ Results depend on fact quality. Across a set of 9 mixed repositories (3,425 tool calls), where only 4 facts were active, 2.6% of fact hits were verified as applied and verified savings were about 5,000 tokens. We have not isolated the cause, but the likely lever is having well-targeted facts for the repo you work in every day. Run `centsible stats` on your own sessions to get yours.
68
+
69
+ ## Quickstart
70
+
71
+ ### Claude Code
72
+
73
+ ```text
74
+ /plugin marketplace add ntrieuvi97/centsible
75
+ /plugin install centsible@centsible
76
+ ```
77
+
78
+ Then use `/centsible-stats`, `/centsible-status`, `/centsible-harvest` or `/centsible-config` in chat.
79
+
80
+ ### One-line installer (Linux and macOS)
81
+
82
+ ```bash
83
+ curl -fsSL https://raw.githubusercontent.com/ntrieuvi97/centsible/main/install.sh | bash
84
+ source ~/.zshrc # or ~/.bashrc
85
+ centsible stats
86
+ ```
87
+
88
+ ### Google Antigravity
89
+
90
+ ```bash
91
+ git clone https://github.com/ntrieuvi97/centsible.git ~/.gemini/config/plugins/centsible
92
+ ~/.gemini/config/plugins/centsible/install.sh
93
+ ```
94
+
95
+ ### Python (any OS, including Windows)
96
+
97
+ ```bash
98
+ pip install git+https://github.com/ntrieuvi97/centsible.git
99
+ centsible stats
100
+ ```
101
+
102
+ ### Hermes Agent
103
+
104
+ ```bash
105
+ centsible install --hermes # prints a `hooks:` block; edits nothing
106
+ ```
107
+
108
+ Merge the printed block into your profile's `config.yaml` (`$HERMES_HOME/config.yaml`), then approve the hooks once (start `hermes` and accept the prompt; `hermes hooks doctor` checks them). Centsible uses four Hermes shell hooks: `pre_llm_call` (fact injection), `pre_tool_call` (loop guard, budget, tool hints), `post_tool_call` (telemetry and recovery learning) and `pre_verify` (one save-the-gotcha nudge on turns that edited code).
109
+
110
+ Two differences from Claude Code: Hermes cannot attach context to a tool call it lets through, so a one-time fact hint blocks that one call and the agent retries with the hint as the tool result. Facts are also resolved from the directory Hermes runs in, so start Hermes from the repo.
111
+
112
+ ### First five minutes
113
+
114
+ ```bash
115
+ centsible harvest # scan a fresh repo and propose up to 5 starting facts (0 if nothing is unusual)
116
+ centsible facts add --pattern "pytest.{0,40}(fail|error)" --fact "Run with 'pytest tests/ -q --tb=short'."
117
+ centsible facts test "why does pytest fail?" # preview which facts would fire
118
+ centsible stats # see what it saved
119
+ ```
120
+
121
+ ## CLI cheat sheet
122
+
123
+ ```bash
124
+ centsible status
125
+ centsible stats [--all] [--rate 3.0] [--transcript session.jsonl] [--baseline DIR] [--since 2026-11-04] [--no-baseline]
126
+ centsible events [--days 7] [--agent main] [--json] # hint/block/apply counts; flags facts shown >=20x but never applied
127
+
128
+ centsible facts add --pattern "<regex>" --fact "<one line>" [--category gotcha] [--global]
129
+ centsible facts list
130
+ centsible facts test "<prompt>"
131
+ centsible facts prune [--days 30] [--min-hits 20] [--dry-run] # remove stale or zero-utility facts
132
+ centsible facts verify [--root DIR] # files named in facts still exist? exit 1 if a path is stale
133
+ centsible facts replay [--days 30] [--transcripts DIR] # replay past sessions: which facts never fire, fire too often, or are redundant
134
+ centsible facts tune [--days 30] [--transcripts DIR] [--apply] # suggest remove / narrow / merge from hits, applies and past sessions
135
+ centsible facts remove <id_or_pattern>
136
+
137
+ centsible config mode ultra # loop guard preset: ultra | normal | weak
138
+ centsible config reflect inline # inline (default, zero extra turns) | hook | off
139
+ centsible config set max_consecutive_errors 4
140
+ centsible config set session_budget_tokens 2000000 # per-session budget: warn at 80%, then block tool calls
141
+ centsible config set session_budget_calls 300
142
+ centsible config list
143
+ ```
144
+
145
+ Writing a good pattern: anchor on an identifier (`deploy_staging`, `run-e2e`, `a/b.py`), a tool plus a symptom (`pytest.{0,40}(fail|error)`), or an action plus object plus context. `--force` overrides the check for deliberately broad patterns.
146
+
147
+ `facts tune` only changes facts with `--apply`, and only the suggestions marked `[auto]`: removing facts that never fired or are redundant, removing exact duplicates, and dropping a `a|b` branch that fired in 3+ past sessions where the fact was never applied while another branch was. Everything else is printed as `[manual]`.
148
+
149
+ Session budgets are off by default. Token usage is measured from the transcript where the host provides one (Claude Code; cached reads count at 10%). On other hosts it is estimated from tool input and output only, which undercounts, so prefer `session_budget_calls` there. Once a limit is reached every further tool call in that session is blocked until you raise or unset it. `budget_warn` / `budget_stop` appear in `centsible events`.
150
+
151
+ Per-fact counters (`hits`, `attributed_hits`, ...) are stored beside the facts in `facts.stats.json`, so the facts file only changes when you change a fact and is safe to commit. Add `facts.stats.json` and `metrics.json` to `.gitignore`. Counters from older versions move over automatically on the next write.
152
+
153
+ Facts live in the project's `.agents/` or `.claude/` directory when present, otherwise in `~/.centsible/projects/<repo>-<hash>/` (scoped per repo, never shared). Facts added with `--global` live in `~/.centsible/facts.jsonl`; a project fact with the same id or pattern wins. Override the root with `CENTSIBLE_HOME`.
154
+
155
+ <details>
156
+ <summary>Example <code>centsible stats</code> output</summary>
157
+
158
+ ```text
159
+ === Centsible Efficiency & ROI Report 🪙 ===
160
+ • Active Micro-Facts: 16 (Auto-learned: 1)
161
+ • Total Fact Hits: 2111 (Prompt: 433, Pre-Tool Hints: 249)
162
+ • Fact Attribution: 199 verified applied (9.4% usage rate)
163
+ • Loop Interventions: 60 halted runaway loops (~120,000 trace tokens saved)
164
+ • Tool Execution: 12447 calls | 94.6% 1st-try success | 1.4% error rate
165
+ --- Token & Cost Accounting ---
166
+ • Discovery Saved: +3,166,500 tokens [Heuristic] | +298,500 tokens [Attributed]
167
+ • Loop Guard Saved: +120,000 tokens [Trace-measured]
168
+ • Ephemeral Overhead: -105,715 tokens
169
+ • Attributed Net Saved: 312,785 tokens [Verified]
170
+ • Net Tokens Saved: 3,180,785 tokens (ROI: 31.1x) [Heuristic, unverified upper bound]
171
+ --- Measured Exploration Cost (before vs after facts) ---
172
+ • Before: 66 sessions | median 31.0 calls / 22108.5 tokens before 1st edit
173
+ • After: 20 sessions | median 28.0 calls / 18137.5 tokens before 1st edit
174
+ • Measured Saving: +3.0 calls, +3971.0 tokens per session (negative = worse)
175
+ ```
176
+ </details>
177
+
178
+ ## How it works
179
+
180
+ ```text
181
+ 1. User prompt ──► [Prompt hook] ──► injects matching facts for this turn only
182
+ 2. Tool execution ──► [PreTool hook] ──► loop guard, CLI flag and file-gotcha checks
183
+ 3. Tool outcome ──► [PostTool hook] ──► telemetry, learns from successful recoveries
184
+ 4. Session end ──► [Stop hook] ──► one-shot reflection nudges the agent to save gotchas
185
+ ```
186
+
187
+ ## Languages
188
+
189
+ "Save this rule" detection (e.g. "never edit `a.py`") ships with English, Vietnamese, Spanish, Portuguese, French, German, Russian, Indonesian, Chinese, Japanese and Korean phrases in `core/triggers.json`. To add or extend a language without a release, put a file with the same shape in `~/.centsible/triggers.json` (or `$CENTSIBLE_HOME/triggers.json`):
190
+
191
+ ```json
192
+ { "nl": { "correction": ["gebruik\\s+nooit", "zorg\\s+voor"], "question_start": ["waarom", "hoe"] } }
193
+ ```
194
+
195
+ Fact patterns themselves are plain regexes and work in any language.
196
+
197
+ ## Limits
198
+
199
+ - Facts only help when their patterns match. Even in the best case above, 9.4% of hits were verified as applied, so most injections are not used. That is why `facts prune` and `centsible events` exist.
200
+ - Savings figures labelled *Heuristic* are estimates. Treat *Verified* and *Trace-measured* as the numbers you can rely on.
201
+ - Transcript analysis supports the agents listed above; other agents may need `--transcript`.
202
+
203
+ ## Develop
204
+
205
+ ```bash
206
+ git clone https://github.com/ntrieuvi97/centsible.git && cd centsible
207
+ python3 -m pip install -e . pytest
208
+ python3 -m pytest -q # or: python3 -m unittest discover tests
209
+ ```
210
+
211
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Related project: [Thauthi](https://github.com/ntrieuvi97/thauthi), runtime-aware tooling for AI coding agents.
212
+
213
+ ## License
214
+
215
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,192 @@
1
+ # centsible 🪙
2
+
3
+ **Repo memory and loop guard for AI coding agents, with savings reported as *verified* vs *estimated*.** Centsible stores one-line repo facts, injects each only when the situation matches, stops runaway retry loops, and tells you how many tokens it actually saved. Standard library only.
4
+
5
+ [![CI](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml/badge.svg)](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml)
6
+ [![Version: 0.10.0](https://img.shields.io/badge/Version-0.10.0-orange.svg)](#)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
8
+ [![Python: 3.9+](https://img.shields.io/badge/python-3.9%2B-green.svg)](https://www.python.org/)
9
+ [![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#)
10
+ [![Works with: Claude Code | Antigravity | OpenClaw | Hermes](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Antigravity%20%7C%20OpenClaw%20%7C%20Hermes-purple.svg)](#quickstart)
11
+
12
+ ---
13
+
14
+ ## The problem
15
+
16
+ Every session, an agent rediscovers the same things: which command runs the tests, which flag is mandatory, which file must never be edited by hand. It also retries failing commands far longer than it should. That is wasted time and tokens.
17
+
18
+ ## What Centsible does differently
19
+
20
+ | | Typical "memory" add-on | Centsible |
21
+ |---|---|---|
22
+ | **When a fact appears** | Loaded up front, always. | Injected for that turn only, when its trigger pattern matches the prompt or the tool call. |
23
+ | **What can be saved** | Anything. | One sentence, 240 characters max. Lone short keywords (`pytest`) and generic-word patterns are rejected because they would fire on unrelated prompts. |
24
+ | **Who writes facts** | You. | You, or the agent itself: it saves a hard-won gotcha in the same turn (no extra turn by default). |
25
+ | **Runaway loops** | Not handled. | Loop guard halts repeated errors and identical tool calls, with `ultra`, `normal` and `weak` presets. |
26
+ | **Savings claims** | A single headline number. | Separate lines for *trace-measured*, *attributed (verified)* and *heuristic* savings, so you can see how much is evidence and how much is an estimate. |
27
+
28
+ ## Measured on real usage
29
+
30
+ The numbers below come from `centsible stats` on one actively used repository (16 curated facts, 12,447 tool calls over several weeks). They are from real sessions, not a benchmark, and the "before/after" split is not a controlled experiment.
31
+
32
+ | Metric | Result | How it is measured |
33
+ |---|---|---|
34
+ | Tool calls observed | 12,447 | Transcript analysis |
35
+ | First-try success | 94.6% overall, 96.8% for shell commands | Transcript analysis |
36
+ | Runaway loops halted | 60 (about 120,000 trace tokens avoided) | Trace-measured |
37
+ | Net tokens saved, **verified** | **312,785** | Attributed: only facts the agent demonstrably applied |
38
+ | Facts verified as applied | 199 of 2,111 hits (9.4%) | Attribution |
39
+ | Exploration before first edit | median 31.0 calls / 22,109 tokens before facts, 28.0 calls / 18,138 tokens after (66 vs 20 sessions) | Measured split at the date facts were introduced |
40
+ | Net tokens saved, heuristic | 3,180,785 (upper bound) | Heuristic, unverified |
41
+
42
+ How to read this: the loop guard produces measured savings, and fact injection produces verified savings of a few hundred thousand tokens in this repo. The before/after split suggests roughly 4,000 fewer tokens (about 18%) of exploration per session, but the "after" group is only 20 sessions and other things changed over the same period. The large heuristic figure is an upper bound and should not be quoted as the benefit.
43
+
44
+ Results depend on fact quality. Across a set of 9 mixed repositories (3,425 tool calls), where only 4 facts were active, 2.6% of fact hits were verified as applied and verified savings were about 5,000 tokens. We have not isolated the cause, but the likely lever is having well-targeted facts for the repo you work in every day. Run `centsible stats` on your own sessions to get yours.
45
+
46
+ ## Quickstart
47
+
48
+ ### Claude Code
49
+
50
+ ```text
51
+ /plugin marketplace add ntrieuvi97/centsible
52
+ /plugin install centsible@centsible
53
+ ```
54
+
55
+ Then use `/centsible-stats`, `/centsible-status`, `/centsible-harvest` or `/centsible-config` in chat.
56
+
57
+ ### One-line installer (Linux and macOS)
58
+
59
+ ```bash
60
+ curl -fsSL https://raw.githubusercontent.com/ntrieuvi97/centsible/main/install.sh | bash
61
+ source ~/.zshrc # or ~/.bashrc
62
+ centsible stats
63
+ ```
64
+
65
+ ### Google Antigravity
66
+
67
+ ```bash
68
+ git clone https://github.com/ntrieuvi97/centsible.git ~/.gemini/config/plugins/centsible
69
+ ~/.gemini/config/plugins/centsible/install.sh
70
+ ```
71
+
72
+ ### Python (any OS, including Windows)
73
+
74
+ ```bash
75
+ pip install git+https://github.com/ntrieuvi97/centsible.git
76
+ centsible stats
77
+ ```
78
+
79
+ ### Hermes Agent
80
+
81
+ ```bash
82
+ centsible install --hermes # prints a `hooks:` block; edits nothing
83
+ ```
84
+
85
+ Merge the printed block into your profile's `config.yaml` (`$HERMES_HOME/config.yaml`), then approve the hooks once (start `hermes` and accept the prompt; `hermes hooks doctor` checks them). Centsible uses four Hermes shell hooks: `pre_llm_call` (fact injection), `pre_tool_call` (loop guard, budget, tool hints), `post_tool_call` (telemetry and recovery learning) and `pre_verify` (one save-the-gotcha nudge on turns that edited code).
86
+
87
+ Two differences from Claude Code: Hermes cannot attach context to a tool call it lets through, so a one-time fact hint blocks that one call and the agent retries with the hint as the tool result. Facts are also resolved from the directory Hermes runs in, so start Hermes from the repo.
88
+
89
+ ### First five minutes
90
+
91
+ ```bash
92
+ centsible harvest # scan a fresh repo and propose up to 5 starting facts (0 if nothing is unusual)
93
+ centsible facts add --pattern "pytest.{0,40}(fail|error)" --fact "Run with 'pytest tests/ -q --tb=short'."
94
+ centsible facts test "why does pytest fail?" # preview which facts would fire
95
+ centsible stats # see what it saved
96
+ ```
97
+
98
+ ## CLI cheat sheet
99
+
100
+ ```bash
101
+ centsible status
102
+ centsible stats [--all] [--rate 3.0] [--transcript session.jsonl] [--baseline DIR] [--since 2026-11-04] [--no-baseline]
103
+ centsible events [--days 7] [--agent main] [--json] # hint/block/apply counts; flags facts shown >=20x but never applied
104
+
105
+ centsible facts add --pattern "<regex>" --fact "<one line>" [--category gotcha] [--global]
106
+ centsible facts list
107
+ centsible facts test "<prompt>"
108
+ centsible facts prune [--days 30] [--min-hits 20] [--dry-run] # remove stale or zero-utility facts
109
+ centsible facts verify [--root DIR] # files named in facts still exist? exit 1 if a path is stale
110
+ centsible facts replay [--days 30] [--transcripts DIR] # replay past sessions: which facts never fire, fire too often, or are redundant
111
+ centsible facts tune [--days 30] [--transcripts DIR] [--apply] # suggest remove / narrow / merge from hits, applies and past sessions
112
+ centsible facts remove <id_or_pattern>
113
+
114
+ centsible config mode ultra # loop guard preset: ultra | normal | weak
115
+ centsible config reflect inline # inline (default, zero extra turns) | hook | off
116
+ centsible config set max_consecutive_errors 4
117
+ centsible config set session_budget_tokens 2000000 # per-session budget: warn at 80%, then block tool calls
118
+ centsible config set session_budget_calls 300
119
+ centsible config list
120
+ ```
121
+
122
+ Writing a good pattern: anchor on an identifier (`deploy_staging`, `run-e2e`, `a/b.py`), a tool plus a symptom (`pytest.{0,40}(fail|error)`), or an action plus object plus context. `--force` overrides the check for deliberately broad patterns.
123
+
124
+ `facts tune` only changes facts with `--apply`, and only the suggestions marked `[auto]`: removing facts that never fired or are redundant, removing exact duplicates, and dropping a `a|b` branch that fired in 3+ past sessions where the fact was never applied while another branch was. Everything else is printed as `[manual]`.
125
+
126
+ Session budgets are off by default. Token usage is measured from the transcript where the host provides one (Claude Code; cached reads count at 10%). On other hosts it is estimated from tool input and output only, which undercounts, so prefer `session_budget_calls` there. Once a limit is reached every further tool call in that session is blocked until you raise or unset it. `budget_warn` / `budget_stop` appear in `centsible events`.
127
+
128
+ Per-fact counters (`hits`, `attributed_hits`, ...) are stored beside the facts in `facts.stats.json`, so the facts file only changes when you change a fact and is safe to commit. Add `facts.stats.json` and `metrics.json` to `.gitignore`. Counters from older versions move over automatically on the next write.
129
+
130
+ Facts live in the project's `.agents/` or `.claude/` directory when present, otherwise in `~/.centsible/projects/<repo>-<hash>/` (scoped per repo, never shared). Facts added with `--global` live in `~/.centsible/facts.jsonl`; a project fact with the same id or pattern wins. Override the root with `CENTSIBLE_HOME`.
131
+
132
+ <details>
133
+ <summary>Example <code>centsible stats</code> output</summary>
134
+
135
+ ```text
136
+ === Centsible Efficiency & ROI Report 🪙 ===
137
+ • Active Micro-Facts: 16 (Auto-learned: 1)
138
+ • Total Fact Hits: 2111 (Prompt: 433, Pre-Tool Hints: 249)
139
+ • Fact Attribution: 199 verified applied (9.4% usage rate)
140
+ • Loop Interventions: 60 halted runaway loops (~120,000 trace tokens saved)
141
+ • Tool Execution: 12447 calls | 94.6% 1st-try success | 1.4% error rate
142
+ --- Token & Cost Accounting ---
143
+ • Discovery Saved: +3,166,500 tokens [Heuristic] | +298,500 tokens [Attributed]
144
+ • Loop Guard Saved: +120,000 tokens [Trace-measured]
145
+ • Ephemeral Overhead: -105,715 tokens
146
+ • Attributed Net Saved: 312,785 tokens [Verified]
147
+ • Net Tokens Saved: 3,180,785 tokens (ROI: 31.1x) [Heuristic, unverified upper bound]
148
+ --- Measured Exploration Cost (before vs after facts) ---
149
+ • Before: 66 sessions | median 31.0 calls / 22108.5 tokens before 1st edit
150
+ • After: 20 sessions | median 28.0 calls / 18137.5 tokens before 1st edit
151
+ • Measured Saving: +3.0 calls, +3971.0 tokens per session (negative = worse)
152
+ ```
153
+ </details>
154
+
155
+ ## How it works
156
+
157
+ ```text
158
+ 1. User prompt ──► [Prompt hook] ──► injects matching facts for this turn only
159
+ 2. Tool execution ──► [PreTool hook] ──► loop guard, CLI flag and file-gotcha checks
160
+ 3. Tool outcome ──► [PostTool hook] ──► telemetry, learns from successful recoveries
161
+ 4. Session end ──► [Stop hook] ──► one-shot reflection nudges the agent to save gotchas
162
+ ```
163
+
164
+ ## Languages
165
+
166
+ "Save this rule" detection (e.g. "never edit `a.py`") ships with English, Vietnamese, Spanish, Portuguese, French, German, Russian, Indonesian, Chinese, Japanese and Korean phrases in `core/triggers.json`. To add or extend a language without a release, put a file with the same shape in `~/.centsible/triggers.json` (or `$CENTSIBLE_HOME/triggers.json`):
167
+
168
+ ```json
169
+ { "nl": { "correction": ["gebruik\\s+nooit", "zorg\\s+voor"], "question_start": ["waarom", "hoe"] } }
170
+ ```
171
+
172
+ Fact patterns themselves are plain regexes and work in any language.
173
+
174
+ ## Limits
175
+
176
+ - Facts only help when their patterns match. Even in the best case above, 9.4% of hits were verified as applied, so most injections are not used. That is why `facts prune` and `centsible events` exist.
177
+ - Savings figures labelled *Heuristic* are estimates. Treat *Verified* and *Trace-measured* as the numbers you can rely on.
178
+ - Transcript analysis supports the agents listed above; other agents may need `--transcript`.
179
+
180
+ ## Develop
181
+
182
+ ```bash
183
+ git clone https://github.com/ntrieuvi97/centsible.git && cd centsible
184
+ python3 -m pip install -e . pytest
185
+ python3 -m pytest -q # or: python3 -m unittest discover tests
186
+ ```
187
+
188
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Related project: [Thauthi](https://github.com/ntrieuvi97/thauthi), runtime-aware tooling for AI coding agents.
189
+
190
+ ## License
191
+
192
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,4 @@
1
+ """Centsible package entrypoint."""
2
+ from core.cli import main
3
+
4
+ __all__ = ["main"]
@@ -0,0 +1,12 @@
1
+ """Main execution entrypoint for python3 -m centsible."""
2
+ import sys
3
+ from pathlib import Path
4
+
5
+ REPO_ROOT = Path(__file__).resolve().parent.parent
6
+ if str(REPO_ROOT) not in sys.path:
7
+ sys.path.insert(0, str(REPO_ROOT))
8
+
9
+ from core.cli import main
10
+
11
+ if __name__ == "__main__":
12
+ sys.exit(main())