| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 16 | 6 | 0% |
| Commands | 0 | 10 | 1 | 0% |
| Section tags | 6 | 4 | 2 | 50% |
What each file covers
Sections
0 shared · 16 only in A · 6 only in B- − CLAUDE.md
- − Overview
- − Commands
- − Running a Single Test
- − Test Environments
- − Architecture
- − Stack
- − Key Directories
- − Text Generation Flow
- − Model Context Protocol (MCP)
- − LLM Router (Omni)
- − Database Collections
- − Environment Setup
- − MONGODB_URL is optional; omit for in-memory DB persisted to ./db
- − Code Conventions
- − Feature Development Checklist
- + V3 Module Development
- + Build & Test
- + From v3/@claude-flow/<package>
- + Packages
- + Code Quality
- + Performance Targets
Commands
0 shared · 10 only in A · 1 only in B- − npm run dev
- − npm run build
- − npm run preview
- − npm run check
- − npm run lint
- − npm run format
- − npm run test
- − npx vitest run path/to/file.spec.ts
- − npx vitest run -t "test name"
- − npx vitest --watch path/to/file.spec.ts
- + npm install && npm run build && npm test
Section tags
6 shared · 4 only in A · 2 only in B- − lint-format
- − code-style
- − types
- − database
- + testing-strategy
- + dependencies
- setup
- build
- test
- architecture
- performance
- agent-behaviour
Line diff
ruvnet/ruflo · ruflo/src/ruvocal/CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Overview
6
7Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.
8
9## Commands
10
11```bash
12npm run dev # Start dev server on localhost:5173
13npm run build # Production build
14npm run preview # Preview production build
15npm run check # TypeScript validation (svelte-kit sync + svelte-check)
16npm run lint # Check formatting (Prettier) and linting (ESLint)
17npm run format # Auto-format with Prettier
18npm run test # Run all tests (Vitest)
19```
20
21### Running a Single Test
22
23```bash
24npx vitest run path/to/file.spec.ts # Run specific test file
25npx vitest run -t "test name" # Run test by name
26npx vitest --watch path/to/file.spec.ts # Watch mode for single file
27```
28
29### Test Environments
30
31Tests are split into three workspaces (configured in vite.config.ts):
32
33- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright
34- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering
35- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities
36
37## Architecture
38
39### Stack
40
41- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)
42- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)
43- **TailwindCSS** for styling
44
45### Key Directories
46
47```
48src/
49├── lib/
50│ ├── components/ # Svelte components (chat/, mcp/, voice/, icons/)
51│ ├── server/
52│ │ ├── api/utils/ # Shared API helpers (auth, superjson, model/conversation resolvers)
53│ │ ├── textGeneration/ # LLM streaming pipeline
54│ │ ├── mcp/ # Model Context Protocol integration
55│ │ ├── router/ # Smart model routing (Omni)
56│ │ ├── database.ts # MongoDB collections
57│ │ ├── models.ts # Model registry from OPENAI_BASE_URL/models
58│ │ └── auth.ts # OpenID Connect authentication
59│ ├── types/ # TypeScript interfaces (Conversation, Message, User, Model, etc.)
60│ ├── stores/ # Svelte stores for reactive state
61│ └── utils/ # Helpers (tree/, marked.ts, auth.ts, etc.)
62├── routes/ # SvelteKit file-based routing
63│ ├── conversation/[id]/ # Chat page + streaming endpoint
64│ ├── settings/ # User settings pages
65│ ├── api/ # Legacy v1 API endpoints (mcp, transcribe, fetch-url)
66│ ├── api/v2/ # REST API endpoints (+server.ts)
67│ └── r/[id]/ # Shared conversation view
68```
69
70### Text Generation Flow
71
721. User sends message via `POST /conversation/[id]`
732. Server validates user, fetches conversation history
743. Builds message tree structure (see `src/lib/utils/tree/`)
754. Calls LLM endpoint via OpenAI client
765. Streams response back, stores in MongoDB
77
78### Model Context Protocol (MCP)
79
80MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.
81
82### LLM Router (Omni)
83
84Smart routing via Arch-Router model. Configured with:
85
86- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes
87- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint
88- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`
89
90### Database Collections
91
92- `conversations` - Chat sessions with nested messages
93- `users` - User accounts (OIDC-backed)
94- `sessions` - Session data
95- `sharedConversations` - Public share links
96- `settings` - User preferences
97
98## Environment Setup
99
100Copy `.env` to `.env.local` and configure:
101
102```env
103OPENAI_BASE_URL=https://router.huggingface.co/v1
104OPENAI_API_KEY=hf_***
105# MONGODB_URL is optional; omit for in-memory DB persisted to ./db
106```
107
108See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.
109
110## Code Conventions
111
112- TypeScript strict mode enabled
113- ESLint: no `any`, no non-null assertions
114- Prettier: tabs, 100 char width, Tailwind class sorting
115- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)
116
117## Feature Development Checklist
118
119When building new features, consider:
120
1211. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`
1222. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`
1233. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options
1244. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars
1255. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons
1266. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs
127
ruvnet/ruflo · v3/CLAUDE.md
@@ +1 @@
1# V3 Module Development
2
3This directory contains the V3 monorepo packages. Root CLAUDE.md rules apply here.
4
5## Build & Test
6
7```bash
8# From v3/@claude-flow/<package>
9npm install && npm run build && npm test
10```
11
12## Packages
13
14| Package | Path | Purpose |
15|---------|------|---------|
16| `@claude-flow/cli` | `@claude-flow/cli/` | CLI entry point (26 commands, 140+ subcommands) |
17| `@claude-flow/guidance` | `@claude-flow/guidance/` | Governance control plane (compile, enforce, prove, evolve) |
18| `@claude-flow/hooks` | `@claude-flow/hooks/` | 17 hooks + 12 background workers |
19| `@claude-flow/memory` | `@claude-flow/memory/` | AgentDB + HNSW vector search |
20| `@claude-flow/shared` | `@claude-flow/shared/` | Shared types and utilities |
21| `@claude-flow/security` | `@claude-flow/security/` | Input validation, path security, CVE remediation |
22
23## Code Quality
24
25- Files under 500 lines
26- No hardcoded secrets
27- Input validation at system boundaries
28- Typed interfaces for all public APIs
29- TDD London School (mock-first) preferred
30- Event sourcing for state changes
31
32## Performance Targets
33
34> Source of truth: [`docs/reviews/intelligence-system-audit-2026-05-29.md`](../docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](../scripts/benchmark-intelligence.mjs). Numbers below are measured unless marked "target/unverified".
35
36| Metric | Measured / Target | Status |
37|--------|-------------------|--------|
38| HNSW Search | ~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99) | **Measured** (ruvector NAPI; 150x-12,500x NOT reproduced) |
39| Int8 Quantization | 3.84x compression, reconstruction cosine 0.99999 | **Measured** |
40| RaBitQ Quantization | 32x compression, 0.60ms/query | **Measured** |
41| SONA Adaptation | 0.0043ms/adapt (target <0.05ms met) | **Measured** |
42| MCP Response | <100ms | target |
43| CLI Startup | <500ms | target |
44| Flash Attention | integration available; measured speedup pending benchmark | **Not measured** — prior "2.49x–7.47x" figure was inherited from upstream marketing, never reproduced in-tree; dropped to avoid a credibility claim we can't verify |
45
@@ −1 +1 @@
1−# CLAUDE.md
1+# V3 Module Development
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+This directory contains the V3 monorepo packages. Root CLAUDE.md rules apply here.
44
5−## Overview
5+## Build & Test
66
7−Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.
8−
9−## Commands
10−
117 ```bash
12−npm run dev # Start dev server on localhost:5173
13−npm run build # Production build
14−npm run preview # Preview production build
15−npm run check # TypeScript validation (svelte-kit sync + svelte-check)
16−npm run lint # Check formatting (Prettier) and linting (ESLint)
17−npm run format # Auto-format with Prettier
18−npm run test # Run all tests (Vitest)
8+# From v3/@claude-flow/<package>
9+npm install && npm run build && npm test
1910 ```
2011
21−### Running a Single Test
12+## Packages
2213
23−```bash
24−npx vitest run path/to/file.spec.ts # Run specific test file
25−npx vitest run -t "test name" # Run test by name
26−npx vitest --watch path/to/file.spec.ts # Watch mode for single file
27−```
14+| Package | Path | Purpose |
15+|---------|------|---------|
16+| `@claude-flow/cli` | `@claude-flow/cli/` | CLI entry point (26 commands, 140+ subcommands) |
17+| `@claude-flow/guidance` | `@claude-flow/guidance/` | Governance control plane (compile, enforce, prove, evolve) |
18+| `@claude-flow/hooks` | `@claude-flow/hooks/` | 17 hooks + 12 background workers |
19+| `@claude-flow/memory` | `@claude-flow/memory/` | AgentDB + HNSW vector search |
20+| `@claude-flow/shared` | `@claude-flow/shared/` | Shared types and utilities |
21+| `@claude-flow/security` | `@claude-flow/security/` | Input validation, path security, CVE remediation |
2822
29−### Test Environments
23+## Code Quality
3024
31−Tests are split into three workspaces (configured in vite.config.ts):
25+- Files under 500 lines
26+- No hardcoded secrets
27+- Input validation at system boundaries
28+- Typed interfaces for all public APIs
29+- TDD London School (mock-first) preferred
30+- Event sourcing for state changes
3231
33−- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright
34−- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering
35−- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities
32+## Performance Targets
3633
37−## Architecture
34+> Source of truth: [`docs/reviews/intelligence-system-audit-2026-05-29.md`](../docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](../scripts/benchmark-intelligence.mjs). Numbers below are measured unless marked "target/unverified".
3835
39−### Stack
40−
41−- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)
42−- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)
43−- **TailwindCSS** for styling
44−
45−### Key Directories
46−
47−```
48−src/
49−├── lib/
50−│ ├── components/ # Svelte components (chat/, mcp/, voice/, icons/)
51−│ ├── server/
52−│ │ ├── api/utils/ # Shared API helpers (auth, superjson, model/conversation resolvers)
53−│ │ ├── textGeneration/ # LLM streaming pipeline
54−│ │ ├── mcp/ # Model Context Protocol integration
55−│ │ ├── router/ # Smart model routing (Omni)
56−│ │ ├── database.ts # MongoDB collections
57−│ │ ├── models.ts # Model registry from OPENAI_BASE_URL/models
58−│ │ └── auth.ts # OpenID Connect authentication
59−│ ├── types/ # TypeScript interfaces (Conversation, Message, User, Model, etc.)
60−│ ├── stores/ # Svelte stores for reactive state
61−│ └── utils/ # Helpers (tree/, marked.ts, auth.ts, etc.)
62−├── routes/ # SvelteKit file-based routing
63−│ ├── conversation/[id]/ # Chat page + streaming endpoint
64−│ ├── settings/ # User settings pages
65−│ ├── api/ # Legacy v1 API endpoints (mcp, transcribe, fetch-url)
66−│ ├── api/v2/ # REST API endpoints (+server.ts)
67−│ └── r/[id]/ # Shared conversation view
68−```
69−
70−### Text Generation Flow
71−
72−1. User sends message via `POST /conversation/[id]`
73−2. Server validates user, fetches conversation history
74−3. Builds message tree structure (see `src/lib/utils/tree/`)
75−4. Calls LLM endpoint via OpenAI client
76−5. Streams response back, stores in MongoDB
77−
78−### Model Context Protocol (MCP)
79−
80−MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.
81−
82−### LLM Router (Omni)
83−
84−Smart routing via Arch-Router model. Configured with:
85−
86−- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes
87−- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint
88−- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`
89−
90−### Database Collections
91−
92−- `conversations` - Chat sessions with nested messages
93−- `users` - User accounts (OIDC-backed)
94−- `sessions` - Session data
95−- `sharedConversations` - Public share links
96−- `settings` - User preferences
97−
98−## Environment Setup
99−
100−Copy `.env` to `.env.local` and configure:
101−
102−```env
103−OPENAI_BASE_URL=https://router.huggingface.co/v1
104−OPENAI_API_KEY=hf_***
105−# MONGODB_URL is optional; omit for in-memory DB persisted to ./db
106−```
107−
108−See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.
109−
110−## Code Conventions
111−
112−- TypeScript strict mode enabled
113−- ESLint: no `any`, no non-null assertions
114−- Prettier: tabs, 100 char width, Tailwind class sorting
115−- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)
116−
117−## Feature Development Checklist
118−
119−When building new features, consider:
120−
121−1. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`
122−2. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`
123−3. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options
124−4. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars
125−5. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons
126−6. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs
36+| Metric | Measured / Target | Status |
37+|--------|-------------------|--------|
38+| HNSW Search | ~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99) | **Measured** (ruvector NAPI; 150x-12,500x NOT reproduced) |
39+| Int8 Quantization | 3.84x compression, reconstruction cosine 0.99999 | **Measured** |
40+| RaBitQ Quantization | 32x compression, 0.60ms/query | **Measured** |
41+| SONA Adaptation | 0.0043ms/adapt (target <0.05ms met) | **Measured** |
42+| MCP Response | <100ms | target |
43+| CLI Startup | <500ms | target |
44+| Flash Attention | integration available; measured speedup pending benchmark | **Not measured** — prior "2.49x–7.47x" figure was inherited from upstream marketing, never reproduced in-tree; dropped to avoid a credibility claim we can't verify |
12745
