lynkr 8.0.1 → 9.0.1

package/README.md

@@ -1,429 +1,303 @@
-# Lynkr - Run Cursor, Cline, Continue, OpenAi Compatible Tools and Claude Code on any model.
-## One universal LLM proxy for AI coding tools.
+# Lynkr
+
+### Run Claude Code, Cursor, and Codex on any model. One proxy, every provider.
 
 [![npm version](https://img.shields.io/npm/v/lynkr.svg)](https://www.npmjs.com/package/lynkr)
-[![Homebrew Tap](https://img.shields.io/badge/homebrew-lynkr-brightgreen.svg)](https://github.com/vishalveerareddy123/homebrew-lynkr)
+[![Tests](https://img.shields.io/badge/tests-652%20passing-brightgreen)](https://github.com/vishalveerareddy123/Lynkr)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-20%2B-green)](https://nodejs.org)
+[![Homebrew Tap](https://img.shields.io/badge/homebrew-lynkr-brightgreen.svg)](https://github.com/vishalveerareddy123/homebrew-lynkr)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vishalveerareddy123/Lynkr)
-[![Databricks Supported](https://img.shields.io/badge/Databricks-Supported-orange)](https://www.databricks.com/)
-[![AWS Bedrock](https://img.shields.io/badge/AWS%20Bedrock-100%2B%20Models-FF9900)](https://aws.amazon.com/bedrock/)
-[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-412991)](https://openai.com/)
-[![Ollama Compatible](https://img.shields.io/badge/Ollama-Compatible-brightgreen)](https://ollama.ai/)
-[![llama.cpp Compatible](https://img.shields.io/badge/llama.cpp-Compatible-blue)](https://github.com/ggerganov/llama.cpp)
 
-### Use Case
-```
-        Cursor / Cline / Continue / Claude Code / Clawdbot / Codex/ KiloCode
-                        ↓
-                       Lynkr
-                        ↓
-        Local LLMs | OpenRouter | Azure | Databricks | AWS BedRock | Ollama | LMStudio | Gemini
-```
----
+<table>
+<tr>
+<td align="center"><strong>10+</strong><br/>LLM Providers</td>
+<td align="center"><strong>60-80%</strong><br/>Cost Reduction</td>
+<td align="center"><strong>652</strong><br/>Tests Passing</td>
+<td align="center"><strong>0</strong><br/>Code Changes Required</td>
+</tr>
+</table>
 
-## Overview
+---
 
-Lynkr is a **self-hosted proxy server** that unlocks Claude Code CLI , Cursor IDE and Codex Cli by enabling:
+## The Problem
 
-- 🚀 **Any LLM Provider** - Databricks, AWS Bedrock (100+ models), OpenRouter (100+ models), Ollama (local), llama.cpp, Azure OpenAI, Azure Anthropic, OpenAI, LM Studio
-- 💰 **60-80% Cost Reduction** - Built-in token optimization with smart tool selection, prompt caching, and memory deduplication
-- 🔒 **100% Local/Private** - Run completely offline with Ollama or llama.cpp
-- 🌐 **Remote or Local** - Connect to providers on any IP/hostname (not limited to localhost)
-- 🎯 **Zero Code Changes** - Drop-in replacement for Anthropic's backend
-- 🏢 **Enterprise-Ready** - Circuit breakers, load shedding, Prometheus metrics, health checks
+AI coding tools lock you into one provider. Claude Code requires Anthropic. Codex requires OpenAI. You can't use your company's Databricks endpoint, your local Ollama models, or your AWS Bedrock account — at least, not without Lynkr.
 
-**Perfect for:**
-- Developers who want provider flexibility and cost control
-- Enterprises needing self-hosted AI with observability
-- Privacy-focused teams requiring local model execution
-- Teams seeking 60-80% cost reduction through optimization
+**The real costs:**
+- Anthropic API at $15/MTok output adds up fast for daily coding
+- No way to use free local models (Ollama, llama.cpp) with Claude Code
+- Enterprise teams can't route through their own cloud infrastructure
+- Provider outages take your entire workflow down
 
----
+## The Solution
 
-## Quick Start
+Lynkr is a self-hosted proxy that sits between your AI coding tools and any LLM provider. One environment variable change, and your tools work with any model.
 
-### Installation
+```
+Claude Code / Cursor / Codex / Cline / Continue / Vercel AI SDK
+                        |
+                      Lynkr
+                        |
+    Ollama | Bedrock | Databricks | OpenRouter | Azure | OpenAI | llama.cpp
+```
 
-**Option 1: NPM Package (Recommended)**
 ```bash
-# Install globally
-npm install -g pino-pretty 
+# That's it. Three lines.
 npm install -g lynkr
-
+export ANTHROPIC_BASE_URL=http://localhost:8081
 lynkr start
 ```
 
-**Option 2: Git Clone**
-```bash
-# Clone repository
-git clone https://github.com/vishalveerareddy123/Lynkr.git
-cd Lynkr
-
-# Install dependencies
-npm install
+---
 
-# Create .env from example
-cp .env.example .env
+## Quick Start
 
-# Edit .env with your provider credentials
-nano .env
+### Install
 
-# Start server
-npm start
+```bash
+npm install -g pino-pretty && npm install -g lynkr
 ```
 
-**Node.js Compatibility:**
-- **Node 20-24**: Full support with all features
-- **Node 25+**: Full support (native modules auto-rebuild, babel fallback for code parsing)
+### Pick a Provider
 
-
-
-**Option 3: Docker**
+**Free & Local (Ollama)**
 ```bash
-docker-compose up -d
+export MODEL_PROVIDER=ollama
+export OLLAMA_MODEL=qwen2.5-coder:latest
+lynkr start
 ```
 
----
-
-## Supported Providers
-
-Lynkr supports **10+ LLM providers**:
-
-| Provider | Type | Models | Cost | Privacy |
-|----------|------|--------|------|---------|
-| **AWS Bedrock** | Cloud | 100+ (Claude, Titan, Llama, Mistral, etc.) | $$-$$$ | Cloud |
-| **Databricks** | Cloud | Claude Sonnet 4.5, Opus 4.5 | $$$ | Cloud |
-| **OpenRouter** | Cloud | 100+ (GPT, Claude, Llama, Gemini, etc.) | $-$$ | Cloud |
-| **Ollama** | Local | Unlimited (free, offline) | **FREE** | 🔒 100% Local |
-| **llama.cpp** | Local | GGUF models | **FREE** | 🔒 100% Local |
-| **Azure OpenAI** | Cloud | GPT-4o, GPT-5, o1, o3 | $$$ | Cloud |
-| **Azure Anthropic** | Cloud | Claude models | $$$ | Cloud |
-| **OpenAI** | Cloud | GPT-4o, o1, o3 | $$$ | Cloud |
-| **LM Studio** | Local | Local models with GUI | **FREE** | 🔒 100% Local |
-| **MLX OpenAI Server** | Local | Apple Silicon (M1/M2/M3/M4) | **FREE** | 🔒 100% Local |
-
-📖 **[Full Provider Configuration Guide](documentation/providers.md)**
-
----
+**AWS Bedrock (100+ models)**
+```bash
+export MODEL_PROVIDER=bedrock
+export AWS_BEDROCK_API_KEY=your-key
+export AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
+lynkr start
+```
 
-## Claude Code Integration
+**OpenRouter (cheapest cloud)**
+```bash
+export MODEL_PROVIDER=openrouter
+export OPENROUTER_API_KEY=sk-or-v1-your-key
+lynkr start
+```
 
-Configure Claude Code CLI to use Lynkr:
+### Connect Your Tool
 
+**Claude Code**
 ```bash
-# Set Lynkr as backend
 export ANTHROPIC_BASE_URL=http://localhost:8081
 export ANTHROPIC_API_KEY=dummy
-
-# Run Claude Code
 claude "Your prompt here"
 ```
 
-That's it! Claude Code now uses your configured provider.
-
-📖 **[Detailed Claude Code Setup](documentation/claude-code-cli.md)**
-
----
-
-## Cursor Integration
-
-Configure Cursor IDE to use Lynkr:
-
-1. **Open Cursor Settings**
-   - Mac: `Cmd+,` | Windows/Linux: `Ctrl+,`
-   - Navigate to: **Features** → **Models**
-
-2. **Configure OpenAI API Settings**
-   - **API Key**: `sk-lynkr` (any non-empty value)
-   - **Base URL**: `http://localhost:8081/v1`
-   - **Model**: `claude-3.5-sonnet` (or your provider's model)
-
-3. **Test It**
-   - Chat: `Cmd+L` / `Ctrl+L`
-   - Inline edits: `Cmd+K` / `Ctrl+K`
-   - @Codebase search: Requires [embeddings setup](documentation/embeddings.md)
-
-📖 **[Full Cursor Setup Guide](documentation/cursor-integration.md)** | **[Embeddings Configuration](documentation/embeddings.md)**
----
-## Codex CLI Integration
-
-Configure [OpenAI Codex CLI](https://github.com/openai/codex) to use Lynkr as its backend.
-
-### Option 1: Environment Variables (Quick Start)
-
-```bash
-export OPENAI_BASE_URL=http://localhost:8081/v1
-export OPENAI_API_KEY=dummy
-
-codex
-```
-
-### Option 2: Config File (Recommended)
-
-Edit `~/.codex/config.toml`:
-
+**Codex CLI** — edit `~/.codex/config.toml`:
 ```toml
-# Set Lynkr as the default provider
 model_provider = "lynkr"
 model = "gpt-4o"
 
-# Define the Lynkr provider
 [model_providers.lynkr]
 name = "Lynkr Proxy"
 base_url = "http://localhost:8081/v1"
 wire_api = "responses"
-
-# Optional: Trust your project directories
-[projects."/path/to/your/project"]
-trust_level = "trusted"
 ```
 
-### Configuration Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `model_provider` | Active provider name | `"lynkr"` |
-| `model` | Model to request (mapped by Lynkr) | `"gpt-4o"`, `"claude-sonnet-4-5"` |
-| `base_url` | Lynkr endpoint | `"http://localhost:8081/v1"` |
-| `wire_api` | API format (`responses` or `chat`) | `"responses"` |
-| `trust_level` | Project trust (`trusted`, `sandboxed`) | `"trusted"` |
-
-### Remote Lynkr Server
-
-To connect Codex to a remote Lynkr instance:
-
-```toml
-[model_providers.lynkr-remote]
-name = "Remote Lynkr"
-base_url = "http://192.168.1.100:8081/v1"
-wire_api = "responses"
+**Cursor IDE**
+- Settings > Features > Models
+- Base URL: `http://localhost:8081/v1`
+- API Key: `sk-lynkr`
+
+**Vercel AI SDK**
+```ts
+import { generateText } from "ai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+
+const lynkr = createOpenAICompatible({
+  baseURL: "http://localhost:8081/v1",
+  name: "lynkr",
+  apiKey: "sk-lynkr",
+});
+
+const { text } = await generateText({
+  model: lynkr.chatModel("auto"),
+  prompt: "Hello!",
+});
 ```
 
-### Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Same response for all queries | Disable semantic cache: `SEMANTIC_CACHE_ENABLED=false` |
-| Tool calls not executing | Increase threshold: `POLICY_TOOL_LOOP_THRESHOLD=15` |
-| Slow first request | Keep Ollama loaded: `OLLAMA_KEEP_ALIVE=24h` |
-| Connection refused | Ensure Lynkr is running: `npm start` |
-
-> **Note:** Codex uses the OpenAI Responses API format. Lynkr automatically converts this to your configured provider's format.
+> Works with any OpenAI-compatible client: Cline, Continue.dev, ClawdBot, KiloCode, and more.
 
 ---
 
-## ClawdBot Integration
-
-Lynkr supports [ClawdBot](https://github.com/openclaw/openclaw) via its OpenAI-compatible API. ClawdBot users can route requests through Lynkr to access any supported provider.
+## Supported Providers
 
-**Configuration in ClawdBot:**
-| Setting | Value |
-|---------|-------|
-| Model/auth provider | `Copilot` |
-| Copilot auth method | `Copilot Proxy (local)` |
-| Copilot Proxy base URL | `http://localhost:8081/v1` |
-| Model IDs | Any model your Lynkr provider supports |
+| Provider | Type | Models | Cost |
+|----------|------|--------|------|
+| **Ollama** | Local | Unlimited (free, offline) | **Free** |
+| **llama.cpp** | Local | Any GGUF model | **Free** |
+| **LM Studio** | Local | Local models with GUI | **Free** |
+| **MLX Server** | Local | Apple Silicon optimized | **Free** |
+| **AWS Bedrock** | Cloud | 100+ (Claude, Llama, Mistral, Titan) | $$ |
+| **OpenRouter** | Cloud | 100+ (GPT, Claude, Llama, Gemini) | $-$$ |
+| **Databricks** | Cloud | Claude Sonnet 4.5, Opus 4.5 | $$$ |
+| **Azure OpenAI** | Cloud | GPT-4o, GPT-5, o1, o3 | $$$ |
+| **Azure Anthropic** | Cloud | Claude models | $$$ |
+| **OpenAI** | Cloud | GPT-4o, o1, o3 | $$$ |
+
+4 local providers for **100% offline, free** usage. 6+ cloud providers for scale.
 
-**Available models** (depending on your Lynkr provider):
-`gpt-5.2`, `gpt-5.1-codex`, `claude-opus-4.5`, `claude-sonnet-4.5`, `claude-haiku-4.5`, `gemini-3-pro`, `gemini-3-flash`, and more.
+---
 
-> 🌐 **Remote Support**: ClawdBot can connect to Lynkr on any machine - use any IP/hostname in the Proxy base URL (e.g., `http://192.168.1.100:8081/v1` or `http://gpu-server:8081/v1`).
+## Why Lynkr Over Alternatives
+
+| Feature | Lynkr | LiteLLM (42K stars) | OpenRouter | PortKey |
+|---------|-------|---------------------|------------|---------|
+| **Setup** | `npm install -g lynkr` | Python + Docker + Postgres | Account signup | Docker + config |
+| **Claude Code support** | Drop-in, native | Requires config | No CLI support | Requires config |
+| **Cursor support** | Drop-in, native | Partial | Via API key | Partial |
+| **Codex CLI support** | Drop-in, native | No | No | No |
+| **Built for coding tools** | Yes (purpose-built) | No (general gateway) | No (general API) | No (general gateway) |
+| **Local models** | Ollama, llama.cpp, LM Studio, MLX | Ollama only | No | No |
+| **Token optimization** | Built-in (60-80% savings) | No | No | Caching only |
+| **Complexity routing** | Auto-routes by task difficulty | Manual | Cost/latency only | Manual |
+| **Memory system** | Titans-inspired long-term memory | No | No | No |
+| **Self-hosted** | Yes (Node.js) | Yes (Python stack) | No (SaaS) | Yes (Docker) |
+| **Offline capable** | Yes | Yes | No | No |
+| **Transaction fees** | None | None (OSS) / Paid enterprise | 5.5% on credits | Free tier / Paid |
+| **Dependencies** | Node.js only | Python, Prisma, PostgreSQL | N/A | Docker, Python |
+| **Format conversion** | Anthropic <-> OpenAI (automatic) | Automatic | N/A | Automatic |
+| **License** | Apache 2.0 | MIT | Proprietary | MIT (gateway) |
+
+**Lynkr's edge:** Purpose-built for AI coding tools. Not a general LLM gateway — a proxy that understands Claude Code, Cursor, and Codex natively, with built-in token optimization, complexity-based routing, and a memory system designed for coding workflows. Installs in one command, runs on Node.js, zero infrastructure required.
 
 ---
 
-## Lynkr also supports  Cline, Continue.dev and other OpenAI compatible tools.
----
+## Cost Comparison
 
-## Documentation
+| Scenario | Direct Anthropic | Lynkr + Ollama | Lynkr + OpenRouter | Lynkr + Bedrock |
+|----------|-----------------|----------------|--------------------| --------------- |
+| Daily Claude Code usage | ~$10-30/day | **$0 (free)** | ~$2-8/day | ~$5-15/day |
+| Token optimization savings | — | — | 60-80% further | 60-80% further |
+| Monthly (heavy use) | $300-900 | **$0** | $60-240 | $150-450 |
 
-### Getting Started
-- 📦 **[Installation Guide](documentation/installation.md)** - Detailed installation for all methods
-- ⚙️ **[Provider Configuration](documentation/providers.md)** - Complete setup for all 12+ providers
-- 🎯 **[Quick Start Examples](documentation/installation.md#quick-start-examples)** - Copy-paste configs
-
-### IDE & CLI Integration
-- 🖥️ **[Claude Code CLI Setup](documentation/claude-code-cli.md)** - Connect Claude Code CLI
-- 🤖 **[Codex CLI Setup](documentation/codex-cli.md)** - Configure OpenAI Codex CLI with config.toml
-- 🎨 **[Cursor IDE Setup](documentation/cursor-integration.md)** - Full Cursor integration with troubleshooting
-- 🔍 **[Embeddings Guide](documentation/embeddings.md)** - Enable @Codebase semantic search (4 options: Ollama, llama.cpp, OpenRouter, OpenAI)
-
-### Features & Capabilities
-- ✨ **[Core Features](documentation/features.md)** - Architecture, request flow, format conversion
-- 🧠 **[Memory System](documentation/memory-system.md)** - Titans-inspired long-term memory
-- 🗃️ **[Semantic Cache](#semantic-cache)** - Cache responses for similar prompts
-- 💰 **[Token Optimization](documentation/token-optimization.md)** - 60-80% cost reduction strategies
-- 🔧 **[Tools & Execution](documentation/tools.md)** - Tool calling, execution modes, custom tools
-
-### Deployment & Operations
-- 🐳 **[Docker Deployment](documentation/docker.md)** - docker-compose setup with GPU support
-- 🏭 **[Production Hardening](documentation/production.md)** - Circuit breakers, load shedding, metrics
-- 📊 **[API Reference](documentation/api.md)** - All endpoints and formats
-
-### Support
-- 🔧 **[Troubleshooting](documentation/troubleshooting.md)** - Common issues and solutions
-- ❓ **[FAQ](documentation/faq.md)** - Frequently asked questions
-- 🧪 **[Testing Guide](documentation/testing.md)** - Running tests and validation
+> With token optimization enabled, Lynkr's smart tool selection, prompt caching, and memory deduplication reduce token usage by 60-80% on top of provider savings.
 
 ---
 
-## External Resources
+## What's Under the Hood
 
-- 📚 **[DeepWiki Documentation](https://deepwiki.com/vishalveerareddy123/Lynkr)** - AI-powered documentation search
-- 💬 **[GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions)** - Community Q&A
-- 🐛 **[Report Issues](https://github.com/vishalveerareddy123/Lynkr/issues)** - Bug reports and feature requests
-- 📦 **[NPM Package](https://www.npmjs.com/package/lynkr)** - Official npm package
+Lynkr isn't just a passthrough proxy. It's an optimization layer.
 
----
+### Smart Routing
+Routes requests to the right model based on task complexity. Simple questions go to fast/cheap models. Complex architectural tasks go to powerful models. You configure the tiers.
 
-## Key Features Highlights
-
-- ✅ **Multi-Provider Support** - 12+ providers including local (Ollama, llama.cpp) and cloud (Bedrock, Databricks, OpenRouter, Moonshot AI)
-- ✅ **60-80% Cost Reduction** - Token optimization with smart tool selection, prompt caching, memory deduplication
-- ✅ **100% Local Option** - Run completely offline with Ollama/llama.cpp (zero cloud dependencies)
-- ✅ **OpenAI Compatible** - Works with Cursor IDE, Continue.dev, and any OpenAI-compatible client
-- ✅ **Embeddings Support** - 4 options for @Codebase search: Ollama (local), llama.cpp (local), OpenRouter, OpenAI
-- ✅ **MCP Integration** - Automatic Model Context Protocol server discovery and orchestration
-- ✅ **Enterprise Features** - Circuit breakers, load shedding, Prometheus metrics, K8s health checks
-- ✅ **Streaming Support** - Real-time token streaming for all providers
-- ✅ **Memory System** - Titans-inspired long-term memory with surprise-based filtering
-- ✅ **Tool Calling** - Full tool support with server and passthrough execution modes
-- ✅ **Production Ready** - Battle-tested with 400+ tests, observability, and error resilience
-- ✅ **Node 20-25 Support** - Works with latest Node.js versions including v25
-- ✅ **Semantic Caching** - Cache responses for similar prompts (requires embeddings)
+### Token Optimization
+- **Smart tool selection** — only sends tools relevant to the current task
+- **Prompt compression** — removes redundant context before sending
+- **Memory deduplication** — eliminates repeated information across turns
+- **TOON format** — compact serialization that cuts token count
 
----
+### Enterprise Resilience
+- **Circuit breakers** — automatic failover when a provider goes down
+- **Load shedding** — graceful degradation under high load
+- **Prometheus metrics** — full observability at `/metrics`
+- **Health checks** — K8s-ready endpoints at `/health`
 
-## Semantic Cache
+### Memory System
+Titans-inspired long-term memory with surprise-based filtering. The system remembers important context across sessions and forgets noise — reducing token waste from repeated context.
 
-Lynkr includes an optional semantic response cache that returns cached responses for semantically similar prompts, reducing latency and costs.
+### Semantic Cache
+Cache responses for semantically similar prompts. Hit rate depends on your workflow, but repeat questions (common in coding) get instant responses.
 
-**Enable Semantic Cache:**
 ```bash
-# Requires an embeddings provider (Ollama recommended)
-ollama pull nomic-embed-text
-
-# Add to .env
 SEMANTIC_CACHE_ENABLED=true
 SEMANTIC_CACHE_THRESHOLD=0.95
-OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-OLLAMA_EMBEDDINGS_ENDPOINT=http://localhost:11434/api/embeddings
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `SEMANTIC_CACHE_ENABLED` | `false` | Enable/disable semantic caching |
-| `SEMANTIC_CACHE_THRESHOLD` | `0.95` | Similarity threshold (0.0-1.0) |
-
-> **Note:** Without a proper embeddings provider, the cache uses hash-based fallback which may cause false matches. Use Ollama with `nomic-embed-text` for best results.
-
----
-
-## Architecture
-
-```
-┌─────────────────┐
-│    AI Tools     │  
-└────────┬────────┘
-         │ Anthropic/OpenAI Format
-         ↓
-┌─────────────────┐
-│  Lynkr Proxy    │
-│  Port: 8081     │
-│                 │
-│ • Format Conv.  │
-│ • Token Optim.  │
-│ • Provider Route│
-│ • Tool Calling  │
-│ • Caching       │
-└────────┬────────┘
-         │
-         ├──→ Databricks (Claude 4.5)
-         ├──→ AWS Bedrock (100+ models)
-         ├──→ OpenRouter (100+ models)
-         ├──→ Ollama (local, free)
-         ├──→ llama.cpp (local, free)
-         ├──→ Azure OpenAI (GPT-4o, o1)
-         ├──→ OpenAI (GPT-4o, o3)
-         └──→ Azure Anthropic (Claude)
 ```
 
-📖 **[Detailed Architecture](documentation/features.md#architecture)**
+### MCP Integration
+Automatic Model Context Protocol server discovery and orchestration. Your MCP tools work through Lynkr without configuration.
 
 ---
 
-## Quick Configuration Examples
+## Deployment Options
 
-**100% Local (FREE)**
+**NPM (recommended)**
 ```bash
-export MODEL_PROVIDER=ollama
-export OLLAMA_MODEL=qwen2.5-coder:latest
-export OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-npm start
+npm install -g lynkr && lynkr start
 ```
-> 💡 **Tip:** Prevent slow cold starts by keeping Ollama models loaded: `launchctl setenv OLLAMA_KEEP_ALIVE "24h"` (macOS) or set `OLLAMA_KEEP_ALIVE=24h` env var. See [troubleshooting](documentation/troubleshooting.md#slow-first-request--cold-start-warning).
 
-**Remote Ollama (GPU Server)**
+**Docker**
 ```bash
-export MODEL_PROVIDER=ollama
-export OLLAMA_ENDPOINT=http://192.168.1.100:11434  # Any IP or hostname
-export OLLAMA_MODEL=llama3.1:70b
-npm start
+docker-compose up -d
 ```
-> 🌐 **Note:** All provider endpoints support remote addresses - not limited to localhost. Use any IP, hostname, or domain.
 
-**MLX OpenAI Server (Apple Silicon)**
+**Git Clone**
 ```bash
-# Terminal 1: Start MLX server
-mlx-openai-server launch --model-path mlx-community/Qwen2.5-Coder-7B-Instruct-4bit --model-type lm
-
-# Terminal 2: Start Lynkr
-export MODEL_PROVIDER=openai
-export OPENAI_ENDPOINT=http://localhost:8000/v1/chat/completions
-export OPENAI_API_KEY=not-needed
+git clone https://github.com/vishalveerareddy123/Lynkr.git
+cd Lynkr && npm install && cp .env.example .env
 npm start
 ```
-> 🍎 **Apple Silicon optimized** - Native MLX performance on M1/M2/M3/M4 Macs. See [MLX setup guide](documentation/providers.md#10-mlx-openai-server-apple-silicon).
 
-**AWS Bedrock (100+ models)**
+**Homebrew**
 ```bash
-export MODEL_PROVIDER=bedrock
-export AWS_BEDROCK_API_KEY=your-key
-export AWS_BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
-npm start
+brew tap vishalveerareddy123/lynkr
+brew install lynkr
 ```
 
-**OpenRouter (simplest cloud)**
-```bash
-export MODEL_PROVIDER=openrouter
-export OPENROUTER_API_KEY=sk-or-v1-your-key
-npm start
-```
-** You can setup multiple models like local models
-📖 **[More Examples](documentation/providers.md#quick-start-examples)**
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Installation](documentation/installation.md) | All installation methods |
+| [Provider Config](documentation/providers.md) | Setup for all 10+ providers |
+| [Claude Code CLI](documentation/claude-code-cli.md) | Detailed Claude Code integration |
+| [Codex CLI](documentation/codex-cli.md) | Codex config.toml setup |
+| [Cursor IDE](documentation/cursor-integration.md) | Cursor integration + troubleshooting |
+| [Embeddings](documentation/embeddings.md) | @Codebase semantic search (4 options) |
+| [Token Optimization](documentation/token-optimization.md) | 60-80% cost reduction strategies |
+| [Memory System](documentation/memory-system.md) | Titans-inspired long-term memory |
+| [Tools & Execution](documentation/tools.md) | Tool calling and execution modes |
+| [Smart Routing](documentation/routing.md) | Complexity-based model routing |
+| [Docker Deployment](documentation/docker.md) | docker-compose with GPU support |
+| [Production Hardening](documentation/production.md) | Circuit breakers, metrics, load shedding |
+| [API Reference](documentation/api.md) | All endpoints and formats |
+| [Troubleshooting](documentation/troubleshooting.md) | Common issues and solutions |
+| [FAQ](documentation/faq.md) | Frequently asked questions |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Same response for all queries | Disable semantic cache: `SEMANTIC_CACHE_ENABLED=false` |
+| Tool calls not executing | Increase threshold: `POLICY_TOOL_LOOP_THRESHOLD=15` |
+| Slow first request | Keep Ollama loaded: `OLLAMA_KEEP_ALIVE=24h` |
+| Connection refused | Ensure Lynkr is running: `lynkr start` |
 
 ---
 
 ## Contributing
 
-We welcome contributions! Please see:
-- **[Contributing Guide](documentation/contributing.md)** - How to contribute
-- **[Testing Guide](documentation/testing.md)** - Running tests
+We welcome contributions. See the [Contributing Guide](documentation/contributing.md) and [Testing Guide](documentation/testing.md).
 
 ---
 
 ## License
 
-Apache 2.0 - See [LICENSE](LICENSE) file for details.
+Apache 2.0 — See [LICENSE](LICENSE).
 
 ---
 
-## Community & Support
+## Community
 
-- ⭐ **Star this repo** if Lynkr helps you!
-- 💬 **[Join Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions)** - Ask questions, share tips
-- 🐛 **[Report Issues](https://github.com/vishalveerareddy123/Lynkr/issues)** - Bug reports welcome
-- 📖 **[Read the Docs](documentation/)** - Comprehensive guides
+- [GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions) — Questions and tips
+- [Report Issues](https://github.com/vishalveerareddy123/Lynkr/issues) — Bug reports and feature requests
+- [NPM Package](https://www.npmjs.com/package/lynkr) — Official package
+- [DeepWiki](https://deepwiki.com/vishalveerareddy123/Lynkr) — AI-powered docs search
 
 ---
 
-**Made with ❤️ by developers, for developers.**
+**Built by [Vishal Veera Reddy](https://github.com/vishalveerareddy123) — for developers who want control over their AI tools.**