lynkr 8.0.0 → 9.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.
Files changed (128) hide show
  1. package/.lynkr/telemetry.db +0 -0
  2. package/.lynkr/telemetry.db-shm +0 -0
  3. package/.lynkr/telemetry.db-wal +0 -0
  4. package/README.md +196 -322
  5. package/lynkr-skill.tar.gz +0 -0
  6. package/package.json +4 -3
  7. package/src/api/openai-router.js +64 -13
  8. package/src/api/providers-handler.js +171 -3
  9. package/src/api/router.js +9 -2
  10. package/src/clients/circuit-breaker.js +10 -247
  11. package/src/clients/codex-process.js +342 -0
  12. package/src/clients/codex-utils.js +143 -0
  13. package/src/clients/databricks.js +210 -63
  14. package/src/clients/resilience.js +540 -0
  15. package/src/clients/retry.js +22 -167
  16. package/src/clients/standard-tools.js +23 -0
  17. package/src/config/index.js +77 -0
  18. package/src/context/compression.js +42 -9
  19. package/src/context/distill.js +492 -0
  20. package/src/orchestrator/index.js +48 -8
  21. package/src/routing/complexity-analyzer.js +258 -5
  22. package/src/routing/index.js +12 -2
  23. package/src/routing/latency-tracker.js +148 -0
  24. package/src/routing/model-tiers.js +2 -0
  25. package/src/routing/quality-scorer.js +113 -0
  26. package/src/routing/telemetry.js +464 -0
  27. package/src/server.js +13 -12
  28. package/src/tools/code-graph.js +538 -0
  29. package/src/tools/code-mode.js +304 -0
  30. package/src/tools/index.js +4 -0
  31. package/src/tools/lazy-loader.js +18 -0
  32. package/src/tools/mcp-remote.js +7 -0
  33. package/src/tools/smart-selection.js +11 -0
  34. package/src/tools/tinyfish.js +358 -0
  35. package/src/tools/truncate.js +1 -0
  36. package/src/utils/payload.js +206 -0
  37. package/src/utils/perf-timer.js +80 -0
  38. package/.github/FUNDING.yml +0 -15
  39. package/.github/workflows/README.md +0 -215
  40. package/.github/workflows/ci.yml +0 -69
  41. package/.github/workflows/index.yml +0 -62
  42. package/.github/workflows/web-tools-tests.yml +0 -56
  43. package/CITATIONS.bib +0 -6
  44. package/DEPLOYMENT.md +0 -1001
  45. package/LYNKR-TUI-PLAN.md +0 -984
  46. package/PERFORMANCE-REPORT.md +0 -866
  47. package/PLAN-per-client-model-routing.md +0 -252
  48. package/docs/42642f749da6234f41b6b425c3bb07c9.txt +0 -1
  49. package/docs/BingSiteAuth.xml +0 -4
  50. package/docs/docs-style.css +0 -478
  51. package/docs/docs.html +0 -198
  52. package/docs/google5be250e608e6da39.html +0 -1
  53. package/docs/index.html +0 -577
  54. package/docs/index.md +0 -584
  55. package/docs/robots.txt +0 -4
  56. package/docs/sitemap.xml +0 -44
  57. package/docs/style.css +0 -1223
  58. package/docs/toon-integration-spec.md +0 -130
  59. package/documentation/README.md +0 -101
  60. package/documentation/api.md +0 -806
  61. package/documentation/claude-code-cli.md +0 -679
  62. package/documentation/codex-cli.md +0 -397
  63. package/documentation/contributing.md +0 -571
  64. package/documentation/cursor-integration.md +0 -734
  65. package/documentation/docker.md +0 -874
  66. package/documentation/embeddings.md +0 -762
  67. package/documentation/faq.md +0 -713
  68. package/documentation/features.md +0 -403
  69. package/documentation/headroom.md +0 -519
  70. package/documentation/installation.md +0 -758
  71. package/documentation/memory-system.md +0 -476
  72. package/documentation/production.md +0 -636
  73. package/documentation/providers.md +0 -1009
  74. package/documentation/routing.md +0 -476
  75. package/documentation/testing.md +0 -629
  76. package/documentation/token-optimization.md +0 -325
  77. package/documentation/tools.md +0 -697
  78. package/documentation/troubleshooting.md +0 -969
  79. package/final-test.js +0 -33
  80. package/headroom-sidecar/config.py +0 -93
  81. package/headroom-sidecar/requirements.txt +0 -14
  82. package/headroom-sidecar/server.py +0 -451
  83. package/monitor-agents.sh +0 -31
  84. package/scripts/audit-log-reader.js +0 -399
  85. package/scripts/compact-dictionary.js +0 -204
  86. package/scripts/test-deduplication.js +0 -448
  87. package/src/db/database.sqlite +0 -0
  88. package/te +0 -11622
  89. package/test/README.md +0 -212
  90. package/test/azure-openai-config.test.js +0 -213
  91. package/test/azure-openai-error-resilience.test.js +0 -238
  92. package/test/azure-openai-format-conversion.test.js +0 -354
  93. package/test/azure-openai-integration.test.js +0 -287
  94. package/test/azure-openai-routing.test.js +0 -175
  95. package/test/azure-openai-streaming.test.js +0 -171
  96. package/test/bedrock-integration.test.js +0 -457
  97. package/test/comprehensive-test-suite.js +0 -928
  98. package/test/config-validation.test.js +0 -207
  99. package/test/cursor-integration.test.js +0 -484
  100. package/test/format-conversion.test.js +0 -578
  101. package/test/hybrid-routing-integration.test.js +0 -269
  102. package/test/hybrid-routing-performance.test.js +0 -428
  103. package/test/llamacpp-integration.test.js +0 -882
  104. package/test/lmstudio-integration.test.js +0 -347
  105. package/test/memory/extractor.test.js +0 -398
  106. package/test/memory/retriever.test.js +0 -613
  107. package/test/memory/retriever.test.js.bak +0 -585
  108. package/test/memory/search.test.js +0 -537
  109. package/test/memory/search.test.js.bak +0 -389
  110. package/test/memory/store.test.js +0 -344
  111. package/test/memory/store.test.js.bak +0 -312
  112. package/test/memory/surprise.test.js +0 -300
  113. package/test/memory-performance.test.js +0 -472
  114. package/test/openai-integration.test.js +0 -683
  115. package/test/openrouter-error-resilience.test.js +0 -418
  116. package/test/passthrough-mode.test.js +0 -385
  117. package/test/performance-benchmark.js +0 -351
  118. package/test/performance-tests.js +0 -528
  119. package/test/routing.test.js +0 -225
  120. package/test/toon-compression.test.js +0 -131
  121. package/test/web-tools.test.js +0 -329
  122. package/test-agents-simple.js +0 -43
  123. package/test-cli-connection.sh +0 -33
  124. package/test-learning-unit.js +0 -126
  125. package/test-learning.js +0 -112
  126. package/test-parallel-agents.sh +0 -124
  127. package/test-parallel-direct.js +0 -155
  128. package/test-subagents.sh +0 -117
