buildlog 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl
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.
- buildlog/cli.py +46 -23
- buildlog/core/operations.py +11 -15
- buildlog/distill.py +3 -3
- buildlog/embeddings.py +108 -16
- buildlog/mcp/tools.py +4 -4
- buildlog/render/__init__.py +34 -11
- buildlog/render/claude_md.py +3 -24
- buildlog/render/settings_json.py +3 -23
- buildlog/render/skill.py +175 -0
- buildlog/render/tracking.py +43 -0
- buildlog/skills.py +118 -37
- buildlog/stats.py +7 -5
- buildlog-0.2.0.dist-info/METADATA +762 -0
- buildlog-0.2.0.dist-info/RECORD +29 -0
- buildlog-0.1.0.dist-info/METADATA +0 -664
- buildlog-0.1.0.dist-info/RECORD +0 -27
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/copier.yml +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/post_gen.py +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/template/buildlog/.gitkeep +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/template/buildlog/2026-01-01-example.md +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/template/buildlog/_TEMPLATE.md +0 -0
- {buildlog-0.1.0.data → buildlog-0.2.0.data}/data/share/buildlog/template/buildlog/assets/.gitkeep +0 -0
- {buildlog-0.1.0.dist-info → buildlog-0.2.0.dist-info}/WHEEL +0 -0
- {buildlog-0.1.0.dist-info → buildlog-0.2.0.dist-info}/entry_points.txt +0 -0
- {buildlog-0.1.0.dist-info → buildlog-0.2.0.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
buildlog/__init__.py,sha256=FrgjyZhC19YyB40rOXHJWTA4xKWx2Yn2heIhVraaZ7A,90
|
|
2
|
+
buildlog/cli.py,sha256=cmg77_RVJx8mdtStApS1KXxBUUB8Id6psHZjtHo33iE,14350
|
|
3
|
+
buildlog/distill.py,sha256=fqXW_YyBFIFhwIWhnR-TQ7U65gypqG-mcAzNBr-qaag,11262
|
|
4
|
+
buildlog/embeddings.py,sha256=vPydWjJVkYp172zFou-lJ737qsu6vRMQAMs143RGIpA,12364
|
|
5
|
+
buildlog/skills.py,sha256=gu26MuIBgo-Jm6GQcVvbXHmV6MNp-HX3h7WC5buiyJ8,20686
|
|
6
|
+
buildlog/stats.py,sha256=2WdHdmzUNGobtWngmm9nA_UmqM7DQeAnZL8_rLQN8aw,13256
|
|
7
|
+
buildlog/core/__init__.py,sha256=07N1gRiPQQTBtLp9rsEErh39sgXWZSlEKWBn708SoQk,412
|
|
8
|
+
buildlog/core/operations.py,sha256=o01z2Sy0fgiBK6Z90Lkg6ACoqihH3-HC-hkPBSdj9mA,10656
|
|
9
|
+
buildlog/mcp/__init__.py,sha256=Eaoa7aRWa428ORxyvneH1cKW7XxuBpF4qvM9mTEH7Ds,268
|
|
10
|
+
buildlog/mcp/server.py,sha256=sgEMYBYq1tNKddvtyTpQ_M1dZHj7FhePDzwz7saIPH0,512
|
|
11
|
+
buildlog/mcp/tools.py,sha256=KbO1NjogCWHECTIzFYSeAikJGG8fIMDNDOBicdKXDdY,2818
|
|
12
|
+
buildlog/render/__init__.py,sha256=VxJWEmcX7pSiC3W-ytsHv9gNVUr4hJrVHBW084kEnAI,1993
|
|
13
|
+
buildlog/render/base.py,sha256=gQfvOsH1zttAo10xtEyNsAbqZ4NRSPiDihO-aiGgTsw,533
|
|
14
|
+
buildlog/render/claude_md.py,sha256=Z_E6MbJyVM_hJSoB4KL2rvbt5UEQHekTpJijj106lsI,2624
|
|
15
|
+
buildlog/render/settings_json.py,sha256=4DS5OWksPrFCa7MIgWIu0t4rxYmItpMdGfTqMX3aMNs,2495
|
|
16
|
+
buildlog/render/skill.py,sha256=_7umIS1Ms1oQ2_PopYueFjX41nMq1p28yJp6DhXFdgU,5981
|
|
17
|
+
buildlog/render/tracking.py,sha256=6O0RIU-1gjVG-_S5dmXLz6RCMsQoHOR2u5___UpqXEo,1294
|
|
18
|
+
buildlog-0.2.0.data/data/share/buildlog/copier.yml,sha256=A-1JKV59kOe0BQosGUBgRCg7iQozP_qyA3zfoHwpBKY,927
|
|
19
|
+
buildlog-0.2.0.data/data/share/buildlog/post_gen.py,sha256=ffVG-1MMXbffKT8OMNvaQmyVDcBjwD8qTYpCaoyyZAQ,1778
|
|
20
|
+
buildlog-0.2.0.data/data/share/buildlog/template/buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
21
|
+
buildlog-0.2.0.data/data/share/buildlog/template/buildlog/2026-01-01-example.md,sha256=7x9sKmydfmfKyNz9hV7MtYnQJuBwbxNanbPOcpQDDZQ,7040
|
|
22
|
+
buildlog-0.2.0.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md,sha256=osclytWwl5jUiTgSpuT4cT3h3oPvCkZ5GPCnFuJZNcY,3802
|
|
23
|
+
buildlog-0.2.0.data/data/share/buildlog/template/buildlog/_TEMPLATE.md,sha256=CUvxgcx1-9XT_EdQ8e_vnuPq_h-u1uhXJgForJU2Pso,2932
|
|
24
|
+
buildlog-0.2.0.data/data/share/buildlog/template/buildlog/assets/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
25
|
+
buildlog-0.2.0.dist-info/METADATA,sha256=pRmXAYYlZhVCwjRXdbTQdtmf8Bz2KijyBGHn65hPYKQ,24161
|
|
26
|
+
buildlog-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
27
|
+
buildlog-0.2.0.dist-info/entry_points.txt,sha256=BMFclPOomp_sgaa0OqBg6LfqCMlqzjZV88ww5TrPPoo,87
|
|
28
|
+
buildlog-0.2.0.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
|
|
29
|
+
buildlog-0.2.0.dist-info/RECORD,,
|
|
@@ -1,664 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: buildlog
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Engineering notebook for AI-assisted development
|
|
5
|
-
Project-URL: Homepage, https://github.com/Peleke/buildlog-template
|
|
6
|
-
Project-URL: Repository, https://github.com/Peleke/buildlog-template
|
|
7
|
-
Author: Peleke Sengstacke
|
|
8
|
-
License-Expression: MIT
|
|
9
|
-
License-File: LICENSE
|
|
10
|
-
Keywords: ai,buildlog,development,documentation,journal
|
|
11
|
-
Classifier: Development Status :: 4 - Beta
|
|
12
|
-
Classifier: Environment :: Console
|
|
13
|
-
Classifier: Intended Audience :: Developers
|
|
14
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
-
Classifier: Programming Language :: Python :: 3
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
-
Classifier: Topic :: Documentation
|
|
21
|
-
Classifier: Topic :: Software Development :: Documentation
|
|
22
|
-
Requires-Python: >=3.10
|
|
23
|
-
Requires-Dist: click>=8.0.0
|
|
24
|
-
Requires-Dist: copier>=9.0.0
|
|
25
|
-
Requires-Dist: numpy>=1.21.0
|
|
26
|
-
Requires-Dist: pyyaml>=6.0.0
|
|
27
|
-
Provides-Extra: all
|
|
28
|
-
Requires-Dist: mcp>=1.0.0; extra == 'all'
|
|
29
|
-
Requires-Dist: openai>=1.0.0; extra == 'all'
|
|
30
|
-
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
|
|
31
|
-
Provides-Extra: dev
|
|
32
|
-
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
|
|
33
|
-
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
|
|
34
|
-
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
35
|
-
Provides-Extra: embeddings
|
|
36
|
-
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
|
|
37
|
-
Provides-Extra: mcp
|
|
38
|
-
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
|
|
39
|
-
Provides-Extra: openai
|
|
40
|
-
Requires-Dist: openai>=1.0.0; extra == 'openai'
|
|
41
|
-
Description-Content-Type: text/markdown
|
|
42
|
-
|
|
43
|
-
<div align="center">
|
|
44
|
-
|
|
45
|
-
# buildlog
|
|
46
|
-
|
|
47
|
-
### Engineering Notebook for AI-Assisted Development
|
|
48
|
-
|
|
49
|
-
[](https://pypi.org/project/buildlog/)
|
|
50
|
-
[](https://python.org/)
|
|
51
|
-
[](https://opensource.org/licenses/MIT)
|
|
52
|
-
|
|
53
|
-
**Capture your work as publishable content. Include the fuckups.**
|
|
54
|
-
|
|
55
|
-
<img src="assets/hero.png" alt="Chaos to Order - buildlog transforms messy development sessions into structured knowledge" width="800"/>
|
|
56
|
-
|
|
57
|
-
[Quick Start](#-quick-start) · [The Pipeline](#-the-pipeline) · [Commands](#-commands) · [Philosophy](#-philosophy)
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
</div>
|
|
62
|
-
|
|
63
|
-
## The Problem
|
|
64
|
-
|
|
65
|
-
You're pairing with AI on real work. Hours of debugging, wrong turns, "oh shit" moments, and hard-won insights—all vanishing into chat history the moment you close the tab.
|
|
66
|
-
|
|
67
|
-
Meanwhile, your AI agent makes the same mistakes on similar problems because it has no memory of what you learned together.
|
|
68
|
-
|
|
69
|
-
## The Solution
|
|
70
|
-
|
|
71
|
-
**buildlog** captures the signal from AI-assisted development sessions and transforms it into:
|
|
72
|
-
|
|
73
|
-
1. **Publishable content** - Each entry is a $500+ tutorial draft
|
|
74
|
-
2. **Structured patterns** - Categorized insights ready for analysis
|
|
75
|
-
3. **Agent-consumable skills** - Deduplicated rules that can improve future AI behavior
|
|
76
|
-
|
|
77
|
-
```
|
|
78
|
-
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
79
|
-
│ Raw Sessions │ ──▶ │ Buildlog Entry │ ──▶ │ Agent Skills │
|
|
80
|
-
│ (ephemeral) │ │ (structured) │ │ (actionable) │
|
|
81
|
-
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
82
|
-
Chat logs Markdown files YAML/JSON rules
|
|
83
|
-
Screen shares with categories that agents can
|
|
84
|
-
Debugging noise and improvements actually use
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
---
|
|
88
|
-
|
|
89
|
-
## ✨ Features
|
|
90
|
-
|
|
91
|
-
### 📝 Structured Capture
|
|
92
|
-
Templates with six required sections ensure you never forget to document the mistakes that teach the most.
|
|
93
|
-
|
|
94
|
-
### 📊 Pattern Distillation
|
|
95
|
-
Extract categorized insights from all your entries into structured JSON/YAML for analysis.
|
|
96
|
-
|
|
97
|
-
### 🧠 Semantic Deduplication
|
|
98
|
-
"Run tests before commit" and "Always execute the test suite prior to committing" are the same insight. buildlog merges them.
|
|
99
|
-
|
|
100
|
-
### 🤖 Agent-Ready Skills
|
|
101
|
-
Generate rules your AI agent can consume—with stable IDs, confidence scores, and source tracking.
|
|
102
|
-
|
|
103
|
-
### 🔌 Pluggable Embeddings
|
|
104
|
-
Token-based similarity by default. Upgrade to sentence-transformers or OpenAI for semantic understanding.
|
|
105
|
-
|
|
106
|
-
---
|
|
107
|
-
|
|
108
|
-
## 🚀 Quick Start
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
# Install
|
|
112
|
-
pip install buildlog
|
|
113
|
-
|
|
114
|
-
# Initialize in your project
|
|
115
|
-
buildlog init
|
|
116
|
-
|
|
117
|
-
# Create an entry for today's work
|
|
118
|
-
buildlog new auth-api
|
|
119
|
-
|
|
120
|
-
# After a few entries, extract patterns
|
|
121
|
-
buildlog distill
|
|
122
|
-
|
|
123
|
-
# Generate agent-consumable skills
|
|
124
|
-
buildlog skills
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
## 🔄 The Pipeline
|
|
130
|
-
|
|
131
|
-
buildlog is a three-stage pipeline that transforms ephemeral work into durable knowledge:
|
|
132
|
-
|
|
133
|
-
### Stage 1: Capture (`buildlog new`)
|
|
134
|
-
|
|
135
|
-
Create structured entries as you work. Each entry has six sections:
|
|
136
|
-
|
|
137
|
-
| Section | Purpose |
|
|
138
|
-
|---------|---------|
|
|
139
|
-
| **The Goal** | What you're building and why |
|
|
140
|
-
| **What We Built** | Architecture diagram, components |
|
|
141
|
-
| **The Journey** | Chronological narrative *including mistakes* |
|
|
142
|
-
| **Test Results** | Actual commands, actual outputs |
|
|
143
|
-
| **Code Samples** | Key snippets with context |
|
|
144
|
-
| **Improvements** | Categorized learnings for next time |
|
|
145
|
-
|
|
146
|
-
The **Improvements** section is structured for machine extraction:
|
|
147
|
-
|
|
148
|
-
```markdown
|
|
149
|
-
### Architectural
|
|
150
|
-
- Always validate inputs at the boundary, not conditionally
|
|
151
|
-
- Use frozen dataclasses for immutable data containers
|
|
152
|
-
|
|
153
|
-
### Workflow
|
|
154
|
-
- Run the test suite after EVERY code change, not just at the end
|
|
155
|
-
- Write the integration test first to clarify the API contract
|
|
156
|
-
|
|
157
|
-
### Tool Usage
|
|
158
|
-
- The `patch` context manager for date mocking is cleaner than fixtures
|
|
159
|
-
- Use `jwt.io` to decode tokens instead of console.log
|
|
160
|
-
|
|
161
|
-
### Domain Knowledge
|
|
162
|
-
- `datetime.utcnow()` is deprecated in Python 3.12+
|
|
163
|
-
- Supabase storage returns 400, not 404, for missing files
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
### Stage 2: Distill (`buildlog distill`)
|
|
167
|
-
|
|
168
|
-
Extract all improvements across entries into structured data:
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
buildlog distill # JSON to stdout
|
|
172
|
-
buildlog distill -o patterns.yaml # Write to file
|
|
173
|
-
buildlog distill --since 2026-01-01 # Filter by date
|
|
174
|
-
buildlog distill --category workflow # Filter by category
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
Output:
|
|
178
|
-
```json
|
|
179
|
-
{
|
|
180
|
-
"patterns": {
|
|
181
|
-
"architectural": [
|
|
182
|
-
{"insight": "Always validate inputs at boundary...", "source": "2026-01-16-auth.md"}
|
|
183
|
-
],
|
|
184
|
-
"workflow": [...],
|
|
185
|
-
"tool_usage": [...],
|
|
186
|
-
"domain_knowledge": [...]
|
|
187
|
-
},
|
|
188
|
-
"statistics": {
|
|
189
|
-
"total_patterns": 47,
|
|
190
|
-
"by_category": {"architectural": 12, "workflow": 15, ...}
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
### Stage 3: Skills (`buildlog skills`)
|
|
196
|
-
|
|
197
|
-
Transform raw patterns into deduplicated, scored rules:
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
buildlog skills # YAML to stdout
|
|
201
|
-
buildlog skills -o skills.yml # Write to file
|
|
202
|
-
buildlog skills --format markdown # For CLAUDE.md injection
|
|
203
|
-
buildlog skills --min-frequency 2 # Only repeated patterns
|
|
204
|
-
buildlog skills --embeddings openai # Semantic deduplication
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Output:
|
|
208
|
-
```yaml
|
|
209
|
-
generated_at: '2026-01-16T12:00:00Z'
|
|
210
|
-
source_entries: 23
|
|
211
|
-
total_skills: 31
|
|
212
|
-
skills:
|
|
213
|
-
architectural:
|
|
214
|
-
- id: arch-b0fcb62a1e
|
|
215
|
-
rule: Always validate inputs at the boundary, not conditionally
|
|
216
|
-
frequency: 4
|
|
217
|
-
confidence: high
|
|
218
|
-
sources: [auth.md, api.md, validation.md, forms.md]
|
|
219
|
-
tags: [api, error]
|
|
220
|
-
- id: arch-0cda924aeb
|
|
221
|
-
rule: Frozen dataclasses should be the default for data containers
|
|
222
|
-
frequency: 2
|
|
223
|
-
confidence: medium
|
|
224
|
-
sources: [models.md, dto.md]
|
|
225
|
-
tags: [python]
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
---
|
|
229
|
-
|
|
230
|
-
## 🧠 Patterns vs Skills
|
|
231
|
-
|
|
232
|
-
**Patterns** are raw extractions—every insight from every entry, exactly as written.
|
|
233
|
-
|
|
234
|
-
**Skills** are processed rules with:
|
|
235
|
-
|
|
236
|
-
| Property | Description |
|
|
237
|
-
|----------|-------------|
|
|
238
|
-
| **Stable ID** | Same rule always gets same ID (SHA-256 based) |
|
|
239
|
-
| **Deduplication** | Similar insights merged, frequency tracked |
|
|
240
|
-
| **Confidence** | high/medium/low based on frequency + recency |
|
|
241
|
-
| **Sources** | Which entries contributed to this skill |
|
|
242
|
-
| **Tags** | Auto-extracted technology/concept keywords |
|
|
243
|
-
|
|
244
|
-
### Deduplication in Action
|
|
245
|
-
|
|
246
|
-
Raw patterns from different entries:
|
|
247
|
-
```
|
|
248
|
-
- "Run tests before committing"
|
|
249
|
-
- "Always run the test suite before commit"
|
|
250
|
-
- "Execute tests prior to committing code"
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
After deduplication → **1 skill** with `frequency: 3`:
|
|
254
|
-
```yaml
|
|
255
|
-
- id: wf-96f12966f1
|
|
256
|
-
rule: Run tests before committing
|
|
257
|
-
frequency: 3
|
|
258
|
-
confidence: high
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
---
|
|
262
|
-
|
|
263
|
-
## 🔌 Embedding Backends
|
|
264
|
-
|
|
265
|
-
Deduplication uses text similarity. Choose your backend:
|
|
266
|
-
|
|
267
|
-
| Backend | Install | Use Case |
|
|
268
|
-
|---------|---------|----------|
|
|
269
|
-
| `token` (default) | Built-in | Fast, free, good for obvious duplicates |
|
|
270
|
-
| `sentence-transformers` | `pip install buildlog[embeddings]` | Local semantic similarity, no API calls |
|
|
271
|
-
| `openai` | `pip install buildlog[openai]` | Best quality, requires API key |
|
|
272
|
-
|
|
273
|
-
```bash
|
|
274
|
-
# Token-based (default) - catches "run tests" ≈ "run testing"
|
|
275
|
-
buildlog skills
|
|
276
|
-
|
|
277
|
-
# Semantic - catches "use Redis for caching" ≈ "cache data in Redis"
|
|
278
|
-
buildlog skills --embeddings sentence-transformers
|
|
279
|
-
|
|
280
|
-
# OpenAI - best quality semantic matching
|
|
281
|
-
export OPENAI_API_KEY=...
|
|
282
|
-
buildlog skills --embeddings openai
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
### Comparison
|
|
286
|
-
|
|
287
|
-
| Input | Token | OpenAI |
|
|
288
|
-
|-------|:-----:|:------:|
|
|
289
|
-
| "Run tests before commit" ≈ "Run testing before committing" | ✅ Merged | ✅ Merged |
|
|
290
|
-
| "Use Redis for caching" ≈ "Cache data in Redis" | ❌ Separate | ✅ Merged |
|
|
291
|
-
|
|
292
|
-
---
|
|
293
|
-
|
|
294
|
-
## 🤖 Practical Usage: Making Your Life Easier
|
|
295
|
-
|
|
296
|
-
### 1. Inject Skills into CLAUDE.md
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
buildlog skills --format markdown >> CLAUDE.md
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
Your AI agent now has access to every lesson you've learned:
|
|
303
|
-
|
|
304
|
-
```markdown
|
|
305
|
-
## Learned Skills
|
|
306
|
-
|
|
307
|
-
Based on 23 buildlog entries, 31 actionable skills have emerged:
|
|
308
|
-
|
|
309
|
-
### Architectural (8 skills)
|
|
310
|
-
- 🟢 **Always validate inputs at the boundary** (seen 4x)
|
|
311
|
-
- 🟡 **Use frozen dataclasses for data containers** (seen 2x)
|
|
312
|
-
|
|
313
|
-
### Workflow (12 skills)
|
|
314
|
-
- 🟢 **Run tests after EVERY code change** (seen 5x)
|
|
315
|
-
...
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### 2. Track Skill Evolution
|
|
319
|
-
|
|
320
|
-
Skills have stable IDs. Track which skills are reinforced over time:
|
|
321
|
-
|
|
322
|
-
```bash
|
|
323
|
-
# This week's new skills
|
|
324
|
-
buildlog skills --since 2026-01-10 -o this-week.yml
|
|
325
|
-
|
|
326
|
-
# Compare to baseline
|
|
327
|
-
diff baseline-skills.yml this-week.yml
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
### 3. Find Your Blind Spots
|
|
331
|
-
|
|
332
|
-
```bash
|
|
333
|
-
buildlog stats --detailed
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
```
|
|
337
|
-
📊 Buildlog Statistics
|
|
338
|
-
═══════════════════════════════════════
|
|
339
|
-
|
|
340
|
-
Entries: 23 total
|
|
341
|
-
Coverage: 87% with improvements
|
|
342
|
-
|
|
343
|
-
Category Breakdown:
|
|
344
|
-
architectural: 12 insights (26%)
|
|
345
|
-
workflow: 15 insights (33%)
|
|
346
|
-
tool_usage: 8 insights (17%)
|
|
347
|
-
domain_knowledge: 11 insights (24%)
|
|
348
|
-
|
|
349
|
-
⚠️ Warnings:
|
|
350
|
-
- 3 entries have empty Improvements sections
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
### 4. Build a Personal Knowledge Base
|
|
354
|
-
|
|
355
|
-
```bash
|
|
356
|
-
# Weekly cron job
|
|
357
|
-
buildlog skills -o ~/.buildlog/skills-$(date +%Y-%m-%d).yml
|
|
358
|
-
```
|
|
359
|
-
|
|
360
|
-
Over time, you build a corpus of everything you've learned—searchable, diffable, and agent-consumable.
|
|
361
|
-
|
|
362
|
-
---
|
|
363
|
-
|
|
364
|
-
## 📋 Commands
|
|
365
|
-
|
|
366
|
-
| Command | Description |
|
|
367
|
-
|---------|-------------|
|
|
368
|
-
| `buildlog init` | Initialize in current directory |
|
|
369
|
-
| `buildlog new <slug>` | Create entry for today |
|
|
370
|
-
| `buildlog new <slug> --date 2026-01-15` | Create entry for specific date |
|
|
371
|
-
| `buildlog list` | List all entries |
|
|
372
|
-
| `buildlog distill` | Extract patterns from all entries |
|
|
373
|
-
| `buildlog stats` | Show statistics and analytics |
|
|
374
|
-
| `buildlog skills` | Generate agent-consumable skills |
|
|
375
|
-
| `buildlog update` | Update templates to latest |
|
|
376
|
-
|
|
377
|
-
### Skills Options
|
|
378
|
-
|
|
379
|
-
```bash
|
|
380
|
-
--output, -o PATH # Write to file instead of stdout
|
|
381
|
-
--format [yaml|json|markdown] # Output format (default: yaml)
|
|
382
|
-
--min-frequency N # Only skills seen N+ times
|
|
383
|
-
--since YYYY-MM-DD # Only entries from this date
|
|
384
|
-
--embeddings [token|sentence-transformers|openai] # Similarity backend
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
---
|
|
388
|
-
|
|
389
|
-
## 🏗️ Architecture
|
|
390
|
-
|
|
391
|
-
```
|
|
392
|
-
buildlog/
|
|
393
|
-
├── cli.py # Click CLI commands
|
|
394
|
-
├── distill.py # Pattern extraction from markdown
|
|
395
|
-
├── stats.py # Analytics and coverage metrics
|
|
396
|
-
├── skills.py # Skill generation with deduplication
|
|
397
|
-
├── embeddings.py # Pluggable similarity backends
|
|
398
|
-
├── core/ # Core business logic
|
|
399
|
-
│ └── operations.py # status, promote, reject, diff
|
|
400
|
-
├── render/ # Output adapters
|
|
401
|
-
│ ├── claude_md.py # Append rules to CLAUDE.md
|
|
402
|
-
│ └── settings_json.py# Merge rules into settings.json
|
|
403
|
-
└── mcp/ # MCP server (thin wrappers)
|
|
404
|
-
├── server.py # FastMCP server setup
|
|
405
|
-
└── tools.py # Tool implementations
|
|
406
|
-
|
|
407
|
-
User's Project/
|
|
408
|
-
└── buildlog/
|
|
409
|
-
├── _TEMPLATE.md # Entry template
|
|
410
|
-
├── 2026-01-15-auth-api.md
|
|
411
|
-
├── 2026-01-16-bugfix.md
|
|
412
|
-
└── ...
|
|
413
|
-
```
|
|
414
|
-
|
|
415
|
-
### Data Flow
|
|
416
|
-
|
|
417
|
-
```
|
|
418
|
-
buildlog/*.md
|
|
419
|
-
│
|
|
420
|
-
▼ parse markdown, extract Improvements
|
|
421
|
-
┌─────────────────┐
|
|
422
|
-
│ distill_all() │ → patterns by category
|
|
423
|
-
└────────┬────────┘
|
|
424
|
-
│
|
|
425
|
-
▼ deduplicate, score, tag
|
|
426
|
-
┌─────────────────┐
|
|
427
|
-
│ generate_skills()│ → SkillSet with stable IDs
|
|
428
|
-
└────────┬────────┘
|
|
429
|
-
│
|
|
430
|
-
▼ format output
|
|
431
|
-
┌─────────────────┐
|
|
432
|
-
│ format_skills() │ → YAML / JSON / Markdown
|
|
433
|
-
└─────────────────┘
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
---
|
|
437
|
-
|
|
438
|
-
## 🧪 Installation Options
|
|
439
|
-
|
|
440
|
-
```bash
|
|
441
|
-
# Basic install
|
|
442
|
-
pip install buildlog
|
|
443
|
-
|
|
444
|
-
# With local semantic embeddings (offline)
|
|
445
|
-
pip install buildlog[embeddings]
|
|
446
|
-
|
|
447
|
-
# With OpenAI embeddings
|
|
448
|
-
pip install buildlog[openai]
|
|
449
|
-
|
|
450
|
-
# Everything
|
|
451
|
-
pip install buildlog[all]
|
|
452
|
-
|
|
453
|
-
# Development
|
|
454
|
-
pip install buildlog[dev]
|
|
455
|
-
|
|
456
|
-
# With MCP server for Claude Code integration
|
|
457
|
-
pip install buildlog[mcp]
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
---
|
|
461
|
-
|
|
462
|
-
## 🔗 MCP Server (Claude Code Integration)
|
|
463
|
-
|
|
464
|
-
The MCP server lets Claude Code interact with your buildlog skills directly. Your agent can review learned patterns, promote them to rules, or reject false positives—all through natural conversation.
|
|
465
|
-
|
|
466
|
-
### Setup for Claude Code CLI
|
|
467
|
-
|
|
468
|
-
1. Install with MCP support:
|
|
469
|
-
```bash
|
|
470
|
-
pip install buildlog[mcp]
|
|
471
|
-
# or with uv
|
|
472
|
-
uv pip install buildlog[mcp]
|
|
473
|
-
```
|
|
474
|
-
|
|
475
|
-
2. Add to your Claude Code settings (`~/.claude/settings.json`):
|
|
476
|
-
```json
|
|
477
|
-
{
|
|
478
|
-
"mcpServers": {
|
|
479
|
-
"buildlog": {
|
|
480
|
-
"command": "buildlog-mcp",
|
|
481
|
-
"args": []
|
|
482
|
-
}
|
|
483
|
-
}
|
|
484
|
-
}
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
Or for project-specific config (`.claude/settings.json` in your repo):
|
|
488
|
-
```json
|
|
489
|
-
{
|
|
490
|
-
"mcpServers": {
|
|
491
|
-
"buildlog": {
|
|
492
|
-
"command": "buildlog-mcp",
|
|
493
|
-
"args": []
|
|
494
|
-
}
|
|
495
|
-
}
|
|
496
|
-
}
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
3. Start a new Claude Code session. The buildlog tools will be available.
|
|
500
|
-
|
|
501
|
-
### Setup for Claude Desktop
|
|
502
|
-
|
|
503
|
-
1. Install with MCP support:
|
|
504
|
-
```bash
|
|
505
|
-
pip install buildlog[mcp]
|
|
506
|
-
```
|
|
507
|
-
|
|
508
|
-
2. Add to your Claude Desktop config:
|
|
509
|
-
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
510
|
-
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
511
|
-
- **Linux**: `~/.config/claude/claude_desktop_config.json`
|
|
512
|
-
|
|
513
|
-
```json
|
|
514
|
-
{
|
|
515
|
-
"mcpServers": {
|
|
516
|
-
"buildlog": {
|
|
517
|
-
"command": "buildlog-mcp",
|
|
518
|
-
"args": []
|
|
519
|
-
}
|
|
520
|
-
}
|
|
521
|
-
}
|
|
522
|
-
```
|
|
523
|
-
|
|
524
|
-
3. Restart Claude Desktop.
|
|
525
|
-
|
|
526
|
-
### Local Development / Dogfooding
|
|
527
|
-
|
|
528
|
-
For dogfooding buildlog in your own projects during development:
|
|
529
|
-
|
|
530
|
-
```bash
|
|
531
|
-
# From the buildlog-template repo, install in editable mode
|
|
532
|
-
uv pip install -e ".[mcp,dev]"
|
|
533
|
-
|
|
534
|
-
# Verify the MCP server runs
|
|
535
|
-
buildlog-mcp --help # Should show MCP server info
|
|
536
|
-
|
|
537
|
-
# Test that skills generation works
|
|
538
|
-
cd /path/to/your/project
|
|
539
|
-
buildlog init # if not already initialized
|
|
540
|
-
buildlog skills # verify skills are generated
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
Then add to your project's `.claude/settings.json`:
|
|
544
|
-
```json
|
|
545
|
-
{
|
|
546
|
-
"mcpServers": {
|
|
547
|
-
"buildlog": {
|
|
548
|
-
"command": "buildlog-mcp"
|
|
549
|
-
}
|
|
550
|
-
}
|
|
551
|
-
}
|
|
552
|
-
```
|
|
553
|
-
|
|
554
|
-
### Troubleshooting
|
|
555
|
-
|
|
556
|
-
**"buildlog-mcp: command not found"**
|
|
557
|
-
- Ensure the package is installed: `pip show buildlog`
|
|
558
|
-
- Check your PATH includes pip's bin directory
|
|
559
|
-
- Try using the full path: `which buildlog-mcp` or `python -m buildlog.mcp.server`
|
|
560
|
-
|
|
561
|
-
**"No buildlog directory found"**
|
|
562
|
-
- Run `buildlog init` in your project first
|
|
563
|
-
- The MCP server looks for `./buildlog/` by default
|
|
564
|
-
|
|
565
|
-
**Skills not appearing**
|
|
566
|
-
- Ensure you have buildlog entries with **Improvements** sections
|
|
567
|
-
- Run `buildlog stats` to check coverage
|
|
568
|
-
|
|
569
|
-
### Available Tools
|
|
570
|
-
|
|
571
|
-
| Tool | Description |
|
|
572
|
-
|------|-------------|
|
|
573
|
-
| `buildlog_status` | Get skills grouped by category with confidence scores |
|
|
574
|
-
| `buildlog_promote` | Write high-confidence skills to CLAUDE.md or settings.json |
|
|
575
|
-
| `buildlog_reject` | Mark skills to exclude from future suggestions |
|
|
576
|
-
| `buildlog_diff` | Show skills pending review (not yet promoted/rejected) |
|
|
577
|
-
|
|
578
|
-
### Example Conversation
|
|
579
|
-
|
|
580
|
-
```
|
|
581
|
-
You: What patterns have I learned?
|
|
582
|
-
|
|
583
|
-
Claude: [calls buildlog_status]
|
|
584
|
-
Based on 23 buildlog entries, you have 31 skills:
|
|
585
|
-
|
|
586
|
-
High confidence (ready to promote):
|
|
587
|
-
- arch-b0fcb62a1e: "Always validate inputs at the boundary"
|
|
588
|
-
- wf-96f12966f1: "Run tests before committing"
|
|
589
|
-
|
|
590
|
-
Would you like me to add these to your CLAUDE.md?
|
|
591
|
-
|
|
592
|
-
You: Yes, promote the high-confidence ones.
|
|
593
|
-
|
|
594
|
-
Claude: [calls buildlog_promote]
|
|
595
|
-
Added 8 rules to CLAUDE.md. These patterns will now
|
|
596
|
-
influence my behavior in future sessions.
|
|
597
|
-
```
|
|
598
|
-
|
|
599
|
-
### How It Works
|
|
600
|
-
|
|
601
|
-
```
|
|
602
|
-
┌─────────────────────────────────────────────────────────────────┐
|
|
603
|
-
│ Claude Code Session │
|
|
604
|
-
│ │
|
|
605
|
-
│ 1. Claude calls buildlog_status │
|
|
606
|
-
│ → Runs generate_skills() on-demand │
|
|
607
|
-
│ → Returns skills with confidence scores │
|
|
608
|
-
│ │
|
|
609
|
-
│ 2. User reviews and approves │
|
|
610
|
-
│ │
|
|
611
|
-
│ 3. Claude calls buildlog_promote │
|
|
612
|
-
│ → Appends rules to CLAUDE.md │
|
|
613
|
-
│ → Tracks promoted IDs in .buildlog/promoted.json │
|
|
614
|
-
└─────────────────────────────────────────────────────────────────┘
|
|
615
|
-
```
|
|
616
|
-
|
|
617
|
-
The MCP server is **stateless**—skills are generated fresh on each request from your buildlog entries. No daemon, no database, no background processes.
|
|
618
|
-
|
|
619
|
-
---
|
|
620
|
-
|
|
621
|
-
## 📜 Philosophy
|
|
622
|
-
|
|
623
|
-
### 1. Write Fast, Not Pretty
|
|
624
|
-
Refrigerator to-do list energy. Get it down before you forget.
|
|
625
|
-
|
|
626
|
-
### 2. Never Delete Mistakes
|
|
627
|
-
Wrong turns are the most valuable content. They're what makes tutorials actually useful.
|
|
628
|
-
|
|
629
|
-
### 3. Include the Journey
|
|
630
|
-
"We tried X, it failed because Y, so we did Z" > "We did Z"
|
|
631
|
-
|
|
632
|
-
### 4. Capture Improvements
|
|
633
|
-
Concrete learnings, not vague observations. "Always validate at boundary" > "validation is important"
|
|
634
|
-
|
|
635
|
-
### 5. Quality Bar
|
|
636
|
-
Each entry should be publishable as a **$500+ tutorial**. Real error messages. Honest about what didn't work. Code that runs.
|
|
637
|
-
|
|
638
|
-
---
|
|
639
|
-
|
|
640
|
-
## 🤝 Contributing
|
|
641
|
-
|
|
642
|
-
1. Fork the repository
|
|
643
|
-
2. Create a feature branch (`git checkout -b feature/amazing`)
|
|
644
|
-
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
645
|
-
4. Push to the branch (`git push origin feature/amazing`)
|
|
646
|
-
5. Open a Pull Request
|
|
647
|
-
|
|
648
|
-
---
|
|
649
|
-
|
|
650
|
-
## 📄 License
|
|
651
|
-
|
|
652
|
-
MIT License — see [LICENSE](./LICENSE) for details.
|
|
653
|
-
|
|
654
|
-
---
|
|
655
|
-
|
|
656
|
-
<div align="center">
|
|
657
|
-
|
|
658
|
-
**Your AI pair programmer should learn from your mistakes.**
|
|
659
|
-
|
|
660
|
-
**buildlog makes that possible.**
|
|
661
|
-
|
|
662
|
-
[⬆ Back to top](#buildlog)
|
|
663
|
-
|
|
664
|
-
</div>
|