hyntx 3.0.1 โ†’ 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 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
  [![npm version](https://img.shields.io/npm/v/hyntx.svg)](https://www.npmjs.com/package/hyntx)
6
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
5
  [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
8
6
 
9
- > ๐Ÿงช **BETA**: This project is functional but still evolving. Feedback and contributions welcome!
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
- **Performance Note**: Numbers based on `gemma3:4b` on CPU. Actual speed varies by hardware, model size, and prompt complexity.
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
- **Detailed Guide**: See [Analysis Modes Documentation](./docs/ANALYSIS_MODES.md) for comprehensive comparison, examples, and decision guidelines.
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
- ### Rules Configuration
13
+ ## How it differs
184
14
 
185
- Hyntx allows you to customize which analysis rules are enabled and their severity levels through a `.hyntxrc.json` file in your project root.
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
- #### Available Pattern IDs
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
- - `vague` - Detects vague requests lacking specificity
190
- - `no-context` - Detects missing background information
191
- - `too-broad` - Detects overly broad requests that should be broken down
192
- - `no-goal` - Detects prompts without a clear outcome
193
- - `imperative` - Detects commands without explanation
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
- #### Configuration Options
25
+ ## Install and run
196
26
 
197
- For each pattern, you can:
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
- # Single provider (Ollama only)
257
- export HYNTX_SERVICES=ollama
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
- # Set reminder frequency (7d, 14d, 30d, or never)
298
- export HYNTX_REMINDER=7d
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
- #### Complete Example
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
- ## AI Provider Setup
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
- โš ๏ธ ollama unavailable, trying anthropic...
380
- โœ… anthropic connected
381
- ```
48
+ hyntx 2026-09-04 to 2026-10-03 (30 days) - all projects
382
49
 
383
- ## Example Output
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
- ```text
386
- ๐Ÿ“Š Hyntx - 2025-01-20
387
- โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
53
+ Top insights (3 of 6)
388
54
 
389
- ๐Ÿ“ˆ Statistics
390
- Prompts: 15
391
- Projects: my-app, backend-api
392
- Score: 6.5/10
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
- โš ๏ธ Patterns (3)
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
- ๐Ÿ”ด Missing Context (60%)
397
- โ€ข "Fix the bug in auth"
398
- โ€ข "Update the component"
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
- Before:
402
- โŒ "Fix the bug in auth"
403
- After:
404
- โœ… "Fix authentication bug in src/auth/login.ts where users get
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
- ## MCP Integration
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
- ### Quick Setup
79
+ ## Claude Code plugin
430
80
 
431
- Add hyntx to your Claude Code MCP configuration. You have two options:
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
- # Add using Claude Code CLI
439
- claude mcp add hyntx
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
- #### Option 2: Project-scoped
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
- Use the analyze-prompt tool to check: "Fix the login bug"
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
- **Get improvement suggestions:**
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
- ```text
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
- 2. If using cloud providers, verify API keys are set:
100
+ ## Interpretation engines and privacy
637
101
 
638
- ```bash
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
- #### "Tools not appearing in Claude Code"
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
- 1. Restart Claude Code completely after config changes
646
- 2. Verify the config file exists and is in the correct location:
647
- - User-scoped: `~/.claude.json`
648
- - Project-scoped: `.mcp.json` (in project root)
649
- 3. Check JSON syntax in the config file:
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
- ```bash
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
- # Or verify project-scoped config
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
- # Or use Claude Code CLI to list MCP servers
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
- #### "Slow responses"
118
+ ## Options
663
119
 
664
- - Local Ollama models are fastest but require GPU for best performance
665
- - Consider using a faster model: `export HYNTX_OLLAMA_MODEL=gemma3:4b:1b`
666
- - Cloud providers (Anthropic, Google) offer faster responses but require API keys
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
- ## Privacy & Security
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
- Hyntx takes your privacy seriously:
138
+ Full reference: [docs/CLI.md](docs/CLI.md).
671
139
 
672
- - **Local-first**: Defaults to Ollama for offline analysis
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
- ### What Gets Redacted?
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
- - OpenAI/Anthropic API keys (`sk-*`, `claude-*`)
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
- ## How It Works
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
- 1. **Read logs**: Parses Claude Code conversation logs from `~/.claude/projects/`
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
- ## Requirements
153
+ Hyntx 4 is new and has been exercised on a small set of real logs.
695
154
 
696
- - **Node.js**: 22.0.0 or higher
697
- - **Claude Code**: Must have Claude Code installed and at least one conversation
698
- - **AI Provider**: At least one of the following:
699
- - **Ollama** (recommended for privacy and cost savings)
700
- - **Anthropic Claude** API key
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
- ### Ollama Model Requirements
161
+ Open items are tracked in [docs/TECHNICAL_DEBT.md](docs/TECHNICAL_DEBT.md).
704
162
 
705
- For local analysis with Ollama, you need to have a compatible model installed. See [docs/MINIMUM_VIABLE_MODEL.md](docs/MINIMUM_VIABLE_MODEL.md) for detailed recommendations and performance benchmarks.
163
+ ## Migrating from v3
706
164
 
707
- **Quick picks**:
165
+ Hyntx 4 does a different job, and most of v3 was removed rather than ported.
708
166
 
709
- | Use Case | Model | Parameters | Disk Size | Speed (CPU) | Quality |
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
- **Installation**:
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
- ```bash
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
- ### "No Claude Code logs found"
731
-
732
- Make sure you've used Claude Code at least once. Logs are stored in:
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
- ### Project Structure
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 License - see [LICENSE](LICENSE) file for details.
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