CLAUDE.md - Turtlez

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Turtlez (RLM-JS) - An NPM-based implementation of the Recursive Language Model (RLM) pattern. It implements a system where context grows with each conversation turn and is stored externally in a SQLite-backed context store. The root LLM never receives full context in its prompt but accesses it through a sandboxed REPL environment with bounded outputs and controlled sub-agent calls.

The project is evolving into an Agentic Coding Environment with infinite context capabilities.

CRITICAL: Runtime Selection

DO NOT use bun run dev - Bun v1.3.x doesn't support better-sqlite3 native bindings.

✅ Correct Commands

cd rlm-chat

# Development - use Node.js (not Bun!)
npx next dev --port 3000

# Testing
npm run test          # Vitest with Node.js (native modules work)
npm rebuild better-sqlite3  # Rebuild if native bindings fail

# Building
npm run build         # Production build

❌ Don't Do This

bun run dev           # FAILS - Bun doesn't support better-sqlite3
bun run test          # FAILS - Native module incompatibility

Why This Matters

• better-sqlite3 requires native C++ bindings compiled for Node's V8
• Bun uses a different JavaScript engine and doesn't support these bindings
• See: https://github.com/oven-sh/bun/issues/4290

#initial test commands run npm rebuild better-sqlite3 before testing wwith vitest

Type Safety Rules

• Never use "any" or "unknown" types
• Always reuse types from other files
• If you have to create a new type, make sure it is reusable and robust and organized in a way that it can be used in multiple files

Using skills

You have access to reusable skills: packaged workflows, tools, or scripts you can call to handle repeatable, multi‑step, or high‑risk tasks.

• Always check which skills are available and read their descriptions before attempting complex or procedural work. Prefer calling a skill over improvising when a skill clearly matches the user’s request.
• Use skills for operations that need reliability or side effects (e.g., running scripts, updating resources, calling external APIs) and keep free‑form reasoning for analysis, planning, and explanation around those calls.
• When a user request could be handled by multiple skills, choose the one whose name, description, and constraints best match the task, and explain briefly which skill you are using and why.
• If no existing skill fits, fall back to regular reasoning, but explicitly note that no registered skill was appropriate for the request.

TypeScript Types Configuration

The tsconfig.json uses an explicit types array to prevent TypeScript from auto-discovering transitive @types/ packages:

"types": ["node", "react", "react-dom", "better-sqlite3"]

Why: Without this, TypeScript finds partial type stubs in transitive dependencies that reference other @types/ packages not installed, causing dozens of "Cannot find type definition file" errors.

