# CLAUDE.md

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

## Commands

```bash
pnpm build          # Compile TypeScript to dist/
pnpm dev            # Run daemon with watch mode (tsx watch)
pnpm start          # Start production build
pnpm tui            # Minimal TUI (readline)
pnpm tui:fs         # Fullscreen TUI (React/Ink)
pnpm test           # Run vitest in watch mode
pnpm test:run       # Run tests once (CI)
pnpm lint           # ESLint
pnpm typecheck      # TypeScript check (no emit)
```

Run a single test file: `pnpm test:run src/path/to/file.test.ts`

## Architecture

Flynn is a multi-channel AI assistant daemon. Messages flow: **Channel Adapter → AgentOrchestrator → NativeAgent → ModelClient**, with tools executed in the agent loop.

### Core Abstractions

**ModelClient** (`src/models/types.ts`): `chat(request): Promise<ChatResponse>`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu, xAI. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains.

**ChannelAdapter** (`src/channels/types.ts`): `connect()`, `disconnect()`, `send()`, `onMessage()`. Adapters: Telegram, Discord, Slack, WhatsApp, WebChat. Registered in `ChannelRegistry`, each channel+sender pair gets its own session.

**Tool** (`src/tools/types.ts`): `{ name, description, inputSchema, execute(args): Promise<ToolResult> }`. Three patterns:
- Static: `export const fooTool: Tool = { ... }` (no deps)
- Factory: `export function createFooTool(dep): Tool` (single tool needing deps)
- Multi-factory: `export function createFooTools(dep): Tool[]` (related tool set)

Registration chain: tool file → `src/tools/builtin/index.ts` → `src/tools/index.ts` → registered in `src/daemon/index.ts`.

**Tool Policy** (`src/tools/policy.ts`): Profiles (minimal/messaging/coding/full), groups (group:fs/runtime/web/memory), allow/deny with glob patterns.

**NativeAgent** (`src/backends/native/agent.ts`): Core agent loop with tool execution. **AgentOrchestrator** (`src/backends/native/orchestrator.ts`) wraps it with session management, compaction, memory extraction, and delegation to different model tiers.

### Other Key Systems

- **Config**: YAML + Zod validation (`src/config/schema.ts`). Supports `${ENV_VAR}` expansion.
- **Sessions**: SQLite via `SessionStore` (`src/session/store.ts`). TTL-based pruning.
- **Memory**: Namespace-based files + hybrid search (keyword + vector). Embedding providers configurable.
- **Hooks**: Pattern-based confirmation engine (`src/hooks/`). Actions: confirm/log/silent.
- **Sandbox**: Docker per-session containers (`src/sandbox/manager.ts`).
- **Automation**: Cron scheduler, webhooks (HMAC), heartbeat monitor, Gmail watcher (`src/automation/`).
- **Gateway**: WebSocket JSON-RPC + HTTP server + vanilla JS dashboard (`src/gateway/`). Lane queue for per-session request serialization. Gateway lock for single-client mode. Tailscale Serve integration.
- **Pairing**: DM pairing codes for unknown sender authentication (`src/channels/pairing.ts`). Gateway handlers + TUI `/pair` command.
- **System Prompt**: Template search for SOUL.md/AGENTS.md/IDENTITY.md/USER.md/TOOLS.md (`src/prompt/template.ts`).

## Code Conventions

- **ES Modules with `.js` extensions** in all imports (e.g., `import { foo } from './bar.js'`)
- **`type` keyword** for type-only imports: `import type { Config } from './schema.js'`
- **Import order**: stdlib → third-party → local
- **Naming**: PascalCase for types/classes, camelCase for functions/variables, `_prefix` for private fields
- **Files**: camelCase for `.ts`, PascalCase for `.tsx`
- **Tests**: co-located as `*.test.ts` next to source. Vitest with `describe`/`it`/`expect`.
- **Target**: ES2022, NodeNext modules, strict mode. Requires Node.js >=22.
- **Error pattern**: `instanceof Error` checks, descriptive messages, try-catch in stream handlers

## State Tracking

After implementing features, update `docs/plans/state.json` (test counts, progress, feature gap scorecard). Commit alongside the feature change.