flynn/CLAUDE.md

CLAUDE.md

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

Commands

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.