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.
- centsible-0.10.0/LICENSE +21 -0
- centsible-0.10.0/PKG-INFO +215 -0
- centsible-0.10.0/README.md +192 -0
- centsible-0.10.0/centsible/__init__.py +4 -0
- centsible-0.10.0/centsible/__main__.py +12 -0
- centsible-0.10.0/centsible.egg-info/PKG-INFO +215 -0
- centsible-0.10.0/centsible.egg-info/SOURCES.txt +40 -0
- centsible-0.10.0/centsible.egg-info/dependency_links.txt +1 -0
- centsible-0.10.0/centsible.egg-info/entry_points.txt +2 -0
- centsible-0.10.0/centsible.egg-info/top_level.txt +2 -0
- centsible-0.10.0/core/__init__.py +5 -0
- centsible-0.10.0/core/budget.py +104 -0
- centsible-0.10.0/core/cli.py +104 -0
- centsible-0.10.0/core/cli_parser.py +157 -0
- centsible-0.10.0/core/commands.py +434 -0
- centsible-0.10.0/core/event_log.py +84 -0
- centsible-0.10.0/core/fact_audit.py +178 -0
- centsible-0.10.0/core/fact_helpers.py +819 -0
- centsible-0.10.0/core/fact_tune.py +197 -0
- centsible-0.10.0/core/facts_engine.py +803 -0
- centsible-0.10.0/core/hooks.py +371 -0
- centsible-0.10.0/core/install.py +204 -0
- centsible-0.10.0/core/loop_guard.py +841 -0
- centsible-0.10.0/core/share.py +146 -0
- centsible-0.10.0/core/transcript.py +197 -0
- centsible-0.10.0/core/triggers.json +93 -0
- centsible-0.10.0/pyproject.toml +40 -0
- centsible-0.10.0/setup.cfg +4 -0
- centsible-0.10.0/tests/test_attribution_and_metrics.py +302 -0
- centsible-0.10.0/tests/test_baseline.py +91 -0
- centsible-0.10.0/tests/test_budget.py +123 -0
- centsible-0.10.0/tests/test_claude_integration.py +294 -0
- centsible-0.10.0/tests/test_cli_integration.py +451 -0
- centsible-0.10.0/tests/test_concurrency.py +39 -0
- centsible-0.10.0/tests/test_event_log.py +81 -0
- centsible-0.10.0/tests/test_fact_audit.py +75 -0
- centsible-0.10.0/tests/test_fact_tune.py +88 -0
- centsible-0.10.0/tests/test_facts_engine.py +636 -0
- centsible-0.10.0/tests/test_hermes_integration.py +82 -0
- centsible-0.10.0/tests/test_loop_guard.py +319 -0
- centsible-0.10.0/tests/test_tool_recovery.py +232 -0
- centsible-0.10.0/tests/test_version_sync.py +27 -0
centsible-0.10.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml)
|
|
29
|
+
[](#)
|
|
30
|
+
[](LICENSE)
|
|
31
|
+
[](https://www.python.org/)
|
|
32
|
+
[](#)
|
|
33
|
+
[](#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
|
+
[](https://github.com/ntrieuvi97/centsible/actions/workflows/ci.yml)
|
|
6
|
+
[](#)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://www.python.org/)
|
|
9
|
+
[](#)
|
|
10
|
+
[](#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,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())
|