hyntx 1.5.0 → 2.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
@@ -28,6 +28,7 @@ Think of it as a **retrospective code review for your prompts**.
28
28
  - **Flexible date filtering**: Analyze today, yesterday, specific dates, or date ranges
29
29
  - **Project filtering**: Focus on specific Claude Code projects
30
30
  - **Multiple output formats**: Beautiful terminal output or markdown reports
31
+ - **Watch mode**: Real-time monitoring and analysis of prompts as you work
31
32
  - **Smart reminders**: Oh-my-zsh style periodic reminders (configurable)
32
33
  - **Auto-configuration**: Saves settings to your shell config automatically
33
34
  - **Dry-run mode**: Preview what will be analyzed before sending to AI
@@ -97,6 +98,12 @@ hyntx --dry-run
97
98
 
98
99
  # Check reminder status
99
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
100
107
  ```
101
108
 
102
109
  ### Combining Options
@@ -111,9 +118,75 @@ hyntx --date yesterday --output yesterday-analysis.md
111
118
 
112
119
  ## Configuration
113
120
 
121
+ ### Rules Configuration
122
+
123
+ Hyntx allows you to customize which analysis rules are enabled and their severity levels through a `.hyntxrc.json` file in your project root.
124
+
125
+ #### Available Pattern IDs
126
+
127
+ - `vague` - Detects vague requests lacking specificity
128
+ - `no-context` - Detects missing background information
129
+ - `too-broad` - Detects overly broad requests that should be broken down
130
+ - `no-goal` - Detects prompts without a clear outcome
131
+ - `imperative` - Detects commands without explanation
132
+
133
+ #### Configuration Options
134
+
135
+ For each pattern, you can:
136
+
137
+ - **Disable**: Set `enabled: false` to skip detection
138
+ - **Override severity**: Set `severity` to `"low"`, `"medium"`, or `"high"`
139
+
140
+ #### Example Configuration
141
+
142
+ Create `.hyntxrc.json` in your project root:
143
+
144
+ ```json
145
+ {
146
+ "rules": {
147
+ "imperative": {
148
+ "enabled": false
149
+ },
150
+ "vague": {
151
+ "severity": "high"
152
+ },
153
+ "no-context": {
154
+ "severity": "high"
155
+ },
156
+ "too-broad": {
157
+ "severity": "medium"
158
+ }
159
+ }
160
+ }
161
+ ```
162
+
163
+ #### What Happens When Patterns Are Disabled
164
+
165
+ - **Filtered out**: Disabled patterns are completely excluded from analysis results
166
+ - **No detection**: The AI will not look for those specific issues
167
+ - **Updated stats**: Pattern counts and frequency calculations exclude disabled patterns
168
+ - **Warning**: If all patterns are disabled, you'll see a warning that no analysis will occur
169
+
170
+ #### How Severity Overrides Work
171
+
172
+ - **Changed priority**: Patterns are sorted by severity (high → medium → low), then by frequency
173
+ - **Updated display**: The reporter shows severity badges based on your configuration
174
+ - **No effect on detection**: Severity only affects sorting and display, not whether the pattern is detected
175
+
176
+ #### Configuration Warnings
177
+
178
+ Hyntx will warn you about:
179
+
180
+ - **Invalid pattern IDs**: If you specify a pattern ID that doesn't exist
181
+ - **All patterns disabled**: If your configuration disables every pattern
182
+
183
+ These warnings appear immediately when the configuration is loaded.
184
+
185
+ ### Environment Variables
186
+
114
187
  Hyntx uses environment variables for configuration. The interactive setup can **auto-save** these to your shell config (`~/.zshrc`, `~/.bashrc`).
115
188
 
116
- ### Multi-Provider Configuration
189
+ #### Multi-Provider Configuration
117
190
 
118
191
  Configure one or more providers in priority order. Hyntx will try each provider in order and fall back to the next if unavailable.
119
192
 
@@ -133,7 +206,7 @@ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
133
206
  export HYNTX_OLLAMA_MODEL=llama3.2
134
207
  ```
135
208
 
136
- ### Provider-Specific Variables
209
+ #### Provider-Specific Variables
137
210
 
138
211
  **Ollama:**
139
212
 
@@ -156,14 +229,14 @@ export HYNTX_OLLAMA_MODEL=llama3.2
156
229
  | `HYNTX_GOOGLE_MODEL` | `gemini-2.0-flash-exp` | Model to use |