@@ -1,734 +0,0 @@
1
- # Cursor IDE Integration Guide
2
-
3
- Complete guide to using Cursor IDE with Lynkr for cost savings, provider flexibility, and local model support.
4
-
5
- ---
6
-
7
- ## Overview
8
-
9
- Lynkr provides **full Cursor IDE support** through OpenAI-compatible API endpoints, enabling you to use Cursor with any provider (Databricks, Bedrock, OpenRouter, Ollama, etc.) while maintaining all Cursor features.
10
-
11
- ### Why Use Lynkr with Cursor?
12
-
13
- - 💰 **60-80% cost savings** vs Cursor's default GPT-4 pricing
14
- - 🔓 **Provider choice** - Use Claude, local models, or any supported provider
15
- - 🏠 **Self-hosted** - Full control over your AI infrastructure
16
- - ✅ **Full compatibility** - All Cursor features work (chat, autocomplete, @Codebase search)
17
- - 🔒 **Privacy** - Option to run 100% locally with Ollama
18
-
19
- ---
20
-
21
- ## Quick Setup (5 Minutes)
22
-
23
- ### Step 1: Start Lynkr Server
24
-
25
- ```bash
26
- # Navigate to Lynkr directory
27
- cd /path/to/Lynkr
28
-
29
- # Start with any provider (Databricks, Bedrock, OpenRouter, Ollama, etc.)
30
- npm start
31
-
32
- # Wait for: "Server listening at http://0.0.0.0:8081" (or your configured PORT)
33
- ```
34
-
35
- **Note**: Lynkr runs on port **8081** by default (configured in `.env` as `PORT=8081`)
36
-
37
- ---
38
-
39
- ### Step 2: Configure Cursor
40
-
41
- #### Detailed Configuration Steps
42
-
43
- 1. **Open Cursor Settings**
44
- - **Mac**: Click **Cursor** menu → **Settings** (or press `Cmd+,`)
45
- - **Windows/Linux**: Click **File** → **Settings** (or press `Ctrl+,`)
46
-
47
- 2. **Navigate to Models Section**
48
- - In the Settings sidebar, find **Features** section
49
- - Click on **Models**
50
-
51
- 3. **Configure OpenAI API Settings**
52
-
53
- Fill in these three fields:
54
-
55
- **API Key:**
56
- ```
57
- sk-lynkr
58
- ```
59
- *(Cursor requires a non-empty value, but Lynkr ignores it. You can use any text like "dummy" or "lynkr")*
60
-
61
- **Base URL:**
62
- ```
63
- http://localhost:8081/v1
64
- ```
65
-
66
- ⚠️ **Critical:**
67
- - Use port **8081** (or your configured PORT in .env)
68
- - **Must end with `/v1`**
69
- - Include `http://` prefix
70
- - ✅ Correct: `http://localhost:8081/v1`
71
- - ❌ Wrong: `http://localhost:8081` (missing `/v1`)
72
- - ❌ Wrong: `localhost:8081/v1` (missing `http://`)
73
-
74
- **Model:**
75
-
76
- Choose based on your `MODEL_PROVIDER` in `.env`:
77
- - **Bedrock**: `claude-3.5-sonnet` or `claude-sonnet-4.5`
78
- - **Databricks**: `claude-sonnet-4.5`
79
- - **OpenRouter**: `anthropic/claude-3.5-sonnet`
80
- - **Ollama**: `qwen2.5-coder:latest` (or your OLLAMA_MODEL)
81
- - **Azure OpenAI**: `gpt-4o` or your deployment name
82
- - **OpenAI**: `gpt-4o` or your model
83
-
84
- 4. **Save Settings** (auto-saves in Cursor)
85
-
86
- #### Visual Setup Summary
87
-
88
- ```
89
- ┌─────────────────────────────────────────────────────────┐
90
- │ Cursor Settings → Models → OpenAI API │
91
- ├─────────────────────────────────────────────────────────┤
92
- │ │
93
- │ API Key: sk-lynkr │
94
- │ (or any non-empty value) │
95
- │ │
96
- │ Base URL: http://localhost:8081/v1 │
97
- │ ⚠️ Must include /v1 │
98
- │ │
99
- │ Model: claude-3.5-sonnet │
100
- │ (or your provider's model) │
101
- │ │
102
- └─────────────────────────────────────────────────────────┘
103
- ```
104
-
105
- ---
106
-
107
- ### Step 3: Test the Integration
108
-
109
- **Test 1: Basic Chat** (`Cmd+L` / `Ctrl+L`)
110
- ```
111
- You: "Hello, can you see this?"
112
- Expected: Response from your provider via Lynkr ✅
113
- ```
114
-
115
- **Test 2: Inline Edits** (`Cmd+K` / `Ctrl+K`)
116
- ```
117
- Select code → Press Cmd+K → "Add error handling"
118
- Expected: Code modifications from your provider ✅
119
- ```
120
-
121
- **Test 3: Verify Health**
122
- ```bash
123
- curl http://localhost:8081/v1/health
124
-
125
- # Expected response:
126
- {
127
- "status": "ok",
128
- "provider": "bedrock",
129
- "openai_compatible": true,
130
- "cursor_compatible": true,
131
- "timestamp": "2026-01-11T12:00:00.000Z"
132
- }
133
- ```
134
-
135
- ---
136
-
137
- ## Feature Compatibility
138
-
139
- ### What Works Without Additional Setup
140
-
141
- | Feature | Without Embeddings | With Embeddings |
142
- |---------|-------------------|-----------------|
143
- | **Cmd+L chat** | ✅ Works | ✅ Works |
144
- | **Inline autocomplete** | ✅ Works | ✅ Works |
145
- | **Cmd+K edits** | ✅ Works | ✅ Works |
146
- | **Manual @file references** | ✅ Works | ✅ Works |
147
- | **Terminal commands** | ✅ Works | ✅ Works |
148
- | **@Codebase semantic search** | ❌ Requires embeddings | ✅ Works |
149
- | **Automatic context** | ❌ Requires embeddings | ✅ Works |
150
- | **Find similar code** | ❌ Requires embeddings | ✅ Works |
151
-
152
- ### Important Notes
153
-
154
- **Autocomplete Behavior:**
155
- - Cursor's inline autocomplete uses Cursor's built-in models (fast, local)
156
- - Autocomplete does NOT go through Lynkr
157
- - Only these features use Lynkr:
158
- - ✅ Chat (`Cmd+L` / `Ctrl+L`)
159
- - ✅ Cmd+K inline edits
160
- - ✅ @Codebase search (with embeddings)
161
- - ❌ Autocomplete (uses Cursor's models)
162
-
163
- ---
164
-
165
- ## Enabling @Codebase Semantic Search
166
-
167
- For Cursor's @Codebase semantic search, you need embeddings support.
168
-
169
- ### ⚡ Already Using OpenRouter?
170
-
171
- If you configured `MODEL_PROVIDER=openrouter`, embeddings **work automatically** with the same `OPENROUTER_API_KEY` - no additional setup needed! OpenRouter handles both chat AND embeddings with one key.
172
-
173
- ### 🔧 Using a Different Provider?
174
-
175
- If you're using Databricks, Bedrock, Ollama, or other providers for chat, add ONE of these for embeddings (ordered by privacy):
176
-
177
- #### Option A: Ollama (100% Local - Most Private) 🔒
178
-
179
- **Best for:** Privacy, offline work, zero cloud dependencies
180
-
181
- ```bash
182
- # Pull embedding model
183
- ollama pull nomic-embed-text
184
-
185
- # Add to .env
186
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
187
- OLLAMA_EMBEDDINGS_ENDPOINT=http://localhost:11434/api/embeddings
188
- ```
189
-
190
- **Popular models:**
191
- - `nomic-embed-text` (768 dim, 137M params) - **Recommended**, best all-around
192
- - `mxbai-embed-large` (1024 dim, 335M params) - Higher quality
193
- - `all-minilm` (384 dim, 23M params) - Fastest/smallest
194
-
195
- **Cost:** **100% FREE** 🔒
196
- **Privacy:** All data stays on your machine
197
-
198
- ---
199
-
200
- #### Option B: llama.cpp (100% Local - Maximum Performance) 🔒
201
-
202
- **Best for:** Performance, GGUF models, GPU acceleration
203
-
204
- ```bash
205
- # Download embedding model (example: nomic-embed-text GGUF)
206
- wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf
207
-
208
- # Start llama-server with embedding model
209
- ./llama-server -m nomic-embed-text-v1.5.Q4_K_M.gguf --port 8080 --embedding
210
-
211
- # Add to .env
212
- LLAMACPP_EMBEDDINGS_ENDPOINT=http://localhost:8080/embeddings
213
- ```
214
-
215
- **Popular models:**
216
- - `nomic-embed-text-v1.5.Q4_K_M.gguf` - **Recommended**, 768 dim
217
- - `all-MiniLM-L6-v2.Q4_K_M.gguf` - Smallest, fastest, 384 dim
218
- - `bge-large-en-v1.5.Q4_K_M.gguf` - Highest quality, 1024 dim
219
-
220
- **Cost:** **100% FREE** 🔒
221
- **Privacy:** All data stays on your machine
222
- **Performance:** Faster than Ollama, optimized C++
223
-
224
- ---
225
-
226
- #### Option C: OpenRouter (Cloud - Simplest)
227
-
228
- **Best for:** Simplicity, quality, one key for everything
229
-
230
- ```bash
231
- # Add to .env (uses same key as chat if you're already using OpenRouter)
232
- OPENROUTER_API_KEY=sk-or-v1-your-key
233
- OPENROUTER_EMBEDDINGS_MODEL=openai/text-embedding-3-small
234
- ```
235
-
236
- **Popular models:**
237
- - `openai/text-embedding-3-small` - $0.02 per 1M tokens (80% cheaper!) **Recommended**
238
- - `openai/text-embedding-ada-002` - $0.10 per 1M tokens (standard)
239
- - `openai/text-embedding-3-large` - $0.13 per 1M tokens (best quality, 3072 dim)
240
- - `voyage/voyage-code-2` - $0.12 per 1M tokens (specialized for code)
241
-
242
- **Cost:** ~$0.01-0.10/month for typical usage
243
- **Privacy:** Cloud-based
244
-
245
- ---
246
-
247
- #### Option D: OpenAI (Cloud - Direct)
248
-
249
- **Best for:** Best quality, direct OpenAI access
250
-
251
- ```bash
252
- # Add to .env
253
- OPENAI_API_KEY=sk-your-openai-api-key
254
- # Optionally specify model (defaults to text-embedding-ada-002)
255
- # OPENAI_EMBEDDINGS_MODEL=text-embedding-3-small
256
- ```
257
-
258
- **Popular models:**
259
- - `text-embedding-3-small` - $0.02 per 1M tokens **Recommended**
260
- - `text-embedding-ada-002` - $0.10 per 1M tokens
261
- - `text-embedding-3-large` - $0.13 per 1M tokens (best quality)
262
-
263
- **Cost:** ~$0.01-0.10/month for typical usage
264
- **Privacy:** Cloud-based
265
-
266
- ---
267
-
268
- ### Embeddings Provider Override
269
-
270
- By default, Lynkr uses the same provider as `MODEL_PROVIDER` for embeddings. To use a different provider:
271
-
272
- ```env
273
- # Use Databricks for chat, but Ollama for embeddings (privacy + cost savings)
274
- MODEL_PROVIDER=databricks
275
- DATABRICKS_API_BASE=https://your-workspace.databricks.com
276
- DATABRICKS_API_KEY=your-key
277
-
278
- # Override embeddings provider
279
- EMBEDDINGS_PROVIDER=ollama
280
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
281
- ```
282
-
283
- **Recommended setups:**
284
- - **100% Local/Private**: Ollama chat + Ollama embeddings (zero cloud dependencies)
285
- - **Hybrid**: Databricks/Bedrock chat + Ollama embeddings (private search, cloud chat)
286
- - **Simple Cloud**: OpenRouter chat + OpenRouter embeddings (one key for both)
287
-
288
- **After configuration, restart Lynkr** and @Codebase will work!
289
-
290
- ---
291
-
292
- ## Available Endpoints
293
-
294
- Lynkr implements all 4 OpenAI API endpoints for full Cursor compatibility:
295
-
296
- ### 1. POST /v1/chat/completions
297
-
298
- Chat with streaming support
299
- - Handles all chat/completion requests
300
- - Converts OpenAI format ↔ Anthropic format automatically
301
- - Full tool calling support
302
- - Streaming responses
303
-
304
- ### 2. GET /v1/models
305
-
306
- List available models
307
- - Returns models based on configured provider
308
- - Updates dynamically when you change providers
309
-
310
- ### 3. POST /v1/embeddings
311
-
312
- Generate embeddings for @Codebase search
313
- - Supports 4 providers: Ollama, llama.cpp, OpenRouter, OpenAI
314
- - Automatic provider detection
315
- - Falls back gracefully if not configured (returns 501)
316
-
317
- ### 4. GET /v1/health
318
-
319
- Health check
320
- - Verify Lynkr is running
321
- - Check provider status
322
- - Returns status, provider info, and compatibility flags
323
-
324
- ---
325
-
326
- ## Cost Comparison
327
-
328
- **Scenario:** 100K requests/month, typical Cursor usage
329
-
330
- | Setup | Monthly Cost | Embeddings Setup | Features | Privacy |
331
- |-------|--------------|------------------|----------|---------|
332
- | **Cursor native (GPT-4)** | $20-50 | Built-in | All features | Cloud |
333
- | **Lynkr + OpenRouter** | $5-10 | ⚡ **Same key for both** | All features, simplest setup | Cloud |
334
- | **Lynkr + Databricks** | $15-30 | +Ollama/OpenRouter | All features | Cloud chat, local/cloud search |
335
- | **Lynkr + Ollama + Ollama embeddings** | **100% FREE** 🔒 | Ollama (local) | All features, 100% local | 100% Local |
336
- | **Lynkr + Ollama + llama.cpp embeddings** | **100% FREE** 🔒 | llama.cpp (local) | All features, 100% local | 100% Local |
337
- | **Lynkr + Ollama + OpenRouter embeddings** | $0.01-0.10 | OpenRouter (cloud) | All features, hybrid | Local chat, cloud search |
338
- | **Lynkr + Ollama (no embeddings)** | **FREE** | None | Chat/Cmd+K only, no @Codebase | 100% Local |
339
-
340
- ---
341
-
342
- ## Provider Recommendations
343
-
344
- ### Best for Privacy (100% Local) 🔒
345
-
346
- **Ollama + Ollama embeddings**
347
- - **Cost:** 100% FREE
348
- - **Privacy:** All data stays on your machine
349
- - **Features:** Full @Codebase support with local embeddings
350
- - **Perfect for:** Sensitive codebases, offline work, privacy requirements
351
-
352
- ```env
353
- MODEL_PROVIDER=ollama
354
- OLLAMA_MODEL=llama3.1:8b
355
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
356
- ```
357
-
358
- ---
359
-
360
- ### Best for Simplicity (Recommended for Most Users)
361
-
362
- **OpenRouter**
363
- - **Cost:** $5-10/month
364
- - **Setup:** ONE key for chat + embeddings, no extra setup
365
- - **Features:** 100+ models, automatic fallbacks
366
- - **Perfect for:** Easy setup, flexibility, cost optimization
367
-
368
- ```env
369
- MODEL_PROVIDER=openrouter
370
- OPENROUTER_API_KEY=sk-or-v1-your-key
371
- OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
372
- # Embeddings work automatically with same key!
373
- ```
374
-
375
- ---
376
-
377
- ### Best for Enterprise
378
-
379
- **Databricks or Azure Anthropic**
380
- - **Cost:** $15-30/month (enterprise pricing)
381
- - **Features:** Claude Sonnet 4.5, enterprise SLA
382
- - **Perfect for:** Production use, enterprise compliance
383
-
384
- ```env
385
- MODEL_PROVIDER=databricks
386
- DATABRICKS_API_BASE=https://your-workspace.databricks.com
387
- DATABRICKS_API_KEY=your-key
388
- # Add Ollama embeddings for privacy
389
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
390
- ```
391
-
392
- ---
393
-
394
- ### Best for AWS Ecosystem
395
-
396
- **AWS Bedrock**
397
- - **Cost:** $10-20/month (100+ models)
398
- - **Features:** Claude + DeepSeek + Qwen + Nova + Titan + Llama
399
- - **Perfect for:** AWS integration, multi-model flexibility
400
-
401
- ```env
402
- MODEL_PROVIDER=bedrock
403
- AWS_BEDROCK_API_KEY=your-bearer-token
404
- AWS_BEDROCK_REGION=us-east-1
405
- AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
406
- ```
407
-
408
- ---
409
-
410
- ### Best for Speed
411
-
412
- **Ollama or llama.cpp**
413
- - **Latency:** 100-500ms (local inference)
414
- - **Cost:** 100% FREE
415
- - **Perfect for:** Fast iteration, local development
416
-
417
- ---
418
-
419
- ## Troubleshooting
420
-
421
- ### Connection Refused or Network Error
422
-
423
- **Symptoms:** Cursor shows connection errors, can't reach Lynkr
424
-
425
- **Solutions:**
426
-
427
- 1. **Verify Lynkr is running:**
428
- ```bash
429
- # Check if Lynkr process is running on port 8081
430
- lsof -i :8081
431
- # Should show node process
432
- ```
433
-
434
- 2. **Test health endpoint:**
435
- ```bash
436
- curl http://localhost:8081/v1/health
437
- # Should return: {"status":"ok"}
438
- ```
439
-
440
- 3. **Check port number:**
441
- - Verify Cursor Base URL uses correct port: `http://localhost:8081/v1`
442
- - Check `.env` file: `PORT=8081`
443
- - If you changed PORT, update Cursor settings to match
444
-
445
- 4. **Verify URL format:**
446
- - ✅ Correct: `http://localhost:8081/v1`
447
- - ❌ Wrong: `http://localhost:8081` (missing `/v1`)
448
- - ❌ Wrong: `localhost:8081/v1` (missing `http://`)
449
-
450
- ---
451
-
452
- ### Invalid API Key or Unauthorized
453
-
454
- **Symptoms:** Cursor says API key is invalid
455
-
456
- **Solutions:**
457
- - Lynkr doesn't validate API keys from Cursor
458
- - This error means Cursor isn't reaching Lynkr at all
459
- - Double-check Base URL in Cursor: `http://localhost:8081/v1`
460
- - Make sure you included `/v1` at the end
461
- - Try clearing and re-entering the Base URL
462
-
463
- ---
464
-
465
- ### Model Not Found or Invalid Model
466
-
467
- **Symptoms:** Cursor can't find the model you specified
468
-
469
- **Solutions:**
470
-
471
- 1. **Match model name to your provider:**
472
- - **Bedrock**: Use `claude-3.5-sonnet` or `claude-sonnet-4.5`
473
- - **Databricks**: Use `claude-sonnet-4.5`
474
- - **OpenRouter**: Use `anthropic/claude-3.5-sonnet`
475
- - **Ollama**: Use your actual model name like `qwen2.5-coder:latest`
476
-
477
- 2. **Try generic names:**
478
- - Lynkr translates generic names, so try:
479
- - `claude-3.5-sonnet`
480
- - `gpt-4o`
481
- - These work across most providers
482
-
483
- 3. **Check provider logs:**
484
- ```bash
485
- # In Lynkr terminal
486
- # Look for "Unknown model" errors
487
- ```
488
-
489
- ---
490
-
491
- ### @Codebase Doesn't Work
492
-
493
- **Symptoms:** @Codebase doesn't return results or shows error
494
-
495
- **Solutions:**
496
-
497
- 1. **Verify embeddings are configured:**
498
- ```bash
499
- curl http://localhost:8081/v1/embeddings \
500
- -H "Content-Type: application/json" \
501
- -d '{"input":"test","model":"text-embedding-ada-002"}'
502
-
503
- # Should return embeddings, not 501 error
504
- ```
505
-
506
- 2. **Check embeddings provider:**
507
- ```bash
508
- # In .env, verify one of these is set:
509
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
510
- # OR
511
- LLAMACPP_EMBEDDINGS_ENDPOINT=http://localhost:8080/embeddings
512
- # OR
513
- OPENROUTER_API_KEY=sk-or-v1-your-key
514
- # OR
515
- OPENAI_API_KEY=sk-your-key
516
- ```
517
-
518
- 3. **Restart Lynkr** after adding embeddings config
519
-
520
- 4. **This is a Cursor indexing issue, not Lynkr:**
521
- - Cursor needs to re-index your codebase
522
- - Try closing and reopening the workspace
523
-
524
- ---
525
-
526
- ### Slow Responses
527
-
528
- **Symptoms:** Responses take 5+ seconds
529
-
530
- **Solutions:**
531
-
532
- 1. **Check provider latency:**
533
- - **Local** (Ollama/llama.cpp): Should be 100-500ms
534
- - **Cloud** (OpenRouter/Databricks): Should be 500ms-2s
535
- - **Distant regions**: Can be 2-5s
536
-
537
- 2. **Enable tier-based routing** for speed:
538
- ```env
539
- # Use Ollama for simple requests (fast), cloud for complex requests
540
- # Set all 4 TIER_* env vars to enable tier-based routing
541
- TIER_SIMPLE=ollama:llama3.2
542
- TIER_MEDIUM=openrouter:openai/gpt-4o-mini
543
- TIER_COMPLEX=azure-openai:gpt-4o
544
- TIER_REASONING=azure-openai:gpt-4o
545
- FALLBACK_ENABLED=true
546
- ```
547
-
548
- 3. **Check Lynkr logs:**
549
- - Look for actual response times
550
- - Example: `Response time: 2500ms`
551
-
552
- ---
553
-
554
- ### Embeddings Work But Search Results Are Poor
555
-
556
- **Symptoms:** @Codebase returns irrelevant files
557
-
558
- **Solutions:**
559
-
560
- 1. **Try better embedding models:**
561
- ```bash
562
- # For Ollama - upgrade to larger model
563
- ollama pull mxbai-embed-large # Better quality than nomic-embed-text
564
- OLLAMA_EMBEDDINGS_MODEL=mxbai-embed-large
565
- ```
566
-
567
- 2. **Use cloud embeddings for better quality:**
568
- ```bash
569
- # OpenRouter has excellent embeddings
570
- OPENROUTER_API_KEY=sk-or-v1-your-key
571
- OPENROUTER_EMBEDDINGS_MODEL=voyage/voyage-code-2
572
- ```
573
-
574
- 3. **This is a Cursor indexing issue, not Lynkr:**
575
- - Cursor needs to re-index your codebase
576
- - Try closing and reopening the workspace
577
-
578
- ---
579
-
580
- ### Too Many Requests or Rate Limiting
581
-
582
- **Symptoms:** Provider returns 429 errors
583
-
584
- **Solutions:**
585
-
586
- 1. **Enable fallback provider:**
587
- ```env
588
- FALLBACK_ENABLED=true
589
- FALLBACK_PROVIDER=databricks
590
- ```
591
-
592
- 2. **Switch to Ollama** (no rate limits):
593
- ```env
594
- MODEL_PROVIDER=ollama
595
- OLLAMA_MODEL=llama3.1:8b
596
- ```
597
-
598
- 3. **Use OpenRouter** (pooled rate limits across providers):
599
- ```env
600
- MODEL_PROVIDER=openrouter
601
- ```
602
-
603
- ---
604
-
605
- ### Enable Debug Logging
606
-
607
- For detailed troubleshooting:
608
-
609
- ```bash
610
- # In .env
611
- LOG_LEVEL=debug
612
-
613
- # Restart Lynkr
614
- npm start
615
-
616
- # Check logs for detailed request/response info
617
- ```
618
-
619
- ---
620
-
621
- ## Architecture
622
-
623
- ```
624
- Cursor IDE
625
- ↓ OpenAI API format
626
- Lynkr Proxy
627
- ↓ Converts to Anthropic format
628
- Your Provider (Databricks/Bedrock/OpenRouter/Ollama/etc.)
629
- ↓ Returns response
630
- Lynkr Proxy
631
- ↓ Converts back to OpenAI format
632
- Cursor IDE (displays result)
633
- ```
634
-
635
- ---
636
-
637
- ## Advanced Configuration Examples
638
-
639
- ### Setup 1: Simplest (One Key for Everything - OpenRouter)
640
-
641
- ```bash
642
- # Chat + Embeddings: OpenRouter handles both with ONE key
643
- MODEL_PROVIDER=openrouter
644
- OPENROUTER_API_KEY=sk-or-v1-your-key-here
645
-
646
- # Done! Everything works with one key
647
- ```
648
-
649
- **Benefits:**
650
- - ✅ ONE key for chat + embeddings
651
- - ✅ 100+ models available
652
- - ✅ Automatic fallbacks
653
- - ✅ Competitive pricing
654
-
655
- ---
656
-
657
- ### Setup 2: Privacy-First (100% Local)
658
-
659
- ```bash
660
- # Chat: Ollama (local)
661
- MODEL_PROVIDER=ollama
662
- OLLAMA_MODEL=llama3.1:8b
663
-
664
- # Embeddings: Ollama (local)
665
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
666
-
667
- # Everything runs on your machine, zero cloud dependencies
668
- ```
669
-
670
- **Benefits:**
671
- - ✅ 100% FREE
672
- - ✅ 100% private (all data stays local)
673
- - ✅ Works offline
674
- - ✅ Full @Codebase support
675
-
676
- ---
677
-
678
- ### Setup 3: Hybrid (Best of Both Worlds)
679
-
680
- ```bash
681
- # Chat: Tier-based routing (set all 4 to enable)
682
- TIER_SIMPLE=ollama:llama3.2
683
- TIER_MEDIUM=openrouter:openai/gpt-4o-mini
684
- TIER_COMPLEX=databricks:databricks-claude-sonnet-4-5
685
- TIER_REASONING=databricks:databricks-claude-sonnet-4-5
686
- FALLBACK_ENABLED=true
687
- FALLBACK_PROVIDER=databricks
688
- DATABRICKS_API_BASE=https://your-workspace.databricks.com
689
- DATABRICKS_API_KEY=your-key
690
-
691
- # Embeddings: Ollama (local, private)
692
- OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
693
-
694
- # Cost: Mostly FREE (Ollama handles 70-80% of simple requests)
695
- # Only complex/reasoning requests go to Databricks
696
- ```
697
-
698
- **Benefits:**
699
- - ✅ Mostly FREE (70-80% of requests on Ollama via TIER_SIMPLE)
700
- - ✅ Private embeddings (local search)
701
- - ✅ Cloud quality for complex tasks
702
- - ✅ Automatic intelligent tier-based routing
703
-
704
- ---
705
-
706
- ## Cursor vs Native Comparison
707
-
708
- | Aspect | Cursor Native | Lynkr + Cursor |
709
- |--------|---------------|----------------|
710
- | **Providers** | OpenAI only | 12+ providers (Bedrock, Databricks, OpenRouter, Ollama, llama.cpp, Moonshot, etc.) |
711
- | **Costs** | OpenAI pricing | 60-80% cheaper (or 100% FREE with Ollama) |
712
- | **Privacy** | Cloud-only | Can run 100% locally (Ollama + local embeddings) |
713
- | **Embeddings** | Built-in (cloud) | 4 options: Ollama (local), llama.cpp (local), OpenRouter (cloud), OpenAI (cloud) |
714
- | **Control** | Black box | Full observability, logs, metrics |
715
- | **Features** | All Cursor features | All Cursor features (chat, Cmd+K, @Codebase) |
716
- | **Flexibility** | Fixed setup | Mix providers (e.g., Bedrock chat + Ollama embeddings) |
717
-
718
- ---
719
-
720
- ## Next Steps
721
-
722
- - **[Embeddings Configuration](embeddings.md)** - Detailed embeddings setup guide
723
- - **[Provider Configuration](providers.md)** - Configure all providers
724
- - **[Installation Guide](installation.md)** - Install Lynkr
725
- - **[Troubleshooting](troubleshooting.md)** - More troubleshooting tips
726
- - **[FAQ](faq.md)** - Frequently asked questions
727
-
728
- ---
729
-
730
- ## Getting Help
731
-
732
- - **[GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions)** - Community Q&A
733
- - **[GitHub Issues](https://github.com/vishalveerareddy123/Lynkr/issues)** - Report bugs
734
- - **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions