helixmind 0.2.14 โ†’ 0.2.16

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,377 +1,382 @@
1
- <div align="center">
2
-
3
- # ๐Ÿง  HelixMind
4
-
5
- **AI Coding Assistant with Persistent Spiral Memory**
6
-
7
- [![npm version](https://img.shields.io/npm/v/helixmind?color=blue&logo=npm)](https://www.npmjs.com/package/helixmind)
8
- [![License](https://img.shields.io/badge/License-AGPL_3.0-blue?logo=gnu)](LICENSE)
9
- [![Node](https://img.shields.io/badge/Node-18%2B-green?logo=node.js)](https://nodejs.org)
10
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue?logo=typescript)](https://www.typescriptlang.org/)
11
-
12
- *Remembers context across sessions. Learns from every interaction. Full SaaS platform with CLI + Web Dashboard.*
13
-
14
- [Installation](#-installation) โ€ข [Features](#-features) โ€ข [Quick Start](#-quick-start) โ€ข [Web Platform](#-web-platform) โ€ข [Documentation](#-documentation)
15
-
16
- </div>
17
-
18
- ---
19
-
20
- ## โœจ Features
21
-
22
- <table>
23
- <tr>
24
- <td width="50%">
25
-
26
- ### ๐Ÿ”„ Spiral Memory
27
- **5-level hierarchical memory** that persists across sessions. Context flows between levels based on relevance and recency.
28
-
29
- </td>
30
- <td width="50%">
31
-
32
- ### ๐Ÿค– Multi-Provider
33
- **Claude, GPT-4, Ollama** and more. Switch seamlessly between AI providers with rate limiting and model limits.
34
-
35
- </td>
36
- </tr>
37
- <tr>
38
- <td width="50%">
39
-
40
- ### โšก Autonomous Agent
41
- AI can **edit files, run commands, commit changes, and browse the web** โ€” with a permission system and sandbox for safety.
42
-
43
- </td>
44
- <td width="50%">
45
-
46
- ### ๐ŸŽฏ Smart Context
47
- **Auto-assembles relevant code** from your project. Session buffer, context trimming, and dependency tracking.
48
-
49
- </td>
50
- </tr>
51
- <tr>
52
- <td width="50%">
53
-
54
- ### ๐ŸŒ Web Dashboard
55
- **Next.js 15 platform** with 3D brain visualization, admin panel, billing (Stripe), support tickets, and CLI remote control.
56
-
57
- </td>
58
- <td width="50%">
59
-
60
- ### ๐Ÿ”ฌ Validation Matrix
61
- **Automatic output validation** with static checks, dynamic checks, spiral checks, autofix, and quality classification.
62
-
63
- </td>
64
- </tr>
65
- <tr>
66
- <td width="50%">
67
-
68
- ### ๐Ÿ“Š SWE-Bench Integration
69
- **Built-in benchmark suite** โ€” run SWE-bench Lite/Verified, compare runs, measure Spiral Memory impact.
70
-
71
- </td>
72
- <td width="50%">
73
-
74
- ### ๐ŸŒ Web Knowledge
75
- **Cloud-enriched context** โ€” topic detection, web search, content extraction, and automatic knowledge integration.
76
-
77
- </td>
78
- </tr>
79
- <tr>
80
- <td width="50%">
81
-
82
- ### ๐Ÿ› Bug Tracking
83
- **Automatic bug detection** and persistent journal โ€” track bugs across sessions with evidence and status.
84
-
85
- </td>
86
- <td width="50%">
87
-
88
- ### ๐Ÿ’พ Checkpoints & Sessions
89
- **Save and revert** to any checkpoint, multi-session tab view, session lifecycle management.
90
-
91
- </td>
92
- </tr>
93
- <tr>
94
- <td width="50%">
95
-
96
- ### ๐ŸŒ Browser Automation
97
- **Puppeteer-based browser control** โ€” navigate, click, type, screenshot, visual analysis with Chrome integration.
98
-
99
- </td>
100
- <td width="50%">
101
-
102
- ### ๐Ÿ” Authentication & Security
103
- **OAuth login, API keys, feature gating** โ€” secure access control with subscription tier enforcement.
104
-
105
- </td>
106
- </tr>
107
- <tr>
108
- <td width="50%">
109
-
110
- ### ๐Ÿ›ก๏ธ Security Monitor
111
- **Continuous security monitoring** โ€” threat detection, automated defenses, real-time dashboard with approval queue.
112
-
113
- </td>
114
- <td width="50%">
115
-
116
- ### ๐Ÿ“ˆ MCP Integration
117
- **Model Context Protocol** โ€” works with Claude Code, Cursor, VS Code, Windsurf, Codex, JetBrains AI.
118
-
119
- </td>
120
- </tr>
121
- </table>
122
-
123
- ---
124
-
125
- ## ๐Ÿš€ Installation
126
-
127
- ```bash
128
- # Run directly (no install needed)
129
- npx helixmind
130
-
131
- # Or install globally
132
- npm install -g helixmind
133
- helixmind
134
- ```
135
-
136
- ---
137
-
138
- ## ๐ŸŽฎ Quick Start
139
-
140
- ```bash
141
- # Start interactive chat (default command)
142
- npx helixmind
143
-
144
- # Initialize in current project
145
- npx helixmind init
146
-
147
- # Send a single message
148
- npx helixmind chat -m "fix all lint errors in src/"
149
-
150
- # YOLO mode โ€” auto-approve everything
151
- npx helixmind chat --yolo
152
-
153
- # Skip permission prompts
154
- npx helixmind chat -s
155
-
156
- # Feed files into spiral memory
157
- npx helixmind feed src/ --deep
158
-
159
- # Watch files and update spiral live
160
- npx helixmind feed src/ --watch
161
- ```
162
-
163
- ---
164
-
165
- ## ๐Ÿ“‹ CLI Commands
166
-
167
- | Command | Description |
168
- |:--------|:------------|
169
- | `helixmind` / `helixmind chat` | ๐ŸŽฏ Start interactive chat (default) |
170
- | `helixmind helix` | ๐ŸŽฏ Alias for interactive chat |
171
- | `helixmind init` | โš™๏ธ Initialize HelixMind in project |
172
- | `helixmind chat -m "..."` | ๐Ÿ’ฌ Send a single message |
173
- | `helixmind chat --yolo` | ๐Ÿš€ Auto-approve all operations |
174
- | `helixmind chat --no-validation` | ๐Ÿ”‡ Disable output validation |
175
- | `helixmind chat --validation-verbose` | ๐Ÿ” Detailed validation output |
176
- | `helixmind chat --validation-strict` | ๐Ÿšซ Treat validation warnings as errors |
177
- | `helixmind feed [paths...]` | ๐Ÿ“‚ Feed files/dirs into spiral |
178
- | `helixmind feed --deep` | ๐Ÿ” Deep analysis with intent detection |
179
- | `helixmind feed --watch` | ๐Ÿ‘๏ธ Watch and auto-update spiral |
180
- | `helixmind spiral status` | ๐Ÿ“Š Show spiral metrics |
181
- | `helixmind spiral search <query>` | ๐Ÿ”Ž Search spiral context |
182
- | `helixmind spiral compact` | ๐Ÿ—œ๏ธ Trigger spiral compaction |
183
- | `helixmind config set <k> <v>` | โš™๏ธ Set config value |
184
- | `helixmind config get <key>` | ๐Ÿ“– Get config value |
185
- | `helixmind config list` | ๐Ÿ“‹ Show all config |
186
- | `helixmind export [dir]` | ๐Ÿ“ฆ Export spiral to .helixmind.zip |
187
- | `helixmind import <zip>` | ๐Ÿ“ฅ Import spiral from archive |
188
- | `helixmind login` | ๐Ÿ”‘ Authenticate with web platform |
189
- | `helixmind logout` | ๐Ÿšช Remove stored auth |
190
- | `helixmind whoami` | ๐Ÿ‘ค Show auth status |
191
- | `helixmind bench run` | ๐Ÿ‹๏ธ Run SWE-bench benchmark |
192
- | `helixmind bench results` | ๐Ÿ“ˆ Show benchmark results |
193
- | `helixmind bench compare` | โš–๏ธ Compare benchmark runs |
194
- | `helixmind bench list` | ๐Ÿ“‹ List past runs |
195
-
196
- ### โŒจ๏ธ Keyboard Shortcuts
197
-
198
- | Key | Action |
199
- |:----|:-------|
200
- | `Ctrl+C` | ๐Ÿ›‘ Exit |
201
- | `Ctrl+L` | ๐Ÿงน Clear screen |
202
- | `Ctrl+D` | ๐Ÿ› Toggle debug mode |
203
- | `Tab` | โœจ Autocomplete command |
204
-
205
- ---
206
-
207
- ## ๐Ÿง  Memory Architecture
208
-
209
- ```
210
- โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
211
- โ”‚ Level 1 โ€” ๐Ÿ” Focus โ”‚
212
- โ”‚ Most relevant, recent context โ”‚
213
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
214
- โ”‚ Level 2 โ€” โšก Active โ”‚
215
- โ”‚ Related files, dependencies โ”‚
216
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
217
- โ”‚ Level 3 โ€” ๐Ÿ“š Reference โ”‚
218
- โ”‚ Decisions, patterns, code structure โ”‚
219
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
220
- โ”‚ Level 4 โ€” ๐Ÿ“ฆ Archive โ”‚
221
- โ”‚ Compressed summaries, old sessions โ”‚
222
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
223
- โ”‚ Level 5 โ€” ๐Ÿ—„๏ธ Deep Archive โ”‚
224
- โ”‚ Long-term knowledge, project history โ”‚
225
- โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
226
- ```
227
-
228
- Context automatically flows between levels based on relevance and recency. Cloud enrichment adds web knowledge via topic detection and content extraction.
229
-
230
- ---
231
-
232
- ## ๐ŸŒ Web Platform
233
-
234
- The web dashboard (`web/`) is a full **Next.js 15** application:
235
-
236
- | Feature | Description |
237
- |:--------|:------------|
238
- | **3D Brain View** | Interactive Three.js visualization of your spiral memory |
239
- | **Dashboard** | Manage API keys, billing, profile, and CLI connections |
240
- | **Admin Panel** | User management, ticket system, plans, settings, stats |
241
- | **CLI Integration** | WebSocket bridge โ€” control your CLI from the browser |
242
- | **Support System** | Built-in ticket system with detail views |
243
- | **Blog & Docs** | MDX-based with i18n (DE/EN), sidebar navigation |
244
- | **Auth** | NextAuth with OAuth, staff login, CLI authorization |
245
- | **Billing** | Stripe checkout, portal, webhooks |
246
- | **PWA** | Service worker, install prompt, offline support |
247
- | **Cookie Consent** | GDPR-compliant cookie banner and settings |
248
-
249
- ### Web Setup
250
-
251
- ```bash
252
- cd web
253
- npm install
254
- cp .env.example .env # Configure database, auth, stripe
255
- npx prisma db push # Set up database
256
- npm run db:seed # Seed initial data
257
- npm run dev # Start dev server (Turbopack)
258
- ```
259
-
260
- ---
261
-
262
- ## โš™๏ธ Configuration
263
-
264
- Create `.helixmind/config.json` in your project:
265
-
266
- ```json
267
- {
268
- "provider": "anthropic",
269
- "model": "claude-sonnet-4-20250514",
270
- "brainEnabled": true,
271
- "permissions": {
272
- "writeFiles": true,
273
- "runCommands": true,
274
- "gitCommit": true
275
- }
276
- }
277
- ```
278
-
279
- ### ๐Ÿ”‘ Environment Variables
280
-
281
- ```bash
282
- ANTHROPIC_API_KEY=sk-ant-... # For Claude
283
- OPENAI_API_KEY=sk-... # For OpenAI/GPT
284
- # Ollama: no key needed (local)
285
- ```
286
-
287
- ---
288
-
289
- ## ๐Ÿ› ๏ธ Tech Stack
290
-
291
- ### CLI
292
-
293
- | Category | Technology |
294
- |:---------|:-----------|
295
- | Language | ![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue) |
296
- | AI SDKs | ![Anthropic](https://img.shields.io/badge/Anthropic-SDK-orange) ![OpenAI](https://img.shields.io/badge/OpenAI-SDK-green) ![Ollama](https://img.shields.io/badge/Ollama-local-purple) |
297
- | Database | ![SQLite](https://img.shields.io/badge/SQLite-better--sqlite3-lightgrey) ![sqlite-vec](https://img.shields.io/badge/sqlite--vec-vectors-blue) |
298
- | Embeddings | ![Transformers](https://img.shields.io/badge/HuggingFace-Transformers-yellow) |
299
- | Browser | ![Puppeteer](https://img.shields.io/badge/Puppeteer-headless-green) |
300
- | Testing | ![Vitest](https://img.shields.io/badge/Vitest-70%2B_tests-yellowgreen) |
301
- | MCP | ![MCP](https://img.shields.io/badge/MCP-SDK-blue) |
302
-
303
- ### Web
304
-
305
- | Category | Technology |
306
- |:---------|:-----------|
307
- | Framework | ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![React](https://img.shields.io/badge/React-19-blue) |
308
- | 3D | ![Three.js](https://img.shields.io/badge/Three.js-R3F-green) |
309
- | Database | ![Prisma](https://img.shields.io/badge/Prisma-6-purple) |
310
- | Auth | ![NextAuth](https://img.shields.io/badge/NextAuth-v5-orange) |
311
- | Payments | ![Stripe](https://img.shields.io/badge/Stripe-17-blue) |
312
- | Styling | ![Tailwind](https://img.shields.io/badge/Tailwind-4-cyan) |
313
- | i18n | ![next-intl](https://img.shields.io/badge/next--intl-DE%2FEN-yellow) |
314
- | PWA | ![Serwist](https://img.shields.io/badge/Serwist-PWA-green) |
315
-
316
- ---
317
-
318
- ## ๐Ÿ—๏ธ Development
319
-
320
- ```bash
321
- # Clone repo
322
- git clone https://github.com/DancingTedDanson011/HelixMind.git
323
- cd HelixMind
324
-
325
- # Install dependencies (CLI)
326
- npm install
327
-
328
- # Build CLI
329
- npm run build
330
-
331
- # Run CLI in dev mode
332
- npm run dev
333
-
334
- # Run tests
335
- npm test
336
-
337
- # Run tests with coverage
338
- npm run test:coverage
339
-
340
- # Web dashboard
341
- cd web
342
- npm install
343
- npm run dev
344
- ```
345
-
346
- ---
347
-
348
- ## ๐Ÿ“š Documentation
349
-
350
- Complete documentation is available in the web dashboard and includes:
351
-
352
- | Category | Topics |
353
- |:---------|:-------|
354
- | **Core Concepts** | Spiral Memory, Validation Matrix, Web Knowledge, Bug Tracking, Browser Automation |
355
- | **Usage Guides** | Getting Started, Configuration, Authentication, Project Setup |
356
- | **Advanced** | Autonomous Modes, Agent Tools, MCP Integration, SWE-Bench |
357
- | **Reference** | CLI Commands, Slash Commands, Permission System, Export/Import |
358
-
359
- **Web Dashboard Docs**: Start the web dashboard (`cd web && npm run dev`) and navigate to `/docs`.
360
-
361
- **CLI Help**: Use `helixmind --help` or `helixmind chat --help` for command reference.
362
-
363
- ---
364
-
365
- ## ๐Ÿ“„ License
366
-
367
- [AGPL-3.0](LICENSE) โ€” Free for open-source use. Commercial licenses available.
368
-
369
- ---
370
-
371
- <div align="center">
372
-
373
- **Made with โค๏ธ by [HelixMind](https://github.com/DancingTedDanson011)**
374
-
375
- [โฌ† Back to Top](#-helixmind)
376
-
377
- </div>
1
+ ๏ปฟ<div align="center">
2
+
3
+ # ๐Ÿง ย  HelixMind
4
+
5
+ **AI Coding Assistant with Persistent Spiral Memory**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/helixmind?color=blue&logo=npm)](https://www.npmjs.com/package/helixmind)
8
+ [![License](https://img.shields.io/badge/License-AGPL_3.0-blue?logo=gnu)](LICENSE)
9
+ [![Node](https://img.shields.io/badge/Node-18%2B-green?logo=node.js)](https://nodejs.org)
10
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue?logo=typescript)](https://www.typescriptlang.org/)
11
+
12
+ *Remembers context across sessions. Learns from every interaction. Full SaaS platform with CLI + Web Dashboard.*
13
+
14
+ [Installation](#-installation) โ€ข [Features](#-features) โ€ข [Quick Start](#-quick-start) โ€ข [Web Platform](#-web-platform) โ€ข [Documentation](#-documentation)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## โœจ Features
21
+
22
+ <table>
23
+ <tr>
24
+ <td width="50%">
25
+
26
+ ### ๐Ÿ”„ Spiral Memory
27
+ **5-level hierarchical memory** that persists across sessions. Context flows between levels based on relevance and recency.
28
+
29
+ </td>
30
+ <td width="50%">
31
+
32
+ ### ๐Ÿค– Multi-Provider
33
+ **Claude, GPT-4, Ollama** and more. Switch seamlessly between AI providers with rate limiting and model limits.
34
+
35
+ </td>
36
+ </tr>
37
+ <tr>
38
+ <td width="50%">
39
+
40
+ ### โšก Autonomous Agent
41
+ AI can **edit files, run commands, commit changes, and browse the web** โ€” with a permission system and sandbox for safety.
42
+
43
+ </td>
44
+ <td width="50%">
45
+
46
+ ### ๐ŸŽฏ Smart Context
47
+ **Auto-assembles relevant code** from your project. Session buffer, context trimming, and dependency tracking.
48
+
49
+ </td>
50
+ </tr>
51
+ <tr>
52
+ <td width="50%">
53
+
54
+ ### ๐ŸŒ Web Dashboard
55
+ **Next.js 15 platform** with 3D brain visualization, admin panel, billing (Stripe), support tickets, and CLI remote control.
56
+
57
+ </td>
58
+ <td width="50%">
59
+
60
+ ### ๐Ÿ”ฌ Validation Matrix
61
+ **Automatic output validation** with static checks, dynamic checks, spiral checks, autofix, and quality classification.
62
+
63
+ </td>
64
+ </tr>
65
+ <tr>
66
+ <td width="50%">
67
+
68
+ ### ๐Ÿ“Š SWE-Bench Integration
69
+ **Built-in benchmark suite** โ€” run SWE-bench Lite/Verified, compare runs, measure Spiral Memory impact.
70
+
71
+ </td>
72
+ <td width="50%">
73
+
74
+ ### ๐ŸŒ Web Knowledge
75
+ **Cloud-enriched context** โ€” topic detection, web search, content extraction, and automatic knowledge integration.
76
+
77
+ </td>
78
+ </tr>
79
+ <tr>
80
+ <td width="50%">
81
+
82
+ ### ๐Ÿ› Bug Tracking
83
+ **Automatic bug detection** and persistent journal โ€” track bugs across sessions with evidence and status.
84
+
85
+ </td>
86
+ <td width="50%">
87
+
88
+ ### ๐Ÿ’พ Checkpoints & Sessions
89
+ **Save and revert** to any checkpoint, multi-session tab view, session lifecycle management.
90
+
91
+ </td>
92
+ </tr>
93
+ <tr>
94
+ <td width="50%">
95
+
96
+ ### ๐ŸŒ Browser Automation
97
+ **Puppeteer-based browser control** โ€” navigate, click, type, screenshot, visual analysis with Chrome integration.
98
+
99
+ </td>
100
+ <td width="50%">
101
+
102
+ ### รฐลธโ€ย Authentication & Security
103
+ **OAuth login, API keys, feature gating** โ€” secure access control with subscription tier enforcement.
104
+
105
+ </td>
106
+ </tr>
107
+ <tr>
108
+ <td width="50%">
109
+
110
+ ### ๐Ÿ›ก๏ธ Security Monitor
111
+ **Continuous security monitoring** โ€” threat detection, automated defenses, real-time dashboard with approval queue.
112
+
113
+ </td>
114
+ <td width="50%">
115
+
116
+ ### ๐Ÿ“ˆ MCP Integration
117
+ **Model Context Protocol** โ€” works with Claude Code, Cursor, VS Code, Windsurf, Codex, JetBrains AI.
118
+
119
+ </td>
120
+ </tr>
121
+ </table>
122
+
123
+ ---
124
+
125
+ ## ๐Ÿง ย  Brain Visualization
126
+
127
+ Watch the 3D brain in action:
128
+
129
+ <div align="center">
130
+ <video src="assets/brain_3d_vision.mp4" controls width="800">
131
+ Your browser does not support the video tag.
132
+ </video>
133
+ <p><em>Interactive 3D brain visualization showing memory layers and connections</em></p>
134
+ <p><small><em>Note: The video may not auto-play in GitHub's web view. You can <a href="assets/brain_3d_vision.mp4" download>download it directly</a> or clone the repository to view it.</em></small></p>
135
+ </div>
136
+
137
+ ---
138
+
139
+ ## ๐Ÿš€ Installation
140
+
141
+ ```bash
142
+ # Run directly (no install needed)
143
+ npx helixmind
144
+
145
+ # Or install globally
146
+ npm install -g helixmind
147
+ helixmind
148
+ ```
149
+
150
+ ---
151
+
152
+ ## ๐ŸŽฎ Quick Start
153
+
154
+ ```bash
155
+ # Start interactive chat (default command)
156
+ npx helixmind
157
+
158
+ # Initialize in current project
159
+ npx helixmind init
160
+
161
+ # Send a single message
162
+ npx helixmind chat -m "fix all lint errors in src/"
163
+
164
+ # YOLO mode โ€” auto-approve everything
165
+ npx helixmind chat --yolo
166
+
167
+ # Skip permission prompts
168
+ npx helixmind chat -s
169
+
170
+ # Feed files into spiral memory
171
+ npx helixmind feed src/ --deep
172
+
173
+ # Watch files and update spiral live
174
+ npx helixmind feed src/ --watch
175
+ ```
176
+
177
+ ---
178
+
179
+ ## ๐Ÿ“‹ CLI Commands
180
+
181
+ | Command | Description |
182
+ |:--------|:------------|
183
+ | `helixmind` / `helixmind chat` | ๐ŸŽฏ Start interactive chat (default) |
184
+ | `helixmind helix` | ๐ŸŽฏ Alias for interactive chat |
185
+ | `helixmind init` | โš™๏ธ Initialize HelixMind in project |
186
+ | `helixmind chat -m "..."` | ๐Ÿ’ฌ Send a single message |
187
+ | `helixmind chat --yolo` | ๐Ÿš€ Auto-approve all operations |
188
+ | `helixmind chat --no-validation` | ๐Ÿ”‡ Disable output validation |
189
+ | `helixmind chat --validation-verbose` | ๐Ÿ” Detailed validation output |
190
+ | `helixmind chat --validation-strict` | ๐Ÿšซ Treat validation warnings as errors |
191
+ | `helixmind feed [paths...]` | ๐Ÿ“‚ Feed files/dirs into spiral |
192
+ | `helixmind feed --deep` | ๐Ÿ” Deep analysis with intent detection |
193
+ | `helixmind feed --watch` | ๐Ÿ‘๏ธ Watch and auto-update spiral |
194
+ | `helixmind spiral status` | ๐Ÿ“Š Show spiral metrics |
195
+ | `helixmind spiral search <query>` | ๐Ÿ”Ž Search spiral context |
196
+ | `helixmind spiral compact` | ๐Ÿ—œ๏ธ Trigger spiral compaction |
197
+ | `helixmind config set <k> <v>` | โš™๏ธ Set config value |
198
+ | `helixmind config get <key>` | ๐Ÿ“– Get config value |
199
+ | `helixmind config list` | ๐Ÿ“‹ Show all config |
200
+ | `helixmind export [dir]` | รฐลธโ€œยฆ Export spiral to .helixmind.zip |
201
+ | `helixmind import <zip>` | ๐Ÿ“ฅ Import spiral from archive |
202
+ | `helixmind login` | ๐Ÿ”‘ Authenticate with web platform |
203
+ | `helixmind logout` | ๐Ÿšช Remove stored auth |
204
+ | `helixmind whoami` | ๐Ÿ‘ค Show auth status |
205
+ | `helixmind bench run` | ๐Ÿ‹๏ธ Run SWE-bench benchmark |
206
+ | `helixmind bench results` | ๐Ÿ“ˆ Show benchmark results |
207
+ | `helixmind bench compare` | โš–๏ธ Compare benchmark runs |
208
+ | `helixmind bench list` | ๐Ÿ“‹ List past runs |
209
+
210
+ ### โŒจ๏ธ Keyboard Shortcuts
211
+
212
+ | Key | Action |
213
+ |:----|:-------|
214
+ | `Ctrl+C` | ๐Ÿ›‘ Exit |
215
+ | `Ctrl+L` | ๐Ÿง ยน Clear screen |
216
+ | `Ctrl+D` | ๐Ÿ› Toggle debug mode |
217
+ | `Tab` | โœจ Autocomplete command |
218
+
219
+ ---
220
+
221
+ ## ๐Ÿง ย  Memory Architecture
222
+
223
+ ```
224
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
225
+ โ”‚ Level 1 โ€” ๐Ÿ” Focus โ”‚
226
+ โ”‚ Most relevant, recent context โ”‚
227
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
228
+ โ”‚ Level 2 โ€” โšก Active โ”‚
229
+ โ”‚ Related files, dependencies โ”‚
230
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
231
+ โ”‚ Level 3 โ€” รฐลธโ€œลก Reference โ”‚
232
+ โ”‚ Decisions, patterns, code structure โ”‚
233
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
234
+ โ”‚ Level 4 โ€” รฐลธโ€œยฆ Archive โ”‚
235
+ โ”‚ Compressed summaries, old sessions โ”‚
236
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
237
+ โ”‚ Level 5 โ€” รฐลธโ€”โ€žรฏยธย Deep Archive โ”‚
238
+ โ”‚ Long-term knowledge, project history โ”‚
239
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
240
+ ```
241
+
242
+ Context automatically flows between levels based on relevance and recency. Cloud enrichment adds web knowledge via topic detection and content extraction.
243
+
244
+ ---
245
+
246
+ ## ๐ŸŒ Web Platform
247
+
248
+ The web dashboard (available at [helix-mind.ai](https://helix-mind.ai)) is a separate **Next.js 15** application:
249
+
250
+ | Feature | Description |
251
+ |:--------|:------------|
252
+ | **3D Brain View** | Interactive Three.js visualization of your spiral memory |
253
+ | **Dashboard** | Manage API keys, billing, profile, and CLI connections |
254
+ | **Admin Panel** | User management, ticket system, plans, settings, stats |
255
+ | **CLI Integration** | WebSocket bridge โ€” control your CLI from the browser |
256
+ | **Support System** | Built-in ticket system with detail views |
257
+ | **Blog & Docs** | MDX-based with i18n (DE/EN), sidebar navigation |
258
+ | **Auth** | NextAuth with OAuth, staff login, CLI authorization |
259
+ | **Billing** | Stripe checkout, portal, webhooks |
260
+ | **PWA** | Service worker, install prompt, offline support |
261
+ | **Cookie Consent** | GDPR-compliant cookie banner and settings |
262
+
263
+
264
+ ---
265
+
266
+ ## โš™๏ธ Configuration
267
+
268
+ Create `.helixmind/config.json` in your project:
269
+
270
+ ```json
271
+ {
272
+ "provider": "anthropic",
273
+ "model": "claude-sonnet-4-20250514",
274
+ "brainEnabled": true,
275
+ "permissions": {
276
+ "writeFiles": true,
277
+ "runCommands": true,
278
+ "gitCommit": true
279
+ }
280
+ }
281
+ ```
282
+
283
+ ### ๐Ÿ”‘ Environment Variables
284
+
285
+ ```bash
286
+ ANTHROPIC_API_KEY=sk-ant-... # For Claude
287
+ OPENAI_API_KEY=sk-... # For OpenAI/GPT
288
+ # Ollama: no key needed (local)
289
+ ```
290
+
291
+ ---
292
+
293
+ ## รฐลธโ€บย รฏยธย Tech Stack
294
+
295
+ ### CLI
296
+
297
+ | Category | Technology |
298
+ |:---------|:-----------|
299
+ | Language | ![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue) |
300
+ | AI SDKs | ![Anthropic](https://img.shields.io/badge/Anthropic-SDK-orange) ![OpenAI](https://img.shields.io/badge/OpenAI-SDK-green) ![Ollama](https://img.shields.io/badge/Ollama-local-purple) |
301
+ | Database | ![SQLite](https://img.shields.io/badge/SQLite-better--sqlite3-lightgrey) ![sqlite-vec](https://img.shields.io/badge/sqlite--vec-vectors-blue) |
302
+ | Embeddings | ![Transformers](https://img.shields.io/badge/HuggingFace-Transformers-yellow) |
303
+ | Browser | ![Puppeteer](https://img.shields.io/badge/Puppeteer-headless-green) |
304
+ | Testing | ![Vitest](https://img.shields.io/badge/Vitest-70%2B_tests-yellowgreen) |
305
+ | MCP | ![MCP](https://img.shields.io/badge/MCP-SDK-blue) |
306
+
307
+ ### Web
308
+
309
+ | Category | Technology |
310
+ |:---------|:-----------|
311
+ | Framework | ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![React](https://img.shields.io/badge/React-19-blue) |
312
+ | 3D | ![Three.js](https://img.shields.io/badge/Three.js-R3F-green) |
313
+ | Database | ![Prisma](https://img.shields.io/badge/Prisma-6-purple) |
314
+ | Auth | ![NextAuth](https://img.shields.io/badge/NextAuth-v5-orange) |
315
+ | Payments | ![Stripe](https://img.shields.io/badge/Stripe-17-blue) |
316
+ | Styling | ![Tailwind](https://img.shields.io/badge/Tailwind-4-cyan) |
317
+ | i18n | ![next-intl](https://img.shields.io/badge/next--intl-DE%2FEN-yellow) |
318
+ | PWA | ![Serwist](https://img.shields.io/badge/Serwist-PWA-green) |
319
+
320
+ ---
321
+
322
+ ## รฐลธยโ€”รฏยธย Development
323
+
324
+ ```bash
325
+ # Clone repo
326
+ git clone https://github.com/DancingTedDanson011/HelixMind.git
327
+ cd HelixMind
328
+
329
+ # Install dependencies (CLI)
330
+ npm install
331
+
332
+ # Build CLI
333
+ npm run build
334
+
335
+ # Run CLI in dev mode
336
+ npm run dev
337
+
338
+ # Run tests
339
+ npm test
340
+
341
+ # Run tests with coverage
342
+ npm run test:coverage
343
+
344
+ # Web dashboard
345
+ cd web
346
+ npm install
347
+ npm run dev
348
+ ```
349
+
350
+ ---
351
+
352
+ ## รฐลธโ€œลก Documentation
353
+
354
+ Complete documentation is available in the web dashboard and includes:
355
+
356
+ | Category | Topics |
357
+ |:---------|:-------|
358
+ | **Core Concepts** | Spiral Memory, Validation Matrix, Web Knowledge, Bug Tracking, Browser Automation |
359
+ | **Usage Guides** | Getting Started, Configuration, Authentication, Project Setup |
360
+ | **Advanced** | Autonomous Modes, Agent Tools, MCP Integration, SWE-Bench |
361
+ | **Reference** | CLI Commands, Slash Commands, Permission System, Export/Import |
362
+
363
+ **Web Dashboard Docs**: Start the web dashboard (`cd web && npm run dev`) and navigate to `/docs`.
364
+
365
+ **CLI Help**: Use `helixmind --help` or `helixmind chat --help` for command reference.
366
+
367
+ ---
368
+
369
+ ## รฐลธโ€œโ€ž License
370
+
371
+ [AGPL-3.0](LICENSE) โ€” Free for open-source use. Commercial licenses available.
372
+
373
+ ---
374
+
375
+ <div align="center">
376
+
377
+ **Made with โค๏ธ by [HelixMind](https://github.com/DancingTedDanson011)**
378
+
379
+ [โฌ† Back to Top](#-helixmind)
380
+
381
+ </div>
382
+