William Valentin
68 lines
4.1 KiB
Markdown
68 lines
4.1 KiB
Markdown
# 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.
|