157
230
  | `HYNTX_GOOGLE_KEY` | - | API key (required) |
158
231
 
159
- ### Reminder Settings
232
+ #### Reminder Settings
160
233
 
161
234
  ```bash
162
235
  # Set reminder frequency (7d, 14d, 30d, or never)
163
236
  export HYNTX_REMINDER=7d
164
237
  ```
165
238
 
166
- ### Complete Example
239
+ #### Complete Example
167
240
 
168
241
  ```bash
169
242
  # Add to ~/.zshrc or ~/.bashrc (or let Hyntx auto-save it)
@@ -287,6 +360,219 @@ When running, Hyntx will show fallback behavior:
287
360
  ──────────────────────────────────────────────────
288
361
  ```
289
362
 
363
+ ## MCP Integration
364
+
365
+ 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.
366
+
367
+ ### Quick Setup
368
+
369
+ Add hyntx to your Claude Code MCP configuration:
370
+
371
+ **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
372
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
373
+ **Linux:** `~/.config/Claude/claude_desktop_config.json`
374
+
375
+ ```json
376
+ {
377
+ "mcpServers": {
378
+ "hyntx": {
379
+ "command": "hyntx",
380
+ "args": ["--mcp-server"]
381
+ }
382
+ }
383
+ }
384
+ ```
385
+
386
+ After editing, restart Claude Code. The hyntx tools will be available in your conversations.
387
+
388
+ ### Prerequisites
389
+
390
+ - **Hyntx installed globally**: `npm install -g hyntx`
391
+ - **AI provider configured**: Set up Ollama (recommended) or cloud providers via environment variables
392
+
393
+ If using Ollama (recommended for privacy):
394
+
395
+ ```bash
396
+ # Ensure Ollama is running
397
+ ollama serve
398
+
399
+ # Pull a model if needed
400
+ ollama pull llama3.2
401
+
402
+ # Set environment variables (add to ~/.zshrc or ~/.bashrc)
403
+ export HYNTX_SERVICES=ollama
404
+ export HYNTX_OLLAMA_MODEL=llama3.2
405
+ ```
406
+
407
+ ### Available MCP Tools
408
+
409
+ Hyntx exposes three tools through the MCP interface:
410
+
411
+ #### analyze-prompt
412
+
413
+ Analyze a prompt to detect anti-patterns, issues, and get improvement suggestions.
414
+
415
+ **Input Schema:**
416
+
417
+ | Parameter | Type | Required | Description |
418
+ | --------- | ------ | -------- | ----------------------------------------------------- |
419
+ | `prompt` | string | Yes | The prompt text to analyze |
420
+ | `date` | string | No | Date context in ISO format. Defaults to current date. |
421
+
422
+ **Example Output:**
423
+
424
+ ```json
425
+ {
426
+ "patterns": [
427
+ {
428
+ "id": "no-context",
429
+ "name": "Missing Context",
430
+ "severity": "high",
431
+ "frequency": "100%",
432
+ "suggestion": "Include specific error messages and file paths",
433
+ "examples": ["Fix the bug in auth"]
434
+ }
435
+ ],
436
+ "stats": {
437
+ "promptCount": 1,
438
+ "overallScore": 4.5
439
+ },
440
+ "topSuggestion": "Add error messages and stack traces for faster resolution"
441
+ }
442
+ ```
443
+
444
+ #### suggest-improvements
445
+
446
+ Get concrete before/after rewrites showing how to improve a prompt.
447
+
448
+ **Input Schema:**
449
+
450
+ | Parameter | Type | Required | Description |
451
+ | --------- | ------ | -------- | ----------------------------------------------------- |
452
+ | `prompt` | string | Yes | The prompt text to analyze for improvements |
453
+ | `date` | string | No | Date context in ISO format. Defaults to current date. |
454
+
455
+ **Example Output:**
456
+
457
+ ```json
458
+ {
459
+ "improvements": [
460
+ {
461
+ "issue": "Missing Context",
462
+ "before": "Fix the bug in auth",
463
+ "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.",
464
+ "suggestion": "Include specific error messages, framework versions, and file paths"
465
+ }
466
+ ],
467
+ "summary": "Found 1 improvement(s)",
468
+ "topSuggestion": "Add error messages and stack traces for faster resolution"
469
+ }
470
+ ```
471
+
472
+ #### check-context
473
+
474
+ Verify if a prompt has sufficient context for effective AI interaction.
475
+
476
+ **Input Schema:**
477
+
478
+ | Parameter | Type | Required | Description |
479
+ | --------- | ------ | -------- | ----------------------------------------------------- |
480
+ | `prompt` | string | Yes | The prompt text to check for context |
481
+ | `date` | string | No | Date context in ISO format. Defaults to current date. |
482
+
483
+ **Example Output:**
484
+
485
+ ```json
486
+ {
487
+ "hasSufficientContext": false,
488
+ "score": 4.5,
489
+ "issues": ["Missing Context", "Vague Instructions"],
490
+ "suggestion": "Include specific error messages and file paths",
491
+ "details": "Prompt lacks sufficient context for effective AI interaction"
492
+ }
493
+ ```
494
+
495
+ ### Usage Examples
496
+
497
+ Once configured, you can use these tools in your Claude Code conversations:
498
+
499
+ **Analyze a prompt before sending:**
500
+
501
+ ```text
502
+ Use the analyze-prompt tool to check: "Fix the login bug"
503
+ ```
504
+
505
+ **Get improvement suggestions:**
506
+
507
+ ```text
508
+ Use suggest-improvements on: "Make the API faster"
509
+ ```
510
+
511
+ **Check if your prompt has enough context:**
512
+
513
+ ```text
514
+ Use check-context to verify: "Update the component to handle errors"
515
+ ```
516
+
517
+ ### MCP Server Troubleshooting
518
+
519
+ #### "Server failed to start"
520
+
521
+ 1. Verify hyntx is installed globally:
522
+
523
+ ```bash
524
+ which hyntx
525
+ # Should output: /usr/local/bin/hyntx or similar
526
+ ```
527
+
528
+ 2. Test manual startup:
529
+
530
+ ```bash
531
+ hyntx --mcp-server
532
+ # Should output: MCP server running on stdio
533
+ ```
534
+
535
+ 3. Check environment variables are set (if using cloud providers):
536
+
537
+ ```bash
538
+ echo $HYNTX_SERVICES
539
+ echo $HYNTX_ANTHROPIC_KEY # if using Anthropic
540
+ ```
541
+
542
+ #### "Analysis failed: Provider not available"
543
+
544
+ 1. If using Ollama, ensure it's running:
545
+
546
+ ```bash
547
+ ollama list
548
+ # If no output, start Ollama:
549
+ ollama serve
550
+ ```
551
+
552
+ 2. If using cloud providers, verify API keys are set:
553
+
554
+ ```bash
555
+ # Check if keys are configured
556
+ env | grep HYNTX_
557
+ ```
558
+
559
+ #### "Tools not appearing in Claude Code"
560
+
561
+ 1. Restart Claude Code completely after config changes
562
+ 2. Verify the config file path is correct for your OS
563
+ 3. Check JSON syntax in the config file:
564
+
565
+ ```bash
566
+ # macOS
567
+ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
568
+ ```
569
+
570
+ #### "Slow responses"
571
+
572
+ - Local Ollama models are fastest but require GPU for best performance
573
+ - Consider using a faster model: `export HYNTX_OLLAMA_MODEL=llama3.2:1b`
574
+ - Cloud providers (Anthropic, Google) offer faster responses but require API keys
575
+
290
576
  ## Privacy & Security
291
577
 
292
578
  Hyntx takes your privacy seriously:
@@ -341,6 +627,206 @@ Make sure you've used Claude Code at least once. Logs are stored in:
341
627
  - Verify you used Claude Code on those dates
342
628
  - Try `--dry-run` to see what logs are being read
343
629
 
630
+ ## Programmatic API
631
+
632
+ 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.
633
+
634
+ ### Installation
635
+
636
+ ```bash
637
+ npm install hyntx
638
+ # or
639
+ pnpm add hyntx
640
+ ```
641
+
642
+ ### Basic Usage
643
+
644
+ ```typescript
645
+ import {
646
+ analyzePrompts,
647
+ sanitizePrompts,
648
+ readLogs,
649
+ createProvider,
650
+ getEnvConfig,
651
+ type AnalysisResult,
652
+ type ExtractedPrompt,
653
+ } from 'hyntx';
654
+
655
+ // Read Claude Code logs for a specific date
656
+ const { prompts } = await readLogs({ date: 'today' });
657
+
658
+ // Sanitize prompts to remove secrets
659
+ const { prompts: sanitizedTexts } = sanitizePrompts(
660
+ prompts.map((p: ExtractedPrompt) => p.content),
661
+ );
662
+
663
+ // Get environment configuration
664
+ const config = getEnvConfig();
665
+
666
+ // Create an AI provider
667
+ const provider = await createProvider('ollama', config);
668
+
669
+ // Analyze the prompts
670
+ const result: AnalysisResult = await analyzePrompts({
671
+ provider,
672
+ prompts: sanitizedTexts,
673
+ date: '2025-12-26',
674
+ });
675
+
676
+ // Use the results
677
+ console.log(`Overall score: ${result.stats.overallScore}/10`);
678
+ console.log(`Patterns detected: ${result.patterns.length}`);
679
+
680
+ result.patterns.forEach((pattern) => {
681
+ console.log(`- ${pattern.name}: ${pattern.severity}`);
682
+ console.log(` Suggestion: ${pattern.suggestion}`);
683
+ });
684
+ ```
685
+
686
+ ### Advanced Examples
687
+
688
+ **CI/CD Integration** - Fail builds when prompt quality drops below threshold:
689
+
690
+ ```typescript
691
+ import { analyzePrompts, readLogs, createProvider, getEnvConfig } from 'hyntx';
692
+
693
+ const config = getEnvConfig();
694
+ const provider = await createProvider('ollama', config);
695
+ const { prompts } = await readLogs({ date: 'today' });
696
+
697
+ const result = await analyzePrompts({
698
+ provider,
699
+ prompts: prompts.map((p) => p.content),
700
+ date: new Date().toISOString().split('T')[0],
701
+ });
702
+
703
+ // Fail CI if quality score is too low
704
+ const QUALITY_THRESHOLD = 7.0;
705
+ if (result.stats.overallScore < QUALITY_THRESHOLD) {
706
+ console.error(
707
+ `Quality score ${result.stats.overallScore} below threshold ${QUALITY_THRESHOLD}`,
708
+ );
709
+ process.exit(1);
710
+ }
711
+ ```
712
+
713
+ **Custom Analysis** - Analyze specific prompts without reading logs:
714
+
715
+ ```typescript
716
+ import { analyzePrompts, createProvider, getEnvConfig } from 'hyntx';
717
+
718
+ const config = getEnvConfig();
719
+ const provider = await createProvider('anthropic', config);
720
+
721
+ const customPrompts = [
722
+ 'Fix the bug',
723
+ 'Make it better',
724
+ 'Refactor the authentication module to use JWT tokens instead of sessions',
725
+ ];
726
+
727
+ const result = await analyzePrompts({
728
+ provider,
729
+ prompts: customPrompts,
730
+ date: '2025-12-26',
731
+ context: {
732
+ role: 'developer',
733
+ techStack: ['TypeScript', 'React', 'Node.js'],
734
+ },
735
+ });
736
+
737
+ console.log(result.patterns);
738
+ ```
739
+
740
+ **History Management** - Track analysis over time:
741
+
742
+ ```typescript
743
+ import {
744
+ analyzePrompts,
745
+ saveAnalysisResult,
746
+ loadAnalysisResult,
747
+ compareResults,
748
+ type HistoryMetadata,
749
+ } from 'hyntx';
750
+
751
+ // Run analysis
752
+ const result = await analyzePrompts({
753
+ /* ... */
754
+ });
755
+
756
+ // Save to history
757
+ const metadata: HistoryMetadata = {
758
+ date: '2025-12-26',
759
+ promptCount: result.stats.promptCount,
760
+ score: result.stats.overallScore,
761
+ projectFilter: undefined,
762
+ provider: 'ollama',
763
+ };
764
+ await saveAnalysisResult(result, metadata);
765
+
766
+ // Load previous analysis
767
+ const previousResult = await loadAnalysisResult('2025-12-19');
768
+
769
+ // Compare results
770
+ const comparison = await compareResults('2025-12-19', '2025-12-26');
771
+ console.log(
772
+ `Score change: ${comparison.scoreChange > 0 ? '+' : ''}${comparison.scoreChange}`,
773
+ );
774
+ ```
775
+
776
+ ### API Reference
777
+
778
+ #### Core Functions
779
+
780
+ - **`analyzePrompts(options: AnalysisOptions): Promise<AnalysisResult>`** - Analyze prompts and detect anti-patterns
781
+ - **`readLogs(options?: ReadLogsOptions): Promise<LogReadResult>`** - Read Claude Code conversation logs
782
+ - **`sanitize(text: string): SanitizeResult`** - Remove secrets from a single text
783
+ - **`sanitizePrompts(prompts: string[]): { prompts: string[]; totalRedacted: number }`** - Remove secrets from multiple prompts
784
+
785
+ #### Provider Functions
786
+
787
+ - **`createProvider(type: ProviderType, config: EnvConfig): Promise<AnalysisProvider>`** - Create an AI provider instance
788
+ - **`getAvailableProvider(config: EnvConfig, onFallback?: Function): Promise<AnalysisProvider>`** - Get first available provider with fallback
789
+ - **`getAllProviders(services: string[], config: EnvConfig): AnalysisProvider[]`** - Get all configured providers
790
+
791
+ #### History Functions
792
+
793
+ - **`saveAnalysisResult(result: AnalysisResult, metadata: HistoryMetadata): Promise<void>`** - Save analysis to history
794
+ - **`loadAnalysisResult(date: string): Promise<HistoryEntry | null>`** - Load analysis from history
795
+ - **`listAvailableDates(): Promise<string[]>`** - Get list of dates with saved analyses
796
+ - **`compareResults(beforeDate: string, afterDate: string): Promise<ComparisonResult>`** - Compare two analyses
797
+
798
+ #### Utility Functions
799
+
800
+ - **`getEnvConfig(): EnvConfig`** - Get environment configuration
801
+ - **`claudeProjectsExist(): boolean`** - Check if Claude projects directory exists
802
+ - **`parseDate(dateStr: string): Date`** - Parse date string to Date object
803
+ - **`groupByDay(prompts: ExtractedPrompt[]): DayGroup[]`** - Group prompts by day
804
+
805
+ #### Cache Functions
806
+
807
+ - **`generateCacheKey(config: CacheKeyConfig): string`** - Generate cache key for analysis
808
+ - **`getCachedResult(cacheKey: string): Promise<AnalysisResult | null>`** - Get cached result
809
+ - **`setCachedResult(cacheKey: string, result: AnalysisResult, ttlMinutes?: number): Promise<void>`** - Cache analysis result
810
+
811
+ ### TypeScript Support
812
+
813
+ Hyntx is written in TypeScript and provides full type definitions. All types are exported:
814
+
815
+ ```typescript
816
+ import type {
817
+ AnalysisResult,
818
+ AnalysisPattern,
819
+ AnalysisStats,
820
+ ExtractedPrompt,
821
+ ProviderType,
822
+ EnvConfig,
823
+ HistoryEntry,
824
+ ComparisonResult,
825
+ } from 'hyntx';
826
+ ```
827
+
828
+ See the TypeScript definitions for complete API documentation.
829
+
344
830
  ## Development
345
831
 
346
832
  ### Setup
@@ -368,7 +854,10 @@ pnpm start
368
854
  ```text
369
855
  hyntx/
370
856
  ├── src/
371
- │ ├── index.ts # CLI entry point
857
+ │ ├── index.ts # Library entry point (re-exports api/)
858
+ │ ├── cli.ts # CLI entry point
859
+ │ ├── api/
860
+ │ │ └── index.ts # Public API surface
372
861
  │ ├── core/ # Core business logic
373
862
  │ │ ├── setup.ts # Interactive setup (multi-provider)
374
863
  │ │ ├── reminder.ts # Reminder system
@@ -376,7 +865,9 @@ hyntx/
376
865
  │ │ ├── schema-validator.ts # Log schema validation
377
866
  │ │ ├── sanitizer.ts # Secret redaction
378
867
  │ │ ├── analyzer.ts # Analysis orchestration + batching
379
- │ │ └── reporter.ts # Output formatting (Before/After)
868
+ │ │ ├── reporter.ts # Output formatting (Before/After)
869
+ │ │ ├── watcher.ts # Real-time log file monitoring
870
+ │ │ └── history.ts # Analysis history management
380
871
  │ ├── providers/ # AI providers
381
872
  │ │ ├── base.ts # Interface & prompts
382
873
  │ │ ├── ollama.ts # Ollama integration
@@ -387,6 +878,8 @@ hyntx/
387
878
  │ │ ├── env.ts # Environment config
388
879
  │ │ ├── shell-config.ts # Shell auto-configuration
389
880
  │ │ ├── paths.ts # System path constants
881
+ │ │ ├── logger-base.ts # Base logger (no CLI deps)
882
+ │ │ ├── logger.ts # CLI logger (with chalk)
390
883
  │ │ └── terminal.ts # Terminal utilities
391
884
  │ └── types/
392
885
  │ └── index.ts # TypeScript type definitions