feat: add consume pattern, Viewer improvements, and Log Hub docs (v1.16.1)

- Log Hub: consume parameter removes entries after query (poll pattern)
- Viewer: Clear button in Logs tab, WebSocket auto-reconnect
- Fix: data:null no longer shows "null" text in Viewer and MCP output
- Docs: LogHub Developer Guide with code examples for C#, Python, JS, C++, PowerShell
- README: new Log Hub section with architecture diagram and quick start

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: CSCSoftware

.claude/CLAUDE.md

@@ -2,7 +2,7 @@
 
 MCP Server für persistentes Code-Indexing. Ermöglicht Claude Code schnelle, präzise Suchen statt Grep/Glob.
 
-**Version:** 1.16.0 | **Sprachen:** 11 | **Repo:** https://github.com/CSCSoftware/AiDex
+**Version:** 1.16.1 | **Sprachen:** 11 | **Repo:** https://github.com/CSCSoftware/AiDex
 
 ## Build & Run
 
@@ -276,6 +276,109 @@ node build/index.js init <path>  # Indexieren
 - **Arrow Functions:** Werden als Methods erkannt (gewollt, etwas Noise)
 - **Keyword-Filter:** Pro Sprache in `src/parser/languages/`
 
+## LogHub Developer Guide
+
+### Übersicht
+
+LogHub ist ein universeller Log-Empfänger. Jedes Programm kann per HTTP POST Logs senden — keine Library, kein SDK nötig. Die KI kann die Logs abfragen, der User sieht sie live im AiDex Viewer.
+
+### Setup (durch die KI)
+
+```
+1. aidex_log({ action: "init" })                    # Server starten (Port 3335)
+2. aidex_viewer({ path: "." })                       # Viewer öffnen → Logs-Tab zeigt Live-Stream
+3. Logging in das Programm einbauen (siehe unten)
+4. aidex_log({ action: "query", since: "5m" })       # KI fragt Logs ab
+5. aidex_log({ action: "free" })                     # Am Ende: Server stoppen
+```
+
+### HTTP API
+
+| Endpoint | Method | Body | Beschreibung |
+|----------|--------|------|--------------|
+| `/log` | POST | `{ level, source, message, data? }` | Einzelner Log-Eintrag |
+| `/logs` | POST | `[{ level, source, message, data? }, ...]` | Batch (mehrere auf einmal) |
+| `/health` | GET | — | Status + Buffer-Auslastung |
+
+**Felder:**
+- `level`: `"debug"`, `"info"`, `"warn"`, `"error"` (default: `"info"`)
+- `source`: Name der App/Komponente (z.B. `"MyApp"`, `"Parser"`)
+- `message`: Log-Text (required)
+- `data`: Beliebiges JSON-Objekt für strukturierte Daten (optional)
+- `timestamp`: Unix-Timestamp in ms (optional, sonst Server-Zeit)
+
+### Code-Beispiele für verschiedene Sprachen
+
+**C# (.NET)**
+```csharp
+using var http = new HttpClient();
+http.PostAsJsonAsync("http://localhost:3335/log", new {
+    level = "info",
+    source = "MyApp",
+    message = "Player spawned",
+    data = new { x = 10, y = 20 }
+});
+```
+
+**C# (Minimal-Helper)**
+```csharp
+// Einmal initialisieren
+static readonly HttpClient _log = new();
+static void Log(string msg, string level = "info", object? data = null) {
+    var body = new { level, source = "MyApp", message = msg, data };
+    _ = _log.PostAsJsonAsync("http://localhost:3335/log", body);
+}
+
+// Verwenden
+Log("Game started");
+Log("Error loading level", "error", new { levelId = 5 });
+```
+
+**Python**
+```python
+import requests
+requests.post("http://localhost:3335/log", json={
+    "level": "info",
+    "source": "MyScript",
+    "message": "Processing complete",
+    "data": {"items": 42}
+})
+```
+
+**JavaScript / Node.js**
+```javascript
+fetch("http://localhost:3335/log", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+        level: "info",
+        source: "MyApp",
+        message: "Server started",
+    })
+});
+```
+
+**C / C++ (curl)**
+```c
+// Mit libcurl oder shell:
+// curl -X POST http://localhost:3335/log -H "Content-Type: application/json" -d '{"level":"info","source":"MyApp","message":"Init done"}'
+```
+
+**PowerShell**
+```powershell
+Invoke-RestMethod -Uri "http://localhost:3335/log" -Method POST -ContentType "application/json" -Body '{"level":"info","source":"MyApp","message":"Task done"}'
+```
+
+### Tipps für die KI
+
+- **Viewer immer mit anbieten** — `aidex_viewer({ path: "." })` öffnet den Browser, Logs-Tab zeigt Live-Stream via WebSocket
+- **Source sinnvoll wählen** — ermöglicht Filtern per `aidex_log({ action: "query", source: "MyApp" })`
+- **Level nutzen** — `error` für Fehler, `warn` für Warnungen, `debug` für Verbose
+- **Batch für Performance** — bei vielen Logs pro Sekunde `/logs` statt `/log` verwenden
+- **Consume-Pattern** — `aidex_log({ action: "query", consume: true })` holt Logs und entfernt sie aus dem Buffer (Poll-Muster)
+- **Fire & Forget** — Logs asynchron senden (kein await nötig), damit die App nicht blockiert
+- **Kein Error-Handling nötig** — wenn LogHub nicht läuft, schlägt der POST still fehl
+
 ## Dokumentation
 
 | Datei | Inhalt |

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to AiDex will be documented in this file.
 
 ## [Unreleased]
 
+## [1.16.1] - 2026-03-20
+
+### Added
+- **Log Hub consume pattern**: New `consume` parameter on `aidex_log` query — returned entries are removed from the buffer, ideal for polling without duplicates
+- **Viewer: Clear Logs button**: "Clear" button in the Logs tab to reset the log display
+- **Viewer: WebSocket auto-reconnect**: Viewer automatically reconnects when WebSocket connection drops (2s retry)
+- **LogHub Developer Guide**: Added comprehensive integration guide to project CLAUDE.md with code examples for C#, Python, JavaScript, C/C++, PowerShell
+
+### Fixed
+- **Log entry `data: null` display**: Entries with `data: null` no longer show "null" text in Viewer and MCP output
+
 ## [1.16.0] - 2026-03-20
 
 ### Added

MCP-API-REFERENCE.md

@@ -910,6 +910,7 @@ Universal log receiver — any program (C#, Python, Node, etc.) can send logs vi
 | `source` | string | - | Filter by source name (query) |
 | `contains` | string | - | Filter by message substring (query) |
 | `limit` | number | - | Max entries to return (default: `50`, used with query) |
+| `consume` | boolean | - | If true, returned entries are removed from buffer — ideal for polling without duplicates (default: `false`, used with query) |
 | `message` | string | for write | Log message text |
 | `data` | string | - | Optional JSON data (write) |
 
@@ -920,7 +921,7 @@ Universal log receiver — any program (C#, Python, Node, etc.) can send logs vi
 | `init` | Start HTTP server and ring buffer. Optional: `persist` + `path` for SQLite storage |
 | `free` | Stop server, free all resources, release port |
 | `status` | Show stats: entries, buffer usage, sources, level counts, port |
-| `query` | Search logs with filters (since, level, source, contains, limit). Newest first |
+| `query` | Search logs with filters (since, level, source, contains, limit, consume). Newest first |
 | `clear` | Clear the ring buffer (keep server running) |
 | `write` | Inject a log entry as source "claude" |
 
@@ -948,6 +949,9 @@ Body limit: 64KB. CORS enabled. Levels: `debug`, `info`, `warn`, `error`.
 // Query by source
 { "action": "query", "source": "MyApp", "contains": "connection" }
 
+// Poll and consume (entries removed from buffer after reading)
+{ "action": "query", "consume": true }
+
 // LLM writes a log entry
 { "action": "write", "level": "info", "message": "Starting debug session" }
 

README.md

@@ -67,7 +67,7 @@ aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", prio
 
 ## Table of Contents
 
-- [What's Inside](#whats-inside--29-tools-in-one-server)
+- [What's Inside](#whats-inside--30-tools-in-one-server)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Why Not Just Grep?](#why-not-just-grep)
@@ -82,6 +82,7 @@ aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", prio
 - [Task Backlog](#task-backlog)
 - [Global Search](#global-search)
 - [AI Guidelines](#ai-guidelines)
+- [Log Hub](#log-hub--universal-logging)
 - [Screenshots — LLM-Optimized](#screenshots--llm-optimized)
 - [Interactive Viewer](#interactive-viewer)
 - [CLI Usage](#cli-usage)
@@ -563,6 +564,70 @@ aidex_global_guideline({ action: "delete", key: "old-rule" })          # Remove
 
 Guidelines are stored in `~/.aidex/global.db` — available across all your projects without `aidex_init`. Ask your AI: *"Load the review guideline and apply it to this file."*
 
+## Log Hub — Universal Logging
+
+Turn any program into a log source for your AI assistant. Your app sends logs via HTTP POST, the AI queries them via MCP, and you see them live in the Viewer — zero dependencies, zero setup in your code.
+
+### How it works
+
+```
+Your Program ──HTTP POST──→ AiDex Log Hub (port 3335) ──→ Ring Buffer
+                                        │                      │
+                                        │ WebSocket             │ MCP query
+                                        ↓                      ↓
+                                   Viewer (Logs tab)      AI Assistant
+                                   (you see live)       (queries & analyzes)
+```
+
+### Quick start
+
+1. AI starts the Log Hub: `aidex_log({ action: "init" })`
+2. AI opens the Viewer: `aidex_viewer({ path: "." })` — Logs tab shows live stream
+3. Add one line to your program:
+
+```csharp
+// C#
+await new HttpClient().PostAsJsonAsync("http://localhost:3335/log",
+    new { level = "info", source = "MyApp", message = "Player spawned", data = new { x = 10, y = 20 } });
+```
+
+```python
+# Python
+requests.post("http://localhost:3335/log", json={"level": "info", "source": "MyApp", "message": "Done"})
+```
+
+```javascript
+// JavaScript
+fetch("http://localhost:3335/log", {
+    method: "POST", headers: {"Content-Type": "application/json"},
+    body: JSON.stringify({level: "info", source: "MyApp", message: "Started"})
+});
+```
+
+```powershell
+# PowerShell
+Invoke-RestMethod -Uri http://localhost:3335/log -Method POST -ContentType "application/json" -Body '{"level":"info","source":"Script","message":"Done"}'
+```
+
+### HTTP API
+
+| Endpoint | Method | Body | Description |
+|----------|--------|------|-------------|
+| `/log` | POST | `{ level, source, message, data? }` | Single log entry |
+| `/logs` | POST | `[{ ... }, ...]` | Batch (multiple at once) |
+| `/health` | GET | — | Status + buffer usage |
+
+**Fields:** `level` (`debug`/`info`/`warn`/`error`), `source` (app name), `message` (text, required), `data` (optional JSON), `timestamp` (optional, ms)
+
+### Features
+
+- **Ring Buffer**: Fixed-size in-memory FIFO (default 10,000 entries) — oldest entries overwritten
+- **Zero-cost**: No server, no buffer, no resources until `init` is called
+- **Persistence**: Optional SQLite storage with 7-day auto-cleanup (`persist: true`)
+- **Consume pattern**: `query` with `consume: true` removes returned entries — ideal for polling
+- **Viewer integration**: Logs tab with WebSocket live-stream, level/source/text filters, auto-scroll
+- **Fire & forget**: Just POST and go — if the server isn't running, the POST silently fails
+
 ## Screenshots — LLM-Optimized
 
 Take screenshots and **reduce them up to 95%** for LLM context. A typical screenshot goes from ~100 KB to ~5 KB — that's thousands of tokens saved per image.
@@ -633,6 +698,8 @@ Opens `http://localhost:3333` with:
 - **File signatures** - Click any file to see its types and methods
 - **Live reload** - Changes detected automatically while you code
 - **Git status icons** - See which files are modified, staged, or untracked
+- **Logs tab** - Live log stream from Log Hub with filters (level, source, text search)
+- **Tasks tab** - View and manage your task backlog
 
 ![AiDex Viewer - Signatures](docs/aidex-viewer.png)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidex-mcp",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "mcpName": "io.github.CSCSoftware/aidex",
   "description": "MCP Server for persistent code indexing. Gives AI assistants (Claude, Gemini, Copilot, Cursor) instant access to your codebase. 50x less context than grep.",
   "main": "build/index.js",

src/commands/log.ts

@@ -99,6 +99,7 @@ export async function log(params: LogParams): Promise<LogResult> {
                 source: params.source,
                 contains: params.contains,
                 limit: params.limit ?? 50,
+                consume: params.consume ?? false,
             });
 
             return { success: true, action, entries };

src/loghub/log-buffer.ts

@@ -53,9 +53,11 @@ export class LogBuffer {
         source?: string;
         contains?: string;
         limit?: number;
+        consume?: boolean;
     }): LogEntry[] {
         const limit = opts?.limit ?? 50;
         const results: LogEntry[] = [];
+        const matchedIndices: number[] = [];
 
         // Iterate backwards from most recent
         for (let i = 0; i < this.count && results.length < limit; i++) {
@@ -70,6 +72,16 @@ export class LogBuffer {
             if (opts?.contains && !entry.message.toLowerCase().includes(opts.contains.toLowerCase())) continue;
 
             results.push(entry);
+            if (opts?.consume) matchedIndices.push(idx);
+        }
+
+        // Remove consumed entries from buffer
+        if (opts?.consume && matchedIndices.length > 0) {
+            for (const idx of matchedIndices) {
+                this.buffer[idx] = null;
+            }
+            this.count -= matchedIndices.length;
+            if (this.count < 0) this.count = 0;
         }
 
         return results;

src/loghub/log-types.ts

@@ -37,6 +37,7 @@ export interface LogParams {
     source?: string;
     contains?: string;
     limit?: number;
+    consume?: boolean;      // If true, returned entries are removed from the buffer (poll pattern)
     // write
     message?: string;
     data?: string;

src/server/tools.ts

@@ -803,6 +803,10 @@ export function registerTools(): Tool[] {
                         type: 'number',
                         description: 'Max entries to return (default: 50, used with query)',
                     },
+                    consume: {
+                        type: 'boolean',
+                        description: 'If true, returned entries are removed from the buffer — ideal for polling without duplicates (default: false, used with query)',
+                    },
                     message: {
                         type: 'string',
                         description: 'Log message text (required for write)',
@@ -2516,6 +2520,7 @@ async function handleLog(args: Record<string, unknown>): Promise<{ content: Arra
         source: args.source as string | undefined,
         contains: args.contains as string | undefined,
         limit: args.limit as number | undefined,
+        consume: args.consume as boolean | undefined,
         message: args.message as string | undefined,
         data: args.data as string | undefined,
     });
@@ -2574,7 +2579,7 @@ async function handleLog(args: Record<string, unknown>): Promise<{ content: Arra
                 const time = new Date(e.timestamp).toISOString().slice(11, 23);
                 const icon = levelIcon[e.level] || '';
                 msg += `${icon} \`${time}\` **[${e.source}]** ${e.message}`;
-                if (e.data) msg += ` \`${e.data}\``;
+                if (e.data && e.data !== 'null') msg += ` \`${e.data}\``;
                 msg += '\n';
             }
             return { content: [{ type: 'text', text: msg.trimEnd() }] };