hyntx 0.0.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Jose Manuel Lucas Munoz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,432 @@
1
+ # Hyntx
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
+ [![npm version](https://img.shields.io/npm/v/hyntx.svg)](https://www.npmjs.com/package/hyntx)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
8
+
9
+ > **🚧 NOT READY FOR USE**: Hyntx is currently **under active development** and **not yet ready for production use**. The tool is not functional at this time. This README describes the planned features and functionality. For the current development status, implementation progress, and what's actually working, please see the [ROADMAP.md](ROADMAP.md).
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
+ - **Smart reminders**: Oh-my-zsh style periodic reminders (configurable)
32
+ - **Auto-configuration**: Saves settings to your shell config automatically
33
+ - **Dry-run mode**: Preview what will be analyzed before sending to AI
34
+
35
+ ## Installation
36
+
37
+ > **Note**: Hyntx is not yet ready for use. The installation instructions below are for reference only. See [ROADMAP.md](ROADMAP.md) for development status.
38
+
39
+ ### NPM (Global)
40
+
41
+ ```bash
42
+ npm install -g hyntx
43
+ ```
44
+
45
+ ### NPX (No installation)
46
+
47
+ ```bash
48
+ npx hyntx
49
+ ```
50
+
51
+ ### PNPM
52
+
53
+ ```bash
54
+ pnpm add -g hyntx
55
+ ```
56
+
57
+ ## Quick Start
58
+
59
+ Run Hyntx with a single command:
60
+
61
+ ```bash
62
+ hyntx
63
+ ```
64
+
65
+ On first run, Hyntx will guide you through an interactive setup:
66
+
67
+ 1. Select one or more AI providers (Ollama recommended for privacy)
68
+ 2. Configure models and API keys for selected providers
69
+ 3. Set reminder preferences
70
+ 4. **Auto-save** configuration to your shell (or get manual instructions)
71
+
72
+ That's it! Hyntx will analyze today's prompts and show you improvement suggestions with concrete "Before/After" examples.
73
+
74
+ ## Usage
75
+
76
+ ### Basic Commands
77
+
78
+ ```bash
79
+ # Analyze today's prompts
80
+ hyntx
81
+
82
+ # Analyze yesterday
83
+ hyntx --date yesterday
84
+
85
+ # Analyze a specific date
86
+ hyntx --date 2025-01-20
87
+
88
+ # Analyze a date range
89
+ hyntx --from 2025-01-15 --to 2025-01-20
90
+
91
+ # Filter by project name
92
+ hyntx --project my-awesome-app
93
+
94
+ # Save report to file
95
+ hyntx --output report.md
96
+
97
+ # Preview without sending to AI
98
+ hyntx --dry-run
99
+
100
+ # Check reminder status
101
+ hyntx --check-reminder
102
+ ```
103
+
104
+ ### Combining Options
105
+
106
+ ```bash
107
+ # Analyze last week for a specific project
108
+ hyntx --from 2025-01-15 --to 2025-01-22 --project backend-api
109
+
110
+ # Generate markdown report for yesterday
111
+ hyntx --date yesterday --output yesterday-analysis.md
112
+ ```
113
+
114
+ ## Configuration
115
+
116
+ Hyntx uses environment variables for configuration. The interactive setup can **auto-save** these to your shell config (`~/.zshrc`, `~/.bashrc`).
117
+
118
+ ### Multi-Provider Configuration
119
+
120
+ Configure one or more providers in priority order. Hyntx will try each provider in order and fall back to the next if unavailable.
121
+
122
+ ```bash
123
+ # Single provider (Ollama only)
124
+ export HYNTX_SERVICES=ollama
125
+ export HYNTX_OLLAMA_MODEL=llama3.2
126
+
127
+ # Multi-provider with fallback (tries Ollama first, then Anthropic)
128
+ export HYNTX_SERVICES=ollama,anthropic
129
+ export HYNTX_OLLAMA_MODEL=llama3.2
130
+ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
131
+
132
+ # Cloud-first with local fallback
133
+ export HYNTX_SERVICES=anthropic,ollama
134
+ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
135
+ export HYNTX_OLLAMA_MODEL=llama3.2
136
+ ```
137
+
138
+ ### Provider-Specific Variables
139
+
140
+ **Ollama:**
141
+
142
+ | Variable | Default | Description |
143
+ | -------------------- | ------------------------ | ----------------- |
144
+ | `HYNTX_OLLAMA_MODEL` | `llama3.2` | Model to use |
145
+ | `HYNTX_OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
146
+
147
+ **Anthropic:**
148
+
149
+ | Variable | Default | Description |
150
+ | ----------------------- | ------------------------- | ------------------ |
151
+ | `HYNTX_ANTHROPIC_MODEL` | `claude-3-5-haiku-latest` | Model to use |
152
+ | `HYNTX_ANTHROPIC_KEY` | - | API key (required) |
153
+
154
+ **Google:**
155
+
156
+ | Variable | Default | Description |
157
+ | -------------------- | ---------------------- | ------------------ |
158
+ | `HYNTX_GOOGLE_MODEL` | `gemini-2.0-flash-exp` | Model to use |
159
+ | `HYNTX_GOOGLE_KEY` | - | API key (required) |
160
+
161
+ ### Reminder Settings
162
+
163
+ ```bash
164
+ # Set reminder frequency (7d, 14d, 30d, or never)
165
+ export HYNTX_REMINDER=7d
166
+ ```
167
+
168
+ ### Complete Example
169
+
170
+ ```bash
171
+ # Add to ~/.zshrc or ~/.bashrc (or let Hyntx auto-save it)
172
+ export HYNTX_SERVICES=ollama,anthropic
173
+ export HYNTX_OLLAMA_MODEL=llama3.2
174
+ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
175
+ export HYNTX_REMINDER=14d
176
+
177
+ # Optional: Enable periodic reminders
178
+ hyntx --check-reminder 2>/dev/null
179
+ ```
180
+
181
+ Then reload your shell:
182
+
183
+ ```bash
184
+ source ~/.zshrc # or source ~/.bashrc
185
+ ```
186
+
187
+ ## AI Provider Setup
188
+
189
+ ### Ollama (Recommended)
190
+
191
+ Ollama runs AI models locally for **privacy and cost savings**.
192
+
193
+ 1. Install Ollama: [ollama.ai](https://ollama.ai)
194
+ 2. Pull a model:
195
+
196
+ ```bash
197
+ ollama pull llama3.2
198
+ ```
199
+
200
+ 3. Verify it's running:
201
+
202
+ ```bash
203
+ ollama list
204
+ ```
205
+
206
+ 4. Run Hyntx (it will auto-configure on first run):
207
+
208
+ ```bash
209
+ hyntx
210
+ ```
211
+
212
+ ### Anthropic Claude
213
+
214
+ 1. Get API key from [console.anthropic.com](https://console.anthropic.com/)
215
+ 2. Run Hyntx and select Anthropic during setup, or set manually:
216
+
217
+ ```bash
218
+ export HYNTX_SERVICES=anthropic
219
+ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
220
+ ```
221
+
222
+ ### Google Gemini
223
+
224
+ 1. Get API key from [ai.google.dev](https://ai.google.dev)
225
+ 2. Run Hyntx and select Google during setup, or set manually:
226
+
227
+ ```bash
228
+ export HYNTX_SERVICES=google
229
+ export HYNTX_GOOGLE_KEY=your-google-api-key
230
+ ```
231
+
232
+ ### Using Multiple Providers
233
+
234
+ Configure multiple providers for automatic fallback:
235
+
236
+ ```bash
237
+ # If Ollama is down, automatically try Anthropic
238
+ export HYNTX_SERVICES=ollama,anthropic
239
+ export HYNTX_OLLAMA_MODEL=llama3.2
240
+ export HYNTX_ANTHROPIC_KEY=sk-ant-your-key-here
241
+ ```
242
+
243
+ When running, Hyntx will show fallback behavior:
244
+
245
+ ```text
246
+ ⚠️ ollama unavailable, trying anthropic...
247
+ ✅ anthropic connected
248
+ ```
249
+
250
+ ## Example Output
251
+
252
+ ```text
253
+ 📊 Hyntx - 2025-01-20
254
+ ──────────────────────────────────────────────────
255
+
256
+ 📈 Statistics
257
+ Prompts: 15
258
+ Projects: my-app, backend-api
259
+ Score: 6.5/10
260
+
261
+ ⚠️ Patterns (3)
262
+
263
+ 🔴 Missing Context (60%)
264
+ • "Fix the bug in auth"
265
+ • "Update the component"
266
+ 💡 Include specific error messages, framework versions, and file paths
267
+
268
+ Before:
269
+ ❌ "Fix the bug in auth"
270
+ After:
271
+ ✅ "Fix authentication bug in src/auth/login.ts where users get
272
+ 'Invalid token' error. Using Next.js 14.1.0 with next-auth 4.24.5."
273
+
274
+ 🟡 Vague Instructions (40%)
275
+ • "Make it better"
276
+ • "Improve this"
277
+ 💡 Define specific success criteria and expected outcomes
278
+
279
+ Before:
280
+ ❌ "Make it better"
281
+ After:
282
+ ✅ "Optimize the database query to reduce response time from 500ms
283
+ to under 100ms. Focus on adding proper indexes."
284
+
285
+ ──────────────────────────────────────────────────
286
+ 💎 Top Suggestion
287
+ "Add error messages and stack traces to debugging requests for
288
+ 10x faster resolution."
289
+ ──────────────────────────────────────────────────
290
+ ```
291
+
292
+ ## Privacy & Security
293
+
294
+ Hyntx takes your privacy seriously:
295
+
296
+ - **Local-first**: Defaults to Ollama for offline analysis
297
+ - **Automatic redaction**: Removes API keys, credentials, emails, tokens before analysis
298
+ - **Read-only**: Never modifies your Claude Code logs
299
+ - **No telemetry**: Hyntx doesn't send usage data anywhere
300
+
301
+ ### What Gets Redacted?
302
+
303
+ - OpenAI/Anthropic API keys (`sk-*`, `claude-*`)
304
+ - AWS credentials (`AKIA*`, secret keys)
305
+ - Bearer tokens
306
+ - HTTP credentials in URLs
307
+ - Email addresses
308
+ - Private keys (PEM format)
309
+
310
+ ## How It Works
311
+
312
+ 1. **Read logs**: Parses Claude Code conversation logs from `~/.claude/projects/`
313
+ 2. **Extract prompts**: Filters user messages from conversations
314
+ 3. **Sanitize**: Redacts sensitive information automatically
315
+ 4. **Analyze**: Sends sanitized prompts to AI provider for pattern detection
316
+ 5. **Report**: Displays findings with examples and suggestions
317
+
318
+ ## Requirements
319
+
320
+ - **Node.js**: 18.0.0 or higher
321
+ - **Claude Code**: Must have Claude Code installed and used
322
+ - **AI Provider**: Ollama (local) or Anthropic/Google API key
323
+
324
+ ## Troubleshooting
325
+
326
+ ### "No Claude Code logs found"
327
+
328
+ Make sure you've used Claude Code at least once. Logs are stored in:
329
+
330
+ ```text
331
+ ~/.claude/projects/<project-hash>/logs.jsonl
332
+ ```
333
+
334
+ ### "Ollama connection failed"
335
+
336
+ 1. Check Ollama is running: `ollama list`
337
+ 2. Start Ollama: `ollama serve`
338
+ 3. Verify the host: `echo $HYNTX_OLLAMA_HOST` (default: `http://localhost:11434`)
339
+
340
+ ### "No prompts found for date range"
341
+
342
+ - Check the date format: `YYYY-MM-DD`
343
+ - Verify you used Claude Code on those dates
344
+ - Try `--dry-run` to see what logs are being read
345
+
346
+ ## Development
347
+
348
+ ### Setup
349
+
350
+ ```bash
351
+ # Clone the repository
352
+ git clone https://github.com/yourusername/hyntx.git
353
+ cd hyntx
354
+
355
+ # Install dependencies
356
+ pnpm install
357
+
358
+ # Run in development mode
359
+ pnpm dev
360
+
361
+ # Build
362
+ pnpm build
363
+
364
+ # Test the CLI
365
+ pnpm start
366
+ ```
367
+
368
+ ### Project Structure
369
+
370
+ ```text
371
+ hyntx/
372
+ ├── src/
373
+ │ ├── index.ts # CLI entry point
374
+ │ ├── core/ # Core business logic
375
+ │ │ ├── setup.ts # Interactive setup (multi-provider)
376
+ │ │ ├── reminder.ts # Reminder system
377
+ │ │ ├── log-reader.ts # Log parsing
378
+ │ │ ├── schema-validator.ts # Log schema validation
379
+ │ │ ├── sanitizer.ts # Secret redaction
380
+ │ │ ├── analyzer.ts # Analysis orchestration + batching
381
+ │ │ └── reporter.ts # Output formatting (Before/After)
382
+ │ ├── providers/ # AI providers
383
+ │ │ ├── base.ts # Interface & prompts
384
+ │ │ ├── ollama.ts # Ollama integration
385
+ │ │ ├── anthropic.ts # Claude integration
386
+ │ │ ├── google.ts # Gemini integration
387
+ │ │ └── index.ts # Provider factory with fallback
388
+ │ ├── utils/ # Utility functions
389
+ │ │ ├── env.ts # Environment config
390
+ │ │ ├── shell-config.ts # Shell auto-configuration
391
+ │ │ ├── paths.ts # System path constants
392
+ │ │ └── terminal.ts # Terminal utilities
393
+ │ └── types/
394
+ │ └── index.ts # TypeScript type definitions
395
+ ├── docs/
396
+ │ └── SPECS.md # Technical specifications
397
+ └── package.json
398
+ ```
399
+
400
+ ## Contributing
401
+
402
+ Contributions are welcome! Please:
403
+
404
+ 1. Fork the repository
405
+ 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
406
+ 3. Commit your changes using Conventional Commits
407
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
408
+ 5. Open a Pull Request
409
+
410
+ ## Roadmap
411
+
412
+ For detailed development roadmap, planned features, and implementation status, see [ROADMAP.md](ROADMAP.md).
413
+
414
+ ## License
415
+
416
+ MIT License - see [LICENSE](LICENSE) file for details.
417
+
418
+ ## Acknowledgments
419
+
420
+ - Built for [Claude Code](https://claude.com/claude-code) users
421
+ - Inspired by retrospective practices in Agile development
422
+ - Privacy-first approach inspired by local-first software movement
423
+
424
+ ## Support
425
+
426
+ - **Issues**: [GitHub Issues](https://github.com/yourusername/hyntx/issues)
427
+ - **Discussions**: [GitHub Discussions](https://github.com/yourusername/hyntx/discussions)
428
+ - **Email**: your-email@example.com
429
+
430
+ ---
431
+
432
+ **Made with ❤️ for better prompt engineering**
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Before/after rewrite example for a pattern.
3
+ * Shows concrete improvement for a detected issue.
4
+ */
5
+ type BeforeAfter = {
6
+ readonly before: string;
7
+ readonly after: string;
8
+ };
9
+ /**
10
+ * Severity levels for detected patterns.
11
+ */
12
+ type PatternSeverity = 'low' | 'medium' | 'high';
13
+ /**
14
+ * Detected improvement pattern from analysis.
15
+ * Each pattern includes concrete examples and actionable suggestions.
16
+ */
17
+ type AnalysisPattern = {
18
+ readonly id: string;
19
+ readonly name: string;
20
+ readonly frequency: number;
21
+ readonly severity: PatternSeverity;
22
+ readonly examples: readonly string[];
23
+ readonly suggestion: string;
24
+ readonly beforeAfter: BeforeAfter;
25
+ };
26
+ /**
27
+ * Statistics from the analysis.
28
+ */
29
+ type AnalysisStats = {
30
+ readonly totalPrompts: number;
31
+ readonly promptsWithIssues: number;
32
+ readonly overallScore: number;
33
+ };
34
+ /**
35
+ * Complete analysis result from a provider.
36
+ * Contains patterns, statistics, and top suggestion.
37
+ */
38
+ type AnalysisResult = {
39
+ readonly date: string;
40
+ readonly patterns: readonly AnalysisPattern[];
41
+ readonly stats: AnalysisStats;
42
+ readonly topSuggestion: string;
43
+ };
44
+ /**
45
+ * Interface for AI analysis providers.
46
+ * All providers must implement this interface.
47
+ */
48
+ type AnalysisProvider = {
49
+ readonly name: string;
50
+ isAvailable(): Promise<boolean>;
51
+ analyze(prompts: readonly string[], date: string): Promise<AnalysisResult>;
52
+ };
53
+ /**
54
+ * Ollama provider configuration.
55
+ */
56
+ type OllamaConfig = {
57
+ readonly model: string;
58
+ readonly host: string;
59
+ };
60
+
61
+ /**
62
+ * Ollama AI provider implementation.
63
+ *
64
+ * This module provides integration with local Ollama instances for prompt analysis.
65
+ * Features include:
66
+ * - Availability checking with timeout and model verification
67
+ * - Retry logic with exponential backoff for network errors
68
+ * - Support for both raw JSON and markdown-wrapped responses
69
+ */
70
+
71
+ /**
72
+ * Ollama provider for local AI analysis.
73
+ * Implements the AnalysisProvider interface for Ollama instances.
74
+ */
75
+ declare class OllamaProvider implements AnalysisProvider {
76
+ readonly name = "Ollama";
77
+ private readonly config;
78
+ /**
79
+ * Creates a new OllamaProvider instance.
80
+ *
81
+ * @param config - Ollama configuration with model and host
82
+ */
83
+ constructor(config: OllamaConfig);
84
+ /**
85
+ * Checks if the Ollama service is available and has the required model.
86
+ * Uses a 3-second timeout to avoid hanging on unreachable services.
87
+ *
88
+ * @returns Promise that resolves to true if available, false otherwise
89
+ */
90
+ isAvailable(): Promise<boolean>;
91
+ /**
92
+ * Analyzes prompts using the Ollama service.
93
+ * Implements retry logic with exponential backoff for network errors.
94
+ *
95
+ * @param prompts - Array of prompt strings to analyze
96
+ * @param date - Date context for the analysis
97
+ * @returns Promise resolving to AnalysisResult
98
+ * @throws Error if analysis fails after retries or if response is invalid
99
+ */
100
+ analyze(prompts: readonly string[], date: string): Promise<AnalysisResult>;
101
+ }
102
+
103
+ /**
104
+ * Hyntx - CLI Entry Point
105
+ *
106
+ * Main entry point for the Hyntx CLI that analyzes Claude Code prompts
107
+ * and generates improvement suggestions.
108
+ */
109
+
110
+ /**
111
+ * Parsed command-line arguments.
112
+ */
113
+ type ParsedArgs = {
114
+ readonly date: string;
115
+ readonly help: boolean;
116
+ readonly version: boolean;
117
+ };
118
+ /**
119
+ * Parses command-line arguments.
120
+ *
121
+ * @returns Parsed arguments
122
+ * @throws Error if arguments are invalid
123
+ */
124
+ declare function parseArguments(): ParsedArgs;
125
+ /**
126
+ * Displays help message and exits.
127
+ */
128
+ declare function showHelp(): void;
129
+ /**
130
+ * Displays version information and exits.
131
+ */
132
+ declare function showVersion(): void;
133
+ /**
134
+ * Checks if this is the first run and runs setup if needed.
135
+ */
136
+ declare function checkAndRunSetup(): Promise<void>;
137
+ /**
138
+ * Reads logs for the specified date with a spinner.
139
+ *
140
+ * @param date - Date to read logs for
141
+ * @returns Array of prompt strings
142
+ */
143
+ declare function readLogsWithSpinner(date: string): Promise<readonly string[]>;
144
+ /**
145
+ * Connects to the Ollama provider with availability check.
146
+ *
147
+ * @returns OllamaProvider instance
148
+ */
149
+ declare function connectProviderWithSpinner(): Promise<OllamaProvider>;
150
+ /**
151
+ * Analyzes prompts with progress tracking.
152
+ *
153
+ * @param provider - Analysis provider
154
+ * @param prompts - Array of prompt strings
155
+ * @param date - Date context
156
+ * @returns Analysis result
157
+ */
158
+ declare function analyzeWithProgress(provider: OllamaProvider, prompts: readonly string[], date: string): Promise<AnalysisResult>;
159
+ /**
160
+ * Displays analysis results.
161
+ *
162
+ * @param result - Analysis result
163
+ */
164
+ declare function displayResults(result: AnalysisResult): void;
165
+ /**
166
+ * Handles errors and exits with appropriate code.
167
+ *
168
+ * @param error - Error to handle
169
+ */
170
+ declare function handleError(error: Error): void;
171
+ /**
172
+ * Main entry point for the CLI.
173
+ */
174
+ declare function main(): Promise<void>;
175
+
176
+ export { analyzeWithProgress, checkAndRunSetup, connectProviderWithSpinner, displayResults, handleError, main, parseArguments, readLogsWithSpinner, showHelp, showVersion };