Adding new types: If you add a dependency that needs types, add it to the types array in tsconfig.json. Do NOT install dozens of @types/* packages for transitive dependencies.

Cross-Platform Development (Windows/WSL)

This project is developed across Windows (PowerShell) and WSL. This causes occasional issues:

Package Installation

• Prefer bun install over npm install - it handles cross-platform better and is faster
• If npm fails with EPERM or esbuild version errors, delete node_modules and use bun
• From Windows: rmdir /s /q node_modules && bun install
• From WSL: rm -rf node_modules && bun install

Running TypeScript from WSL

Bun creates .exe binaries, so from WSL use node directly:

node node_modules/typescript/lib/tsc.js --noEmit

Repository Structure

This is a monorepo with the main application in rlm-chat/:

rlm/
├── rlm-chat/           # Main Next.js application
│   ├── src/
│   │   ├── app/        # Next.js App Router (layout.tsx, page.tsx)
│   │   └── lib/        # Core library
│   │       ├── agent/      # Agent prompts, tools, parsing
│   │       ├── db/         # Context store, migrations (SQLite)
│   │       ├── indexing/   # Term-based indexing service
│   │       ├── llm/        # LLM provider abstraction (OpenRouter)
│   │       ├── runtime/    # Tool runtime, budget management
│   │       └── search/     # Search scoring algorithms
│   └── specs/          # Feature specifications
├── .kiro/specs/        # Requirements and design documents
└── .claude/            # Claude Code skills and commands

Commands

All commands run from the rlm-chat/ directory:

cd rlm-chat

npm run dev           # Start development server (localhost:3000)
npm run build         # Production build
npm run lint          # ESLint
npm run test          # Run Vitest tests
npm run test:watch    # Vitest watch mode
npm run test:coverage # Tests with coverage
npx vitest run        # Alternative: run tests directly
bun test              # Fast test runner (no native modules)

# TypeScript check (from WSL when using bun-installed node_modules)
node node_modules/typescript/lib/tsc.js --noEmit

Tech Stack

• Next.js 16.1.4 (App Router)
• React 19
• TypeScript 5 (strict mode)
• Tailwind CSS 4
• better-sqlite3 for database
• Vitest for testing
• ESLint 9 with next/core-web-vitals

Key Concepts

Context Store

• Append-only SQLite storage for conversation context
• Entry types: doc_chunk, turn_user, turn_assistant, summary, index_v1, system_meta
• Entries are immutable except for meta.supersededBy field

RLM Loop

The root agent executes: request REPL operations → call sub-agents on chunks → return FINAL(...). It only receives metadata and tool descriptions, never raw context in prompts.

Budget System

• maxSubcallsTotal=40, maxIterations=8, maxRuntimeMs=90000
• maxInputCharsSubcall=200000, maxOutputCharsSubcall=4000

Level 1 Indexing

• Simple tokenization: lowercase, split on non-alphanumeric, drop stopwords
• Index snapshots created every 10 turns
• Search scoring: +3 exact match, +2 multiple terms, recency bonus

Path Alias

@/* maps to ./src/* (e.g., import { ContextStore } from '@/lib/db/context-store')

Code Conventions

• Files: kebab-case (context-store.ts)
• Classes/Interfaces: PascalCase (ContextStore, ContextEntry)
• Tests: Co-located as *.test.ts or *.spec.ts

Required Patterns (from Phase 1 Review)

Singleton Pattern - Use Lazy Factory

// ✅ Correct - lazy initialization with factory
let _instance: MyClass | null = null;

export function getMyClass(config?: Config): MyClass {
    if (!_instance) {
        _instance = new MyClass(config);
    }
    return _instance;
}

export function resetMyClass(): void {
    _instance?.cleanup();
    _instance = null;
}

// ❌ Wrong - eager initialization breaks testing
export const myInstance = new MyClass();

Current usage: getContextStore() and resetContextStore() in src/lib/db/context-store.ts

Error Handling for External Data

All JSON.parse on stored/external data MUST have try/catch with fallback:

let data: MyType | null = null;
try {
    data = JSON.parse(storedText) as MyType;
    if (data.version !== 'expected') {
        console.warn('Unsupported version, falling back');
        data = null;
    }
} catch (error) {
    console.error('Failed to parse data:', error);
    data = null;
}
if (!data) return fallbackBehavior();

LRU Cache Eviction

Use LRU (Least Recently Used), never FIFO:

get(key: string): T | null {
    const value = this.cache.get(key);
    if (!value) return null;
    // LRU: Move to end by re-inserting
    this.cache.delete(key);
    this.cache.set(key, value);
    return value;
}

Current usage: SubcallCache in src/lib/llm/subcall-cache.ts

External API Clients

All HTTP clients MUST include:

• API key validation before requests (not at construction)
• Retry logic: 3 retries with exponential backoff (1s, 2s, 4s)
• Retryable status codes: 429, 500, 502, 503, 504

Current usage: OpenRouterClient in src/lib/llm/openrouter-client.ts

Testing Requirements

Before marking ANY task complete:

1. Unit tests exist for new code
2. Happy path AND error paths tested
3. Tests actually pass: npx vitest run

Specialized UI Agents

For browser-based UI testing, use the specialized agents in .gemini/agents/:

• playwright-test-planner: Use to explore the UI and design comprehensive test scenarios.
• playwright-test-generator: Use to automatically generate spec files from a test plan by watching real-time interactions.
• playwright-test-healer: Use to systematically debug and fix failing Playwright tests.

Environment Variables

Create .env.local at repository root:

OPENROUTER_API_KEY=sk-or-v1-...
DATABASE_URL=./data/rlm-chat.db  # optional

Specifications

Detailed requirements and design documents are in:

• .kiro/specs/rlm-chat-system/requirements.md - Full requirements
• .kiro/specs/rlm-chat-system/design.md - Architecture and data models
• .kiro/specs/rlm-chat-system/tasks.md - Implementation tasks with status

System Reviews

Post-implementation reviews are stored in:

• rlm-chat/.agents/system-reviews/ - Process improvement documentation