hyntx 3.0.2 โ 4.0.0
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.
- package/README.md +118 -963
- package/dist/cli.d.ts +1 -440
- package/dist/cli.js +5183 -6762
- package/dist/index.d.ts +696 -2
- package/dist/index.js +5392 -1
- package/package.json +17 -38
- package/dist/api/index.d.ts +0 -1083
- package/dist/api/index.js +0 -1
- package/dist/chunk-24U3LCZC.js +0 -3347
- package/dist/chunk-TLJ2AIHG.js +0 -389
- package/dist/shell-config-VEIMSP5W.js +0 -2
package/README.md
CHANGED
|
@@ -1,1042 +1,197 @@
|
|
|
1
1
|
# Hyntx
|
|
2
2
|
|
|
3
|
-
**Hyntx** is a CLI tool that analyzes your Claude Code prompts and helps you become a better prompt engineer through retrospective analysis and actionable feedback.
|
|
4
|
-
|
|
5
3
|
[](https://www.npmjs.com/package/hyntx)
|
|
6
4
|
[](LICENSE)
|
|
7
5
|
[](https://nodejs.org/)
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
## What is Hyntx?
|
|
12
|
-
|
|
13
|
-
Hyntx reads your Claude Code conversation logs and uses AI to detect common prompt engineering anti-patterns. It provides you with:
|
|
14
|
-
|
|
15
|
-
- **Pattern detection**: Identifies recurring issues in your prompts (missing context, vague instructions, etc.)
|
|
16
|
-
- **Actionable suggestions**: Specific recommendations with concrete "Before/After" rewrites
|
|
17
|
-
- **Privacy-first**: Automatically redacts secrets and defaults to local AI (Ollama)
|
|
18
|
-
- **Zero configuration**: Interactive setup on first run with auto-save to shell config
|
|
19
|
-
|
|
20
|
-
Think of it as a **retrospective code review for your prompts**.
|
|
21
|
-
|
|
22
|
-
## Features
|
|
23
|
-
|
|
24
|
-
- **Offline-first analysis** with local Ollama (privacy-friendly, cost-free)
|
|
25
|
-
- **Multi-provider support**: Ollama (local), Anthropic Claude, Google Gemini with automatic fallback
|
|
26
|
-
- **Before/After rewrites**: Concrete examples showing how to improve your prompts
|
|
27
|
-
- **Automatic secret redaction**: API keys, emails, tokens, credentials
|
|
28
|
-
- **Flexible date filtering**: Analyze today, yesterday, specific dates, or date ranges
|
|
29
|
-
- **Project filtering**: Focus on specific Claude Code projects
|
|
30
|
-
- **Multiple output formats**: Beautiful terminal output or markdown reports
|
|
31
|
-
- **Watch mode**: Real-time monitoring and analysis of prompts as you work
|
|
32
|
-
- **Smart reminders**: Oh-my-zsh style periodic reminders (configurable)
|
|
33
|
-
- **Auto-configuration**: Saves settings to your shell config automatically
|
|
34
|
-
- **Dry-run mode**: Preview what will be analyzed before sending to AI
|
|
35
|
-
|
|
36
|
-
## Installation
|
|
37
|
-
|
|
38
|
-
### NPM (Global)
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
npm install -g hyntx
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### NPX (No installation)
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
npx hyntx
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### PNPM
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
pnpm add -g hyntx
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## Quick Start
|
|
57
|
-
|
|
58
|
-
Run Hyntx with a single command:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
hyntx
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
On first run, Hyntx will guide you through an interactive setup:
|
|
65
|
-
|
|
66
|
-
1. Select one or more AI providers (Ollama recommended for privacy)
|
|
67
|
-
2. Configure models and API keys for selected providers
|
|
68
|
-
3. Set reminder preferences
|
|
69
|
-
4. **Auto-save** configuration to your shell (or get manual instructions)
|
|
70
|
-
|
|
71
|
-
That's it! Hyntx will analyze today's prompts and show you improvement suggestions with concrete "Before/After" examples.
|
|
72
|
-
|
|
73
|
-
## Usage
|
|
74
|
-
|
|
75
|
-
### Basic Commands
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
# Analyze today's prompts
|
|
79
|
-
hyntx
|
|
80
|
-
|
|
81
|
-
# Analyze yesterday
|
|
82
|
-
hyntx --date yesterday
|
|
83
|
-
|
|
84
|
-
# Analyze a specific date
|
|
85
|
-
hyntx --date 2025-01-20
|
|
86
|
-
|
|
87
|
-
# Analyze a date range
|
|
88
|
-
hyntx --from 2025-01-15 --to 2025-01-20
|
|
89
|
-
|
|
90
|
-
# Filter by project name
|
|
91
|
-
hyntx --project my-awesome-app
|
|
92
|
-
|
|
93
|
-
# Save report to file
|
|
94
|
-
hyntx --output report.md
|
|
95
|
-
|
|
96
|
-
# Preview without sending to AI
|
|
97
|
-
hyntx --dry-run
|
|
98
|
-
|
|
99
|
-
# Check reminder status
|
|
100
|
-
hyntx --check-reminder
|
|
101
|
-
|
|
102
|
-
# Watch mode - real-time analysis
|
|
103
|
-
hyntx --watch
|
|
104
|
-
|
|
105
|
-
# Watch specific project only
|
|
106
|
-
hyntx --watch --project my-app
|
|
107
|
-
|
|
108
|
-
# Analysis modes - control speed vs accuracy trade-off
|
|
109
|
-
hyntx --analysis-mode batch # Fast (default): ~300-400ms/prompt
|
|
110
|
-
hyntx --analysis-mode individual # Accurate: ~1000-1500ms/prompt
|
|
111
|
-
hyntx -m individual # Short form
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### Combining Options
|
|
115
|
-
|
|
116
|
-
```bash
|
|
117
|
-
# Analyze last week for a specific project
|
|
118
|
-
hyntx --from 2025-01-15 --to 2025-01-22 --project backend-api
|
|
119
|
-
|
|
120
|
-
# Generate markdown report for yesterday
|
|
121
|
-
hyntx --date yesterday --output yesterday-analysis.md
|
|
122
|
-
|
|
123
|
-
# Deep analysis with individual mode for critical project
|
|
124
|
-
hyntx -m individual --project production-api --date today
|
|
125
|
-
|
|
126
|
-
# Fast batch analysis across date range
|
|
127
|
-
hyntx --from 2025-01-15 --to 2025-01-20 --analysis-mode batch -o report.md
|
|
128
|
-
|
|
129
|
-
# Watch mode with individual analysis (slower but detailed)
|
|
130
|
-
hyntx --watch -m individual --project critical-app
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
## Configuration
|
|
134
|
-
|
|
135
|
-
### Analysis Modes
|
|
136
|
-
|
|
137
|
-
Hyntx offers two analysis modes to balance speed and accuracy based on your needs:
|
|
138
|
-
|
|
139
|
-
#### Batch Mode (Default)
|
|
140
|
-
|
|
141
|
-
- **Speed**: ~300-400ms per prompt
|
|
142
|
-
- **Best for**: Daily analysis, quick feedback, large prompt batches
|
|
143
|
-
- **Accuracy**: Good categorization for most use cases
|
|
144
|
-
- **When to use**: Regular check-ins, monitoring prompt quality over time
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
hyntx # Uses batch mode by default
|
|
148
|
-
hyntx --analysis-mode batch # Explicit batch mode
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
#### Individual Mode
|
|
152
|
-
|
|
153
|
-
- **Speed**: ~1000-1500ms per prompt
|
|
154
|
-
- **Best for**: Deep analysis, quality-focused reviews, important prompts
|
|
155
|
-
- **Accuracy**: Better categorization and more nuanced pattern detection
|
|
156
|
-
- **When to use**: Learning sessions, preparing critical prompts, detailed audits
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
hyntx --analysis-mode individual # Use individual mode
|
|
160
|
-
hyntx -m individual # Short form
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
#### Quick Mode Comparison
|
|
164
|
-
|
|
165
|
-
| Mode | Speed/Prompt | Use Case | Accuracy | When to Use |
|
|
166
|
-
| ---------- | ------------ | -------------------------- | -------- | ----------------------------------------- |
|
|
167
|
-
| Batch | ~300-400ms | Daily analysis, monitoring | Good | Quick feedback, large datasets |
|
|
168
|
-
| Individual | ~1-1.5s | Deep analysis, learning | Better | Quality-focused reviews, critical prompts |
|
|
169
|
-
|
|
170
|
-
**Speedup**: Batch mode is 3-4x faster than individual mode.
|
|
171
|
-
|
|
172
|
-
**Recommendation**: Use batch mode (default) for daily analysis to get fast feedback. Switch to individual mode when:
|
|
173
|
-
|
|
174
|
-
- You need detailed, nuanced feedback on each prompt
|
|
175
|
-
- You're learning prompt engineering patterns
|
|
176
|
-
- Analyzing high-stakes or complex prompts
|
|
177
|
-
- Conducting quality audits or teaching sessions
|
|
7
|
+
Hyntx reads your Claude Code session logs and tells you where your sessions cost you time, with the evidence and a fix you can apply.
|
|
178
8
|
|
|
179
|
-
|
|
9
|
+
It looks at what actually happened in each session, not at how your prompts are worded: the times you corrected Claude, interrupted it, watched the same command fail in a loop, hit a blocked tool, re-explained the same thing in three sessions, or ran the same read-only command again and again in a mode that can prompt. Each finding comes with counts, quoted examples and one concrete action: a rule for `CLAUDE.md`, a permission entry for `settings.json`, a slash command file, a prompting habit or a workflow change.
|
|
180
10
|
|
|
181
|
-
|
|
11
|
+
> Hyntx 4 is a rewrite. Versions up to 3 sent the text of your prompts to a model and returned prompt-writing advice. If you are upgrading, read [Migrating from v3](#migrating-from-v3).
|
|
182
12
|
|
|
183
|
-
|
|
13
|
+
## How it differs
|
|
184
14
|
|
|
185
|
-
Hyntx
|
|
15
|
+
**From prompt linting.** A prompt linter judges the text of a prompt. Hyntx judges outcomes: a short prompt that worked is fine, and a careful prompt that led to four corrections is a finding.
|
|
186
16
|
|
|
187
|
-
|
|
17
|
+
**From Claude Code's `/insights`.** Claude Code has a built-in [`/insights`](https://code.claude.com/docs/en/costs#analyze-your-usage-patterns) command that has a model read your recent sessions and writes a narrative HTML report. Hyntx overlaps with it and is built differently:
|
|
188
18
|
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
19
|
+
- The core is deterministic. Parsing, metrics, friction detection and ranking are plain code; the same logs give the same findings, and the whole analysis runs with no model at all (`--no-llm`).
|
|
20
|
+
- Every finding carries its evidence: how many times, in how many sessions, in which projects, with quoted examples.
|
|
21
|
+
- Every finding ends in an action that is ready to apply (review it first: suggestions are heuristics, and a permission rule in particular should be checked before you paste it), and the [plugin](#claude-code-plugin) applies it for you after you confirm.
|
|
22
|
+
- Output is also available as JSON and markdown, for scripts and for other tools.
|
|
23
|
+
- Daily totals are kept in `~/.hyntx/`, so trends remain after Claude Code deletes old session logs (30 days by default).
|
|
194
24
|
|
|
195
|
-
|
|
25
|
+
## Install and run
|
|
196
26
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
- **Disable**: Set `enabled: false` to skip detection
|
|
200
|
-
- **Override severity**: Set `severity` to `"low"`, `"medium"`, or `"high"`
|
|
201
|
-
|
|
202
|
-
#### Example Configuration
|
|
203
|
-
|
|
204
|
-
Create `.hyntxrc.json` in your project root:
|
|
205
|
-
|
|
206
|
-
```json
|
|
207
|
-
{
|
|
208
|
-
"rules": {
|
|
209
|
-
"imperative": {
|
|
210
|
-
"enabled": false
|
|
211
|
-
},
|
|
212
|
-
"vague": {
|
|
213
|
-
"severity": "high"
|
|
214
|
-
},
|
|
215
|
-
"no-context": {
|
|
216
|
-
"severity": "high"
|
|
217
|
-
},
|
|
218
|
-
"too-broad": {
|
|
219
|
-
"severity": "medium"
|
|
220
|
-
}
|
|
221
|
-
}
|
|
222
|
-
}
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
#### What Happens When Patterns Are Disabled
|
|
226
|
-
|
|
227
|
-
- **Filtered out**: Disabled patterns are completely excluded from analysis results
|
|
228
|
-
- **No detection**: The AI will not look for those specific issues
|
|
229
|
-
- **Updated stats**: Pattern counts and frequency calculations exclude disabled patterns
|
|
230
|
-
- **Warning**: If all patterns are disabled, you'll see a warning that no analysis will occur
|
|
231
|
-
|
|
232
|
-
#### How Severity Overrides Work
|
|
233
|
-
|
|
234
|
-
- **Changed priority**: Patterns are sorted by severity (high โ medium โ low), then by frequency
|
|
235
|
-
- **Updated display**: The reporter shows severity badges based on your configuration
|
|
236
|
-
- **No effect on detection**: Severity only affects sorting and display, not whether the pattern is detected
|
|
237
|
-
|
|
238
|
-
#### Configuration Warnings
|
|
239
|
-
|
|
240
|
-
Hyntx will warn you about:
|
|
241
|
-
|
|
242
|
-
- **Invalid pattern IDs**: If you specify a pattern ID that doesn't exist
|
|
243
|
-
- **All patterns disabled**: If your configuration disables every pattern
|
|
244
|
-
|
|
245
|
-
These warnings appear immediately when the configuration is loaded.
|
|
246
|
-
|
|
247
|
-
### Environment Variables
|
|
248
|
-
|
|
249
|
-
Hyntx uses environment variables for configuration. The interactive setup can **auto-save** these to your shell config (`~/.zshrc`, `~/.bashrc`).
|
|
250
|
-
|
|
251
|
-
#### Multi-Provider Configuration
|
|
252
|
-
|
|
253
|
-
Configure one or more providers in priority order. Hyntx will try each provider in order and fall back to the next if unavailable.
|
|
27
|
+
Requires Node.js 22 or later and Claude Code session logs in `~/.claude/projects/`.
|
|
254
28
|
|
|
255
29
|
```bash
|
|
256
|
-
#
|
|
257
|
-
|
|
258
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
259
|
-
|
|
260
|
-
# Multi-provider with fallback (tries Ollama first, then Anthropic)
|
|
261
|
-
export HYNTX_SERVICES=ollama,anthropic
|
|
262
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
263
|
-
export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
|
|
264
|
-
|
|
265
|
-
# Cloud-first with local fallback
|
|
266
|
-
export HYNTX_SERVICES=anthropic,ollama
|
|
267
|
-
export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
|
|
268
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
30
|
+
npx hyntx # last 7 days, all projects
|
|
31
|
+
npm install -g hyntx # or install it
|
|
269
32
|
```
|
|
270
33
|
|
|
271
|
-
#### Provider-Specific Variables
|
|
272
|
-
|
|
273
|
-
**Ollama:**
|
|
274
|
-
|
|
275
|
-
| Variable | Default | Description |
|
|
276
|
-
| -------------------- | ------------------------ | ----------------- |
|
|
277
|
-
| `HYNTX_OLLAMA_MODEL` | `gemma3:4b` | Model to use |
|
|
278
|
-
| `HYNTX_OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
|
|
279
|
-
|
|
280
|
-
**Anthropic:**
|
|
281
|
-
|
|
282
|
-
| Variable | Default | Description |
|
|
283
|
-
| ----------------------- | ------------------------- | ------------------ |
|
|
284
|
-
| `HYNTX_ANTHROPIC_MODEL` | `claude-3-5-haiku-latest` | Model to use |
|
|
285
|
-
| `HYNTX_ANTHROPIC_KEY` | - | API key (required) |
|
|
286
|
-
|
|
287
|
-
**Google:**
|
|
288
|
-
|
|
289
|
-
| Variable | Default | Description |
|
|
290
|
-
| -------------------- | ---------------------- | ------------------ |
|
|
291
|
-
| `HYNTX_GOOGLE_MODEL` | `gemini-2.0-flash-exp` | Model to use |
|
|
292
|
-
| `HYNTX_GOOGLE_KEY` | - | API key (required) |
|
|
293
|
-
|
|
294
|
-
#### Reminder Settings
|
|
295
|
-
|
|
296
34
|
```bash
|
|
297
|
-
|
|
298
|
-
|
|
35
|
+
hyntx --days 30 # a longer period
|
|
36
|
+
hyntx --project my-app # one project (substring match)
|
|
37
|
+
hyntx --from 2026-09-01 --to 2026-09-30
|
|
38
|
+
hyntx --no-llm # deterministic analysis only
|
|
39
|
+
hyntx --html # also write hyntx-report.html
|
|
40
|
+
hyntx --format json > report.json # machine-readable
|
|
299
41
|
```
|
|
300
42
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
```bash
|
|
304
|
-
# Add to ~/.zshrc or ~/.bashrc (or let Hyntx auto-save it)
|
|
305
|
-
export HYNTX_SERVICES=ollama,anthropic
|
|
306
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
307
|
-
export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
|
|
308
|
-
export HYNTX_REMINDER=14d
|
|
309
|
-
|
|
310
|
-
# Optional: Enable periodic reminders
|
|
311
|
-
hyntx --check-reminder 2>/dev/null
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
Then reload your shell:
|
|
315
|
-
|
|
316
|
-
```bash
|
|
317
|
-
source ~/.zshrc # or source ~/.bashrc
|
|
318
|
-
```
|
|
43
|
+
## Example output
|
|
319
44
|
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
### Ollama (Recommended)
|
|
323
|
-
|
|
324
|
-
Ollama runs AI models locally for **privacy and cost savings**.
|
|
325
|
-
|
|
326
|
-
1. Install Ollama: [ollama.ai](https://ollama.ai)
|
|
327
|
-
2. Pull a model:
|
|
328
|
-
|
|
329
|
-
```bash
|
|
330
|
-
ollama pull gemma3:4b
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
3. Verify it's running:
|
|
334
|
-
|
|
335
|
-
```bash
|
|
336
|
-
ollama list
|
|
337
|
-
```
|
|
338
|
-
|
|
339
|
-
4. Run Hyntx (it will auto-configure on first run):
|
|
340
|
-
|
|
341
|
-
```bash
|
|
342
|
-
hyntx
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
### Anthropic Claude
|
|
346
|
-
|
|
347
|
-
1. Get API key from [console.anthropic.com](https://console.anthropic.com/)
|
|
348
|
-
2. Run Hyntx and select Anthropic during setup, or set manually:
|
|
349
|
-
|
|
350
|
-
```bash
|
|
351
|
-
export HYNTX_SERVICES=anthropic
|
|
352
|
-
export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
### Google Gemini
|
|
356
|
-
|
|
357
|
-
1. Get API key from [ai.google.dev](https://ai.google.dev)
|
|
358
|
-
2. Run Hyntx and select Google during setup, or set manually:
|
|
359
|
-
|
|
360
|
-
```bash
|
|
361
|
-
export HYNTX_SERVICES=google
|
|
362
|
-
export HYNTX_GOOGLE_KEY=your-google-api-key
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
### Using Multiple Providers
|
|
366
|
-
|
|
367
|
-
Configure multiple providers for automatic fallback:
|
|
368
|
-
|
|
369
|
-
```bash
|
|
370
|
-
# If Ollama is down, automatically try Anthropic
|
|
371
|
-
export HYNTX_SERVICES=ollama,anthropic
|
|
372
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
373
|
-
export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
When running, Hyntx will show fallback behavior:
|
|
45
|
+
An illustrative, shortened report in the shape `hyntx --days 30 --no-llm` prints (project and file names are made up):
|
|
377
46
|
|
|
378
47
|
```text
|
|
379
|
-
|
|
380
|
-
โ
anthropic connected
|
|
381
|
-
```
|
|
48
|
+
hyntx 2026-09-04 to 2026-10-03 (30 days) - all projects
|
|
382
49
|
|
|
383
|
-
|
|
50
|
+
14 sessions 45 typed prompts 645 tool calls (1.6% errors)
|
|
51
|
+
98.3M tokens (97% cache hits, 468.9k output) 0 interruptions 0 compactions
|
|
384
52
|
|
|
385
|
-
|
|
386
|
-
๐ Hyntx - 2025-01-20
|
|
387
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
53
|
+
Top insights (3 of 6)
|
|
388
54
|
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
55
|
+
1. [MEDIUM] A hook keeps blocking Bash: "Use 'trash' instead of 'rm'"
|
|
56
|
+
A PreToolUse hook blocked 4 calls with the same message in 4 sessions in shop.
|
|
57
|
+
evidence: 4 in 4 sessions; e.g. "โฆ touch /var/www/html/.t && cleanup /var/www/html/.t โฆ" (shop, 2026-09-19)
|
|
58
|
+
do: Add to CLAUDE.md in project "shop"
|
|
59
|
+
- A hook blocks commands that break this rule: "Use 'trash' instead of 'rm'".
|
|
60
|
+
Follow it on the first attempt instead of retrying the blocked command.
|
|
393
61
|
|
|
394
|
-
|
|
62
|
+
2. [LOW] Read-only commands that may be worth allowing
|
|
63
|
+
1 read-only command ran 6 times in permission modes that can prompt (top: Bash(gh pr view *)).
|
|
64
|
+
do: Allow in ~/.claude/settings.json
|
|
65
|
+
{ "permissions": { "allow": ["Bash(gh pr view *)"] } }
|
|
395
66
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
๐ก Include specific error messages, framework versions, and file paths
|
|
67
|
+
3. [LOW] `bin/sync` was reworked repeatedly
|
|
68
|
+
`bin/sync` was edited 6 times across 3 of your prompts, with 2 tool failures in between (plan mode was not used).
|
|
69
|
+
do: Plan before editing: agree on the exact changes first, then execute.
|
|
400
70
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
'Invalid token' error. Using Next.js 14.1.0 with next-auth 4.24.5."
|
|
406
|
-
|
|
407
|
-
๐ก Vague Instructions (40%)
|
|
408
|
-
โข "Make it better"
|
|
409
|
-
โข "Improve this"
|
|
410
|
-
๐ก Define specific success criteria and expected outcomes
|
|
411
|
-
|
|
412
|
-
Before:
|
|
413
|
-
โ "Make it better"
|
|
414
|
-
After:
|
|
415
|
-
โ
"Optimize the database query to reduce response time from 500ms
|
|
416
|
-
to under 100ms. Focus on adding proper indexes."
|
|
417
|
-
|
|
418
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
419
|
-
๐ Top Suggestion
|
|
420
|
-
"Add error messages and stack traces to debugging requests for
|
|
421
|
-
10x faster resolution."
|
|
422
|
-
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
71
|
+
Metrics
|
|
72
|
+
Projects shop 38, printing 3, hyntx 1
|
|
73
|
+
Tools Bash 476 (8 err), Write 26, Edit 18, Read 14
|
|
74
|
+
Sessions median 4m, p90 38m
|
|
423
75
|
```
|
|
424
76
|
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
Hyntx can run as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, enabling real-time prompt analysis directly within MCP-compatible clients like Claude Code.
|
|
77
|
+
With too little data (fewer than 3 sessions or 10 typed prompts) Hyntx says so instead of producing findings.
|
|
428
78
|
|
|
429
|
-
|
|
79
|
+
## Claude Code plugin
|
|
430
80
|
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
#### Option 1: User-scoped (Recommended)
|
|
434
|
-
|
|
435
|
-
Configuration visible only to you, stored in `~/.claude.json`:
|
|
81
|
+
The plugin adds the `/hyntx:hyntx` command to Claude Code. It runs the same analyzer with `--no-llm` and lets the Claude in your session do the interpretation: it checks each detected episode against its context, discards the ones that are not real friction, shows you the few findings that matter and offers to apply the fixes. It shows the exact change and asks before every write, and it does not add a rule that is already there. The runner validates its arguments, never uses a shell, and deletes the temporary report it writes before it exits.
|
|
436
82
|
|
|
437
83
|
```bash
|
|
438
|
-
|
|
439
|
-
claude
|
|
440
|
-
|
|
441
|
-
# Or manually edit ~/.claude.json
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
```json
|
|
445
|
-
{
|
|
446
|
-
"mcpServers": {
|
|
447
|
-
"hyntx": {
|
|
448
|
-
"command": "hyntx",
|
|
449
|
-
"args": ["--mcp-server"]
|
|
450
|
-
}
|
|
451
|
-
}
|
|
452
|
-
}
|
|
84
|
+
claude plugin marketplace add jmlweb/hyntx
|
|
85
|
+
claude plugin install hyntx@hyntx
|
|
453
86
|
```
|
|
454
87
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
Configuration shared with your team via Git, stored in `.mcp.json` at your project root:
|
|
458
|
-
|
|
459
|
-
```json
|
|
460
|
-
{
|
|
461
|
-
"mcpServers": {
|
|
462
|
-
"hyntx": {
|
|
463
|
-
"command": "hyntx",
|
|
464
|
-
"args": ["--mcp-server"]
|
|
465
|
-
}
|
|
466
|
-
}
|
|
467
|
-
}
|
|
468
|
-
```
|
|
469
|
-
|
|
470
|
-
After adding the configuration, restart your Claude Code session. The hyntx tools will be available in your conversations.
|
|
471
|
-
|
|
472
|
-
### Prerequisites
|
|
473
|
-
|
|
474
|
-
- **Hyntx installed globally**: `npm install -g hyntx`
|
|
475
|
-
- **AI provider configured**: Set up Ollama (recommended) or cloud providers via environment variables
|
|
476
|
-
|
|
477
|
-
If using Ollama (recommended for privacy):
|
|
478
|
-
|
|
479
|
-
```bash
|
|
480
|
-
# Ensure Ollama is running
|
|
481
|
-
ollama serve
|
|
482
|
-
|
|
483
|
-
# Pull a model if needed
|
|
484
|
-
ollama pull gemma3:4b
|
|
485
|
-
|
|
486
|
-
# Set environment variables (add to ~/.zshrc or ~/.bashrc)
|
|
487
|
-
export HYNTX_SERVICES=ollama
|
|
488
|
-
export HYNTX_OLLAMA_MODEL=gemma3:4b
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
### Available MCP Tools
|
|
492
|
-
|
|
493
|
-
Hyntx exposes three tools through the MCP interface:
|
|
494
|
-
|
|
495
|
-
#### analyze-prompt
|
|
496
|
-
|
|
497
|
-
Analyze a prompt to detect anti-patterns, issues, and get improvement suggestions.
|
|
498
|
-
|
|
499
|
-
**Input Schema:**
|
|
500
|
-
|
|
501
|
-
| Parameter | Type | Required | Description |
|
|
502
|
-
| --------- | ------ | -------- | ----------------------------------------------------- |
|
|
503
|
-
| `prompt` | string | Yes | The prompt text to analyze |
|
|
504
|
-
| `date` | string | No | Date context in ISO format. Defaults to current date. |
|
|
505
|
-
|
|
506
|
-
**Example Output:**
|
|
507
|
-
|
|
508
|
-
```json
|
|
509
|
-
{
|
|
510
|
-
"patterns": [
|
|
511
|
-
{
|
|
512
|
-
"id": "no-context",
|
|
513
|
-
"name": "Missing Context",
|
|
514
|
-
"severity": "high",
|
|
515
|
-
"frequency": "100%",
|
|
516
|
-
"suggestion": "Include specific error messages and file paths",
|
|
517
|
-
"examples": ["Fix the bug in auth"]
|
|
518
|
-
}
|
|
519
|
-
],
|
|
520
|
-
"stats": {
|
|
521
|
-
"promptCount": 1,
|
|
522
|
-
"overallScore": 4.5
|
|
523
|
-
},
|
|
524
|
-
"topSuggestion": "Add error messages and stack traces for faster resolution"
|
|
525
|
-
}
|
|
526
|
-
```
|
|
527
|
-
|
|
528
|
-
#### suggest-improvements
|
|
529
|
-
|
|
530
|
-
Get concrete before/after rewrites showing how to improve a prompt.
|
|
531
|
-
|
|
532
|
-
**Input Schema:**
|
|
533
|
-
|
|
534
|
-
| Parameter | Type | Required | Description |
|
|
535
|
-
| --------- | ------ | -------- | ----------------------------------------------------- |
|
|
536
|
-
| `prompt` | string | Yes | The prompt text to analyze for improvements |
|
|
537
|
-
| `date` | string | No | Date context in ISO format. Defaults to current date. |
|
|
538
|
-
|
|
539
|
-
**Example Output:**
|
|
540
|
-
|
|
541
|
-
```json
|
|
542
|
-
{
|
|
543
|
-
"improvements": [
|
|
544
|
-
{
|
|
545
|
-
"issue": "Missing Context",
|
|
546
|
-
"before": "Fix the bug in auth",
|
|
547
|
-
"after": "Fix authentication bug in src/auth/login.ts where users get 'Invalid token' error. Using Next.js 14.1.0 with next-auth 4.24.5.",
|
|
548
|
-
"suggestion": "Include specific error messages, framework versions, and file paths"
|
|
549
|
-
}
|
|
550
|
-
],
|
|
551
|
-
"summary": "Found 1 improvement(s)",
|
|
552
|
-
"topSuggestion": "Add error messages and stack traces for faster resolution"
|
|
553
|
-
}
|
|
554
|
-
```
|
|
555
|
-
|
|
556
|
-
#### check-context
|
|
557
|
-
|
|
558
|
-
Verify if a prompt has sufficient context for effective AI interaction.
|
|
559
|
-
|
|
560
|
-
**Input Schema:**
|
|
561
|
-
|
|
562
|
-
| Parameter | Type | Required | Description |
|
|
563
|
-
| --------- | ------ | -------- | ----------------------------------------------------- |
|
|
564
|
-
| `prompt` | string | Yes | The prompt text to check for context |
|
|
565
|
-
| `date` | string | No | Date context in ISO format. Defaults to current date. |
|
|
566
|
-
|
|
567
|
-
**Example Output:**
|
|
568
|
-
|
|
569
|
-
```json
|
|
570
|
-
{
|
|
571
|
-
"hasSufficientContext": false,
|
|
572
|
-
"score": 4.5,
|
|
573
|
-
"issues": ["Missing Context", "Vague Instructions"],
|
|
574
|
-
"suggestion": "Include specific error messages and file paths",
|
|
575
|
-
"details": "Prompt lacks sufficient context for effective AI interaction"
|
|
576
|
-
}
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
### Usage Examples
|
|
580
|
-
|
|
581
|
-
Once configured, you can use these tools in your Claude Code conversations:
|
|
582
|
-
|
|
583
|
-
**Analyze a prompt before sending:**
|
|
88
|
+
Then, in a session:
|
|
584
89
|
|
|
585
90
|
```text
|
|
586
|
-
|
|
91
|
+
/hyntx:hyntx # last 30 days, all projects
|
|
92
|
+
/hyntx:hyntx 14d # a period
|
|
93
|
+
/hyntx:hyntx 60d my-app # a period and a project
|
|
587
94
|
```
|
|
588
95
|
|
|
589
|
-
|
|
96
|
+
The command is `/hyntx:hyntx` (plugin name, then skill name); Claude Code may also accept the short `/hyntx` when nothing else uses that name.
|
|
590
97
|
|
|
591
|
-
|
|
592
|
-
Use suggest-improvements on: "Make the API faster"
|
|
593
|
-
```
|
|
594
|
-
|
|
595
|
-
**Check if your prompt has enough context:**
|
|
596
|
-
|
|
597
|
-
```text
|
|
598
|
-
Use check-context to verify: "Update the component to handle errors"
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
### MCP Server Troubleshooting
|
|
602
|
-
|
|
603
|
-
#### "Server failed to start"
|
|
604
|
-
|
|
605
|
-
1. Verify hyntx is installed globally:
|
|
606
|
-
|
|
607
|
-
```bash
|
|
608
|
-
which hyntx
|
|
609
|
-
# Should output: /usr/local/bin/hyntx or similar
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
2. Test manual startup:
|
|
613
|
-
|
|
614
|
-
```bash
|
|
615
|
-
hyntx --mcp-server
|
|
616
|
-
# Should output: MCP server running on stdio
|
|
617
|
-
```
|
|
618
|
-
|
|
619
|
-
3. Check environment variables are set (if using cloud providers):
|
|
620
|
-
|
|
621
|
-
```bash
|
|
622
|
-
echo $HYNTX_SERVICES
|
|
623
|
-
echo $HYNTX_ANTHROPIC_KEY # if using Anthropic
|
|
624
|
-
```
|
|
625
|
-
|
|
626
|
-
#### "Analysis failed: Provider not available"
|
|
627
|
-
|
|
628
|
-
1. If using Ollama, ensure it's running:
|
|
629
|
-
|
|
630
|
-
```bash
|
|
631
|
-
ollama list
|
|
632
|
-
# If no output, start Ollama:
|
|
633
|
-
ollama serve
|
|
634
|
-
```
|
|
98
|
+
The plugin needs a Hyntx 4 analyzer. It uses, in order: the path in `HYNTX_CLI`, a built checkout that contains the plugin, a globally installed `hyntx` (version 4 or later), and finally `npx hyntx@4`. To try the plugin from a checkout before installing it, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#testing-the-plugin-locally).
|
|
635
99
|
|
|
636
|
-
|
|
100
|
+
## Interpretation engines and privacy
|
|
637
101
|
|
|
638
|
-
|
|
639
|
-
# Check if keys are configured
|
|
640
|
-
env | grep HYNTX_
|
|
641
|
-
```
|
|
102
|
+
Reading the logs, computing metrics, detecting friction and ranking insights all happen on your machine and never modify Claude Code's files. Hyntx reads `~/.claude/projects/**/*.jsonl` and, to avoid suggesting permissions you already have, the `permissions` in your Claude Code settings files.
|
|
642
103
|
|
|
643
|
-
|
|
104
|
+
After that, an optional interpretation step asks a model to confirm or reject the heuristic episodes (corrections in particular are guessed from phrasing) and to write a short summary. What leaves your machine depends on the engine:
|
|
644
105
|
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
106
|
+
| Engine | Flag | What is sent, and where |
|
|
107
|
+
| ------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| `claude` (default) | none | Sanitized excerpts of the report (counts, up to 8 insights, and up to 16 flagged episodes with their summary and a 220-character excerpt of the prompt, the previous prompt and the assistant's last text) go to Anthropic through `claude -p`, using your existing Claude Code login. It uses your plan or API usage like any other Claude Code request. A bare run prints a notice about this on stderr before the call. |
|
|
109
|
+
| `ollama` | `--engine ollama` | A smaller selection (8 episodes, 140 characters each) goes to the Ollama server at `OLLAMA_HOST` (default `http://localhost:11434`). That stays on your machine unless you point `OLLAMA_HOST` elsewhere, in which case it leaves the machine and hyntx warns you. |
|
|
110
|
+
| none | `--no-llm` | Nothing is sent anywhere. You get the deterministic findings, and heuristic ones are marked as unconfirmed. |
|
|
650
111
|
|
|
651
|
-
|
|
652
|
-
# Verify user-scoped config
|
|
653
|
-
cat ~/.claude.json | jq .
|
|
112
|
+
Sanitized means that API keys, tokens, credentials in URLs and on command lines, private keys, email addresses and common personal identifiers are replaced with `[REDACTED_<TYPE>]` before text is put in a report, sent to an engine or written to disk, and that terminal escape sequences are removed. Redaction is pattern-based: it catches well-known formats, not every possible secret, and it can hide harmless text that looks like an identifier. Treat a report like any file that may mention your projects.
|
|
654
113
|
|
|
655
|
-
|
|
656
|
-
cat .mcp.json | jq .
|
|
114
|
+
If the engine is not available (no `claude` on the PATH, Ollama not running), Hyntx still prints the deterministic report and notes that interpretation was skipped. The model sees only some of the episodes, so a verdict covers part of an insight: an insight is hidden as dismissed only when every episode behind it was rejected, and otherwise it shows how many were reviewed.
|
|
657
115
|
|
|
658
|
-
|
|
659
|
-
claude mcp list
|
|
660
|
-
```
|
|
116
|
+
The `/hyntx:hyntx` plugin always runs the analyzer with `--no-llm`. The findings it reads are then part of your Claude Code conversation, like any other tool output in that session.
|
|
661
117
|
|
|
662
|
-
|
|
118
|
+
## Options
|
|
663
119
|
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
120
|
+
| Flag | Description |
|
|
121
|
+
| ------------------ | ------------------------------------------------------------- |
|
|
122
|
+
| `--days <n>` | Analyze the last n days (default: 7) |
|
|
123
|
+
| `--from <date>` | Start date: `YYYY-MM-DD`, `today` or `yesterday` |
|
|
124
|
+
| `--to <date>` | End date, inclusive (default: now) |
|
|
125
|
+
| `--project <name>` | Only projects whose name contains `<name>` |
|
|
126
|
+
| `--format <fmt>` | `terminal` (default), `json`, `markdown` |
|
|
127
|
+
| `--output <file>` | Write the report to a file instead of stdout |
|
|
128
|
+
| `--html [path]` | Also write a self-contained HTML report (`hyntx-report.html`) |
|
|
129
|
+
| `--no-llm` | Skip the interpretation step |
|
|
130
|
+
| `--engine <name>` | `claude` (default) or `ollama` |
|
|
131
|
+
| `--model <name>` | Model for the interpretation engine |
|
|
132
|
+
| `--verbose` | Debug logging on stderr |
|
|
133
|
+
| `--help`, `-h` | Show help |
|
|
134
|
+
| `--version`, `-v` | Show version |
|
|
667
135
|
|
|
668
|
-
|
|
136
|
+
`--days` cannot be combined with `--from`/`--to`. With `--format json`, stdout contains only the report JSON; progress and logs go to stderr. Exit codes: `0` success, `1` error, `2` no logs or no sessions for the period.
|
|
669
137
|
|
|
670
|
-
|
|
138
|
+
Full reference: [docs/CLI.md](docs/CLI.md).
|
|
671
139
|
|
|
672
|
-
|
|
673
|
-
- **Automatic redaction**: Removes API keys, credentials, emails, tokens before analysis
|
|
674
|
-
- **Read-only**: Never modifies your Claude Code logs
|
|
675
|
-
- **No telemetry**: Hyntx doesn't send usage data anywhere
|
|
140
|
+
## What it writes to disk
|
|
676
141
|
|
|
677
|
-
|
|
142
|
+
- `~/.hyntx/daily.json`: one record per day with aggregate numbers only (sessions, prompts, tool calls, errors, tokens and similar). No prompt text, no file names. It is updated on every run that is not filtered by project (including plugin runs), and it is what keeps trends available after Claude Code prunes old logs.
|
|
143
|
+
- The files you ask for: `--output <file>` and `--html [path]`.
|
|
144
|
+
- Temporary files while writing (a uniquely named `*.tmp` next to the target, renamed into place). If `daily.json` cannot be parsed it is renamed to `daily.json.corrupt`.
|
|
145
|
+
- The plugin runner writes the full report to a private temp directory and deletes it before it exits.
|
|
678
146
|
|
|
679
|
-
|
|
680
|
-
- AWS credentials (`AKIA*`, secret keys)
|
|
681
|
-
- Bearer tokens
|
|
682
|
-
- HTTP credentials in URLs
|
|
683
|
-
- Email addresses
|
|
684
|
-
- Private keys (PEM format)
|
|
147
|
+
Nothing else. Hyntx never writes to `~/.claude/` or to your projects. Only the plugin edits `CLAUDE.md`, settings or command files, one change at a time, after you approve each one.
|
|
685
148
|
|
|
686
|
-
|
|
149
|
+
Set `HYNTX_HOME` to move `~/.hyntx/`, and `HYNTX_CLAUDE_PROJECTS_DIR` to read logs from another location. `OLLAMA_HOST` selects the Ollama server for `--engine ollama`.
|
|
687
150
|
|
|
688
|
-
|
|
689
|
-
2. **Extract prompts**: Filters user messages from conversations
|
|
690
|
-
3. **Sanitize**: Redacts sensitive information automatically
|
|
691
|
-
4. **Analyze**: Sends sanitized prompts to AI provider for pattern detection
|
|
692
|
-
5. **Report**: Displays findings with examples and suggestions
|
|
151
|
+
## Status and limits
|
|
693
152
|
|
|
694
|
-
|
|
153
|
+
Hyntx 4 is new and has been exercised on a small set of real logs.
|
|
695
154
|
|
|
696
|
-
-
|
|
697
|
-
-
|
|
698
|
-
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
- **Google Gemini** API key
|
|
155
|
+
- Findings are heuristics. Corrections in particular are guessed from phrasing; without an interpretation step they are marked unconfirmed, and the detector prefers missing a correction to inventing one.
|
|
156
|
+
- The log format is Claude Code's own and changes between versions. Unknown record types are counted and skipped, and `dataQuality.notes` in the report says what was not understood. Interruptions, user rejections and compactions are parsed from formats that the test fixtures model but that have not all been checked against real logs.
|
|
157
|
+
- Permission suggestions are limited to a short list of read-only commands, so many users will see none.
|
|
158
|
+
- With `--engine ollama` and a small model, verdicts are less reliable than with the default engine and can differ between runs.
|
|
159
|
+
- No cost figures: tokens only.
|
|
702
160
|
|
|
703
|
-
|
|
161
|
+
Open items are tracked in [docs/TECHNICAL_DEBT.md](docs/TECHNICAL_DEBT.md).
|
|
704
162
|
|
|
705
|
-
|
|
163
|
+
## Migrating from v3
|
|
706
164
|
|
|
707
|
-
|
|
165
|
+
Hyntx 4 does a different job, and most of v3 was removed rather than ported.
|
|
708
166
|
|
|
709
|
-
|
|
710
|
-
| ------------------- | ------------- | ---------- | --------- | -------------- | --------- |
|
|
711
|
-
| **Daily use** | `gemma3:4b` | 2-3B | ~2GB | ~2-5s/prompt | Good |
|
|
712
|
-
| **Production** | `mistral:7b` | 7B | ~4GB | ~5-10s/prompt | Better |
|
|
713
|
-
| **Maximum quality** | `qwen2.5:14b` | 14B | ~9GB | ~15-30s/prompt | Excellent |
|
|
167
|
+
Removed:
|
|
714
168
|
|
|
715
|
-
|
|
169
|
+
- Prompt-quality analysis: anti-pattern detection, the rules engine and its issue taxonomy, Before/After prompt rewrites
|
|
170
|
+
- Cloud providers called with API keys (Anthropic, Google Gemini), the provider fallback chain and rate limiting
|
|
171
|
+
- The interactive setup wizard and all shell-config editing; there is nothing to configure
|
|
172
|
+
- All `HYNTX_*` provider, model and API-key environment variables, and `.hyntxrc.json` project configuration
|
|
173
|
+
- Watch mode (`--watch`), periodic reminders (`--check-reminder`), `--dry-run`, `--date` and `--analysis-mode`
|
|
174
|
+
- The MCP server (`--mcp-server`)
|
|
175
|
+
- The results cache and per-run history under `~/.hyntx/` (`results/` and `history/` can be deleted)
|
|
176
|
+
- Exit code `3`
|
|
716
177
|
|
|
717
|
-
|
|
718
|
-
# Install recommended model (gemma3:4b)
|
|
719
|
-
ollama pull gemma3:4b
|
|
720
|
-
|
|
721
|
-
# Or choose a different model
|
|
722
|
-
ollama pull mistral:7b
|
|
723
|
-
ollama pull qwen2.5:14b
|
|
724
|
-
```
|
|
725
|
-
|
|
726
|
-
For complete model comparison, compatibility info, and performance notes, see the [Model Requirements documentation](docs/MINIMUM_VIABLE_MODEL.md).
|
|
727
|
-
|
|
728
|
-
## Troubleshooting
|
|
178
|
+
Changed:
|
|
729
179
|
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
```text
|
|
735
|
-
~/.claude/projects/<project-hash>/logs.jsonl
|
|
736
|
-
```
|
|
737
|
-
|
|
738
|
-
### "Ollama connection failed"
|
|
739
|
-
|
|
740
|
-
1. Check Ollama is running: `ollama list`
|
|
741
|
-
2. Start Ollama: `ollama serve`
|
|
742
|
-
3. Verify the host: `echo $HYNTX_OLLAMA_HOST` (default: `http://localhost:11434`)
|
|
743
|
-
|
|
744
|
-
### "No prompts found for date range"
|
|
745
|
-
|
|
746
|
-
- Check the date format: `YYYY-MM-DD`
|
|
747
|
-
- Verify you used Claude Code on those dates
|
|
748
|
-
- Try `--dry-run` to see what logs are being read
|
|
749
|
-
|
|
750
|
-
## Programmatic API
|
|
751
|
-
|
|
752
|
-
Hyntx can also be used as a library in your Node.js applications for custom integrations, CI/CD pipelines, or building tooling on top of the analysis engine.
|
|
753
|
-
|
|
754
|
-
### Installation
|
|
755
|
-
|
|
756
|
-
```bash
|
|
757
|
-
npm install hyntx
|
|
758
|
-
# or
|
|
759
|
-
pnpm add hyntx
|
|
760
|
-
```
|
|
761
|
-
|
|
762
|
-
### Basic Usage
|
|
763
|
-
|
|
764
|
-
```typescript
|
|
765
|
-
import {
|
|
766
|
-
analyzePrompts,
|
|
767
|
-
sanitizePrompts,
|
|
768
|
-
readLogs,
|
|
769
|
-
createProvider,
|
|
770
|
-
getEnvConfig,
|
|
771
|
-
type AnalysisResult,
|
|
772
|
-
type ExtractedPrompt,
|
|
773
|
-
} from 'hyntx';
|
|
774
|
-
|
|
775
|
-
// Read Claude Code logs for a specific date
|
|
776
|
-
const { prompts } = await readLogs({ date: 'today' });
|
|
777
|
-
|
|
778
|
-
// Sanitize prompts to remove secrets
|
|
779
|
-
const { prompts: sanitizedTexts } = sanitizePrompts(
|
|
780
|
-
prompts.map((p: ExtractedPrompt) => p.content),
|
|
781
|
-
);
|
|
782
|
-
|
|
783
|
-
// Get environment configuration
|
|
784
|
-
const config = getEnvConfig();
|
|
785
|
-
|
|
786
|
-
// Create an AI provider
|
|
787
|
-
const provider = await createProvider('ollama', config);
|
|
788
|
-
|
|
789
|
-
// Analyze the prompts
|
|
790
|
-
const result: AnalysisResult = await analyzePrompts({
|
|
791
|
-
provider,
|
|
792
|
-
prompts: sanitizedTexts,
|
|
793
|
-
date: '2025-12-26',
|
|
794
|
-
});
|
|
795
|
-
|
|
796
|
-
// Use the results
|
|
797
|
-
console.log(`Overall score: ${result.stats.overallScore}/10`);
|
|
798
|
-
console.log(`Patterns detected: ${result.patterns.length}`);
|
|
799
|
-
|
|
800
|
-
result.patterns.forEach((pattern) => {
|
|
801
|
-
console.log(`- ${pattern.name}: ${pattern.severity}`);
|
|
802
|
-
console.log(` Suggestion: ${pattern.suggestion}`);
|
|
803
|
-
});
|
|
804
|
-
```
|
|
805
|
-
|
|
806
|
-
### Advanced Examples
|
|
807
|
-
|
|
808
|
-
**CI/CD Integration** - Fail builds when prompt quality drops below threshold:
|
|
809
|
-
|
|
810
|
-
```typescript
|
|
811
|
-
import { analyzePrompts, readLogs, createProvider, getEnvConfig } from 'hyntx';
|
|
812
|
-
|
|
813
|
-
const config = getEnvConfig();
|
|
814
|
-
const provider = await createProvider('ollama', config);
|
|
815
|
-
const { prompts } = await readLogs({ date: 'today' });
|
|
816
|
-
|
|
817
|
-
const result = await analyzePrompts({
|
|
818
|
-
provider,
|
|
819
|
-
prompts: prompts.map((p) => p.content),
|
|
820
|
-
date: new Date().toISOString().split('T')[0],
|
|
821
|
-
});
|
|
822
|
-
|
|
823
|
-
// Fail CI if quality score is too low
|
|
824
|
-
const QUALITY_THRESHOLD = 7.0;
|
|
825
|
-
if (result.stats.overallScore < QUALITY_THRESHOLD) {
|
|
826
|
-
console.error(
|
|
827
|
-
`Quality score ${result.stats.overallScore} below threshold ${QUALITY_THRESHOLD}`,
|
|
828
|
-
);
|
|
829
|
-
process.exit(1);
|
|
830
|
-
}
|
|
831
|
-
```
|
|
832
|
-
|
|
833
|
-
**Custom Analysis** - Analyze specific prompts without reading logs:
|
|
834
|
-
|
|
835
|
-
```typescript
|
|
836
|
-
import { analyzePrompts, createProvider, getEnvConfig } from 'hyntx';
|
|
837
|
-
|
|
838
|
-
const config = getEnvConfig();
|
|
839
|
-
const provider = await createProvider('anthropic', config);
|
|
840
|
-
|
|
841
|
-
const customPrompts = [
|
|
842
|
-
'Fix the bug',
|
|
843
|
-
'Make it better',
|
|
844
|
-
'Refactor the authentication module to use JWT tokens instead of sessions',
|
|
845
|
-
];
|
|
846
|
-
|
|
847
|
-
const result = await analyzePrompts({
|
|
848
|
-
provider,
|
|
849
|
-
prompts: customPrompts,
|
|
850
|
-
date: '2025-12-26',
|
|
851
|
-
context: {
|
|
852
|
-
role: 'developer',
|
|
853
|
-
techStack: ['TypeScript', 'React', 'Node.js'],
|
|
854
|
-
},
|
|
855
|
-
});
|
|
856
|
-
|
|
857
|
-
console.log(result.patterns);
|
|
858
|
-
```
|
|
859
|
-
|
|
860
|
-
**History Management** - Track analysis over time:
|
|
861
|
-
|
|
862
|
-
```typescript
|
|
863
|
-
import {
|
|
864
|
-
analyzePrompts,
|
|
865
|
-
saveAnalysisResult,
|
|
866
|
-
loadAnalysisResult,
|
|
867
|
-
compareResults,
|
|
868
|
-
type HistoryMetadata,
|
|
869
|
-
} from 'hyntx';
|
|
870
|
-
|
|
871
|
-
// Run analysis
|
|
872
|
-
const result = await analyzePrompts({
|
|
873
|
-
/* ... */
|
|
874
|
-
});
|
|
875
|
-
|
|
876
|
-
// Save to history
|
|
877
|
-
const metadata: HistoryMetadata = {
|
|
878
|
-
date: '2025-12-26',
|
|
879
|
-
promptCount: result.stats.promptCount,
|
|
880
|
-
score: result.stats.overallScore,
|
|
881
|
-
projectFilter: undefined,
|
|
882
|
-
provider: 'ollama',
|
|
883
|
-
};
|
|
884
|
-
await saveAnalysisResult(result, metadata);
|
|
885
|
-
|
|
886
|
-
// Load previous analysis
|
|
887
|
-
const previousResult = await loadAnalysisResult('2025-12-19');
|
|
888
|
-
|
|
889
|
-
// Compare results
|
|
890
|
-
const comparison = await compareResults('2025-12-19', '2025-12-26');
|
|
891
|
-
console.log(
|
|
892
|
-
`Score change: ${comparison.scoreChange > 0 ? '+' : ''}${comparison.scoreChange}`,
|
|
893
|
-
);
|
|
894
|
-
```
|
|
895
|
-
|
|
896
|
-
### API Reference
|
|
897
|
-
|
|
898
|
-
#### Core Functions
|
|
899
|
-
|
|
900
|
-
- **`analyzePrompts(options: AnalysisOptions): Promise<AnalysisResult>`** - Analyze prompts and detect anti-patterns
|
|
901
|
-
- **`readLogs(options?: ReadLogsOptions): Promise<LogReadResult>`** - Read Claude Code conversation logs
|
|
902
|
-
- **`sanitize(text: string): SanitizeResult`** - Remove secrets from a single text
|
|
903
|
-
- **`sanitizePrompts(prompts: string[]): { prompts: string[]; totalRedacted: number }`** - Remove secrets from multiple prompts
|
|
904
|
-
|
|
905
|
-
#### Provider Functions
|
|
906
|
-
|
|
907
|
-
- **`createProvider(type: ProviderType, config: EnvConfig): Promise<AnalysisProvider>`** - Create an AI provider instance
|
|
908
|
-
- **`getAvailableProvider(config: EnvConfig, onFallback?: Function): Promise<AnalysisProvider>`** - Get first available provider with fallback
|
|
909
|
-
- **`getAllProviders(services: string[], config: EnvConfig): AnalysisProvider[]`** - Get all configured providers
|
|
910
|
-
|
|
911
|
-
#### History Functions
|
|
912
|
-
|
|
913
|
-
- **`saveAnalysisResult(result: AnalysisResult, metadata: HistoryMetadata): Promise<void>`** - Save analysis to history
|
|
914
|
-
- **`loadAnalysisResult(date: string): Promise<HistoryEntry | null>`** - Load analysis from history
|
|
915
|
-
- **`listAvailableDates(): Promise<string[]>`** - Get list of dates with saved analyses
|
|
916
|
-
- **`compareResults(beforeDate: string, afterDate: string): Promise<ComparisonResult>`** - Compare two analyses
|
|
917
|
-
|
|
918
|
-
#### Utility Functions
|
|
919
|
-
|
|
920
|
-
- **`getEnvConfig(): EnvConfig`** - Get environment configuration
|
|
921
|
-
- **`claudeProjectsExist(): boolean`** - Check if Claude projects directory exists
|
|
922
|
-
- **`parseDate(dateStr: string): Date`** - Parse date string to Date object
|
|
923
|
-
- **`groupByDay(prompts: ExtractedPrompt[]): DayGroup[]`** - Group prompts by day
|
|
924
|
-
|
|
925
|
-
#### Cache Functions
|
|
926
|
-
|
|
927
|
-
- **`generateCacheKey(config: CacheKeyConfig): string`** - Generate cache key for analysis
|
|
928
|
-
- **`getCachedResult(cacheKey: string): Promise<AnalysisResult | null>`** - Get cached result
|
|
929
|
-
- **`setCachedResult(cacheKey: string, result: AnalysisResult, ttlMinutes?: number): Promise<void>`** - Cache analysis result
|
|
930
|
-
|
|
931
|
-
### TypeScript Support
|
|
932
|
-
|
|
933
|
-
Hyntx is written in TypeScript and provides full type definitions. All types are exported:
|
|
934
|
-
|
|
935
|
-
```typescript
|
|
936
|
-
import type {
|
|
937
|
-
AnalysisResult,
|
|
938
|
-
AnalysisPattern,
|
|
939
|
-
AnalysisStats,
|
|
940
|
-
ExtractedPrompt,
|
|
941
|
-
ProviderType,
|
|
942
|
-
EnvConfig,
|
|
943
|
-
HistoryEntry,
|
|
944
|
-
ComparisonResult,
|
|
945
|
-
} from 'hyntx';
|
|
946
|
-
```
|
|
947
|
-
|
|
948
|
-
See the TypeScript definitions for complete API documentation.
|
|
180
|
+
- Input is the whole session (turns, tool calls, results, interruptions, compactions), not just prompt text
|
|
181
|
+
- Ollama is opt-in (`--engine ollama`) instead of the default; the default engine is your own Claude Code login, and `--no-llm` needs no model
|
|
182
|
+
- `--format json` now prints a versioned `Report` object (`schemaVersion: 1`); the v3 JSON shape is gone
|
|
183
|
+
- The library entry point exports the v4 pipeline (`readSessions`, `buildReport`, `interpretReport`, renderers); the v3 API is gone
|
|
949
184
|
|
|
950
185
|
## Development
|
|
951
186
|
|
|
952
|
-
### Setup
|
|
953
|
-
|
|
954
187
|
```bash
|
|
955
|
-
# Clone the repository
|
|
956
|
-
git clone https://github.com/jmlweb/hyntx.git
|
|
957
|
-
cd hyntx
|
|
958
|
-
|
|
959
|
-
# Install dependencies
|
|
960
188
|
pnpm install
|
|
961
|
-
|
|
962
|
-
# Run in development mode
|
|
963
|
-
pnpm dev
|
|
964
|
-
|
|
965
|
-
# Build
|
|
966
189
|
pnpm build
|
|
967
|
-
|
|
968
|
-
# Test the CLI
|
|
969
|
-
pnpm start
|
|
190
|
+
pnpm check && pnpm test
|
|
970
191
|
```
|
|
971
192
|
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
```text
|
|
975
|
-
hyntx/
|
|
976
|
-
โโโ src/
|
|
977
|
-
โ โโโ index.ts # Library entry point (re-exports api/)
|
|
978
|
-
โ โโโ cli.ts # CLI entry point
|
|
979
|
-
โ โโโ api/
|
|
980
|
-
โ โ โโโ index.ts # Public API surface
|
|
981
|
-
โ โโโ core/ # Core business logic
|
|
982
|
-
โ โ โโโ setup.ts # Interactive setup (multi-provider)
|
|
983
|
-
โ โ โโโ reminder.ts # Reminder system
|
|
984
|
-
โ โ โโโ log-reader.ts # Log parsing
|
|
985
|
-
โ โ โโโ schema-validator.ts # Log schema validation
|
|
986
|
-
โ โ โโโ sanitizer.ts # Secret redaction
|
|
987
|
-
โ โ โโโ analyzer.ts # Analysis orchestration + batching
|
|
988
|
-
โ โ โโโ reporter.ts # Output formatting (Before/After)
|
|
989
|
-
โ โ โโโ watcher.ts # Real-time log file monitoring
|
|
990
|
-
โ โ โโโ history.ts # Analysis history management
|
|
991
|
-
โ โโโ providers/ # AI providers
|
|
992
|
-
โ โ โโโ base.ts # Interface & prompts
|
|
993
|
-
โ โ โโโ ollama.ts # Ollama integration
|
|
994
|
-
โ โ โโโ anthropic.ts # Claude integration
|
|
995
|
-
โ โ โโโ google.ts # Gemini integration
|
|
996
|
-
โ โ โโโ index.ts # Provider factory with fallback
|
|
997
|
-
โ โโโ utils/ # Utility functions
|
|
998
|
-
โ โ โโโ env.ts # Environment config
|
|
999
|
-
โ โ โโโ shell-config.ts # Shell auto-configuration
|
|
1000
|
-
โ โ โโโ paths.ts # System path constants
|
|
1001
|
-
โ โ โโโ logger-base.ts # Base logger (no CLI deps)
|
|
1002
|
-
โ โ โโโ logger.ts # CLI logger (with chalk)
|
|
1003
|
-
โ โ โโโ terminal.ts # Terminal utilities
|
|
1004
|
-
โ โโโ types/
|
|
1005
|
-
โ โโโ index.ts # TypeScript type definitions
|
|
1006
|
-
โโโ docs/
|
|
1007
|
-
โ โโโ SPECS.md # Technical specifications
|
|
1008
|
-
โโโ package.json
|
|
1009
|
-
```
|
|
1010
|
-
|
|
1011
|
-
## Contributing
|
|
1012
|
-
|
|
1013
|
-
Contributions are welcome! Please:
|
|
1014
|
-
|
|
1015
|
-
1. Fork the repository
|
|
1016
|
-
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
1017
|
-
3. Commit your changes using Conventional Commits
|
|
1018
|
-
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
1019
|
-
5. Open a Pull Request
|
|
1020
|
-
|
|
1021
|
-
## Roadmap
|
|
1022
|
-
|
|
1023
|
-
For detailed development roadmap, planned features, and implementation status, see [GitHub Issues](https://github.com/jmlweb/hyntx/issues) and [GitHub Projects](https://github.com/jmlweb/hyntx/projects).
|
|
193
|
+
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [AGENTS.md](AGENTS.md).
|
|
1024
194
|
|
|
1025
195
|
## License
|
|
1026
196
|
|
|
1027
|
-
MIT
|
|
1028
|
-
|
|
1029
|
-
## Acknowledgments
|
|
1030
|
-
|
|
1031
|
-
- Built for [Claude Code](https://claude.com/claude-code) users
|
|
1032
|
-
- Inspired by retrospective practices in Agile development
|
|
1033
|
-
- Privacy-first approach inspired by local-first software movement
|
|
1034
|
-
|
|
1035
|
-
## Support
|
|
1036
|
-
|
|
1037
|
-
- **Issues**: [GitHub Issues](https://github.com/jmlweb/hyntx/issues)
|
|
1038
|
-
- **Discussions**: [GitHub Discussions](https://github.com/jmlweb/hyntx/discussions)
|
|
1039
|
-
|
|
1040
|
-
---
|
|
1041
|
-
|
|
1042
|
-
**Made with โค๏ธ for better prompt engineering**
|
|
197
|
+
MIT
|