# Codebase Structure **Analysis Date:** 2025-02-09 ## Directory Layout ``` flynn/ ├── src/ # All TypeScript source code │ ├── agents/ # Named agent configs + routing │ ├── auth/ # GitHub device flow auth │ ├── automation/ # Cron, webhooks, heartbeat, Gmail │ ├── backends/ # AI agent implementations │ │ └── native/ # NativeAgent + AgentOrchestrator │ ├── channels/ # Multi-platform messaging adapters │ │ ├── discord/ # Discord adapter │ │ ├── slack/ # Slack adapter │ │ ├── telegram/ # Telegram adapter │ │ ├── webchat/ # WebChat adapter (wraps gateway) │ │ └── whatsapp/ # WhatsApp adapter │ ├── cli/ # CLI commands (commander.js) │ ├── config/ # YAML config loading + Zod schema │ ├── context/ # Token estimation + compaction │ ├── daemon/ # Daemon bootstrap + lifecycle │ ├── frontends/ # UI frontends │ │ ├── telegram/ # Telegram bot (legacy direct integration) │ │ └── tui/ # Terminal UI (readline + React/Ink) │ │ └── components/ # Ink React components │ ├── gateway/ # WebSocket JSON-RPC server │ │ ├── handlers/ # JSON-RPC method handlers │ │ └── ui/ # Vanilla JS dashboard │ │ ├── lib/ # Shared JS (ws-client) │ │ └── pages/ # Page JS (chat, dashboard, sessions, settings, usage) │ ├── hooks/ # Tool confirmation engine │ ├── mcp/ # Model Context Protocol bridge │ ├── memory/ # Persistent memory + vector search │ ├── models/ # LLM provider clients + router │ │ └── local/ # Ollama + llama.cpp clients │ ├── prompt/ # System prompt template assembly │ ├── sandbox/ # Docker sandbox for tool execution │ ├── session/ # SQLite session persistence │ ├── skills/ # Pluggable skill system │ └── tools/ # Tool registry, executor, policy │ └── builtin/ # Built-in tool implementations │ ├── browser/ # Puppeteer browser tools │ └── process/ # Background process tools ├── config/ # Example/default config files ├── docs/ # Documentation │ └── plans/ # Planning docs ├── .planning/ # GSD planning documents │ └── codebase/ # Codebase analysis (this file) ├── AGENTS.md # Agent instructions for Claude Code ├── CHANGELOG.md # Version changelog ├── CLAUDE.md # Claude Code shared memory ├── SOUL.md # Flynn's AI personality/identity ├── Dockerfile # Docker build config ├── docker-compose.yml # Docker Compose config ├── package.json # Node.js package manifest ├── tsconfig.json # TypeScript configuration └── pnpm-lock.yaml # Lockfile ``` ## Directory Purposes **`src/agents/`:** - Purpose: Named agent configurations and routing logic - Contains: `AgentConfigRegistry` (stores named configs), `AgentRouter` (resolves channel+sender → agent config) - Key files: `src/agents/registry.ts`, `src/agents/router.ts` **`src/auth/`:** - Purpose: GitHub device flow authentication for GitHub Models provider - Contains: OAuth device flow implementation - Key files: `src/auth/github.ts` **`src/automation/`:** - Purpose: Scheduled jobs, incoming webhooks, health monitoring, Gmail watching - Contains: CronScheduler (croner-based), WebhookHandler (HMAC auth), HeartbeatMonitor, GmailWatcher - Key files: `src/automation/cron.ts`, `src/automation/webhooks.ts`, `src/automation/heartbeat.ts`, `src/automation/gmail.ts` **`src/backends/native/`:** - Purpose: Core AI agent implementation — message processing and tool execution loop - Contains: `NativeAgent` (tool loop), `AgentOrchestrator` (delegation/compaction/memory wrapper), prompt templates - Key files: `src/backends/native/agent.ts`, `src/backends/native/orchestrator.ts`, `src/backends/native/prompts.ts`, `src/backends/native/attachments.ts` **`src/channels/`:** - Purpose: Platform-agnostic messaging layer with uniform adapter interface - Contains: `ChannelAdapter` interface, `ChannelRegistry`, per-platform adapter directories, `PairingManager` - Key files: `src/channels/types.ts`, `src/channels/registry.ts`, `src/channels/pairing.ts`, `src/channels/utils.ts` **`src/cli/`:** - Purpose: CLI command definitions and entry point - Contains: Commander.js command registrations, config loading helpers - Key files: `src/cli/index.ts` (entry point), `src/cli/start.ts`, `src/cli/tui.ts`, `src/cli/send.ts`, `src/cli/sessions.ts`, `src/cli/doctor.ts`, `src/cli/config-cmd.ts`, `src/cli/completion.ts`, `src/cli/shared.ts` **`src/config/`:** - Purpose: Configuration loading and validation - Contains: YAML loader with `${ENV_VAR}` expansion, comprehensive Zod schema - Key files: `src/config/schema.ts` (all config types), `src/config/loader.ts` (YAML parse + validate) **`src/context/`:** - Purpose: Conversation context management — token counting and history compaction - Contains: Token estimator (rule-based, no tokenizer), compaction logic using delegation - Key files: `src/context/tokens.ts`, `src/context/compaction.ts` **`src/daemon/`:** - Purpose: Daemon bootstrap — wires all subsystems together and manages lifecycle - Contains: `startDaemon()` function (1088 lines), `Lifecycle` manager, model client factory, message router - Key files: `src/daemon/index.ts` (main orchestration), `src/daemon/lifecycle.ts` **`src/frontends/telegram/`:** - Purpose: Legacy direct Telegram bot integration with confirmation UI - Contains: Bot handlers, confirmation keyboard management - Key files: `src/frontends/telegram/bot.ts`, `src/frontends/telegram/handlers.ts`, `src/frontends/telegram/confirmations.ts` **`src/frontends/tui/`:** - Purpose: Terminal user interface with two modes - Contains: Minimal readline TUI, fullscreen React/Ink TUI, markdown rendering, slash commands - Key files: `src/frontends/tui/minimal.ts`, `src/frontends/tui/fullscreen.ts`, `src/frontends/tui/commands.ts`, `src/frontends/tui/markdown.ts` **`src/gateway/`:** - Purpose: WebSocket JSON-RPC server + HTTP server + dashboard - Contains: `GatewayServer`, `Router` (method dispatch), `SessionBridge` (WS → NativeAgent), `LaneQueue` (request serialization), auth, protocol, static file serving, Tailscale Serve integration - Key files: `src/gateway/server.ts`, `src/gateway/router.ts`, `src/gateway/session-bridge.ts`, `src/gateway/lane-queue.ts`, `src/gateway/protocol.ts`, `src/gateway/auth.ts`, `src/gateway/static.ts`, `src/gateway/tailscale.ts` **`src/gateway/handlers/`:** - Purpose: JSON-RPC method handler implementations - Contains: Handler factories for system, session, tool, agent, config, and pairing methods - Key files: `src/gateway/handlers/system.ts`, `src/gateway/handlers/sessions.ts`, `src/gateway/handlers/agent.ts`, `src/gateway/handlers/tools.ts`, `src/gateway/handlers/config.ts`, `src/gateway/handlers/pairing.ts` **`src/gateway/ui/`:** - Purpose: Vanilla JS web dashboard served by gateway HTTP server - Contains: HTML pages, CSS, client-side JavaScript - Key files: `src/gateway/ui/index.html`, `src/gateway/ui/chat.html`, `src/gateway/ui/style.css`, `src/gateway/ui/app.js`, `src/gateway/ui/lib/ws-client.js` **`src/hooks/`:** - Purpose: Tool execution confirmation engine with glob-pattern matching - Contains: `HookEngine` with pending confirmation queue - Key files: `src/hooks/engine.ts` **`src/mcp/`:** - Purpose: Model Context Protocol integration — start external MCP servers and bridge their tools - Contains: `McpClient`, `McpManager`, tool bridging utilities - Key files: `src/mcp/client.ts`, `src/mcp/manager.ts`, `src/mcp/bridge.ts` **`src/memory/`:** - Purpose: Persistent memory system with keyword + vector hybrid search - Contains: `MemoryStore` (namespace-based markdown files), `VectorStore` (SQLite), `HybridSearch`, embedding providers, text chunker - Key files: `src/memory/store.ts`, `src/memory/vector-store.ts`, `src/memory/hybrid-search.ts`, `src/memory/embeddings.ts`, `src/memory/chunker.ts` **`src/models/`:** - Purpose: LLM provider client implementations and tier-based routing - Contains: Provider clients, `ModelRouter`, retry logic, cost estimation, media helpers - Key files: `src/models/types.ts` (core interfaces), `src/models/router.ts`, `src/models/anthropic.ts`, `src/models/openai.ts`, `src/models/gemini.ts`, `src/models/bedrock.ts`, `src/models/github.ts`, `src/models/retry.ts`, `src/models/costs.ts`, `src/models/media.ts`, `src/models/capabilities.ts` **`src/models/local/`:** - Purpose: Local model provider clients - Contains: Ollama and llama.cpp client implementations - Key files: `src/models/local/ollama.ts`, `src/models/local/llamacpp.ts` **`src/prompt/`:** - Purpose: System prompt assembly from template files - Contains: Template search across directories (SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md) - Key files: `src/prompt/template.ts` **`src/sandbox/`:** - Purpose: Docker container isolation for shell/process tool execution - Contains: `DockerSandbox` (container lifecycle), `SandboxManager` (per-session containers), sandboxed tool wrappers - Key files: `src/sandbox/docker.ts`, `src/sandbox/manager.ts`, `src/sandbox/tools.ts` **`src/session/`:** - Purpose: Conversation history persistence - Contains: `SessionStore` (SQLite), `SessionManager` (in-memory cache), `ManagedSession` - Key files: `src/session/store.ts`, `src/session/manager.ts` **`src/skills/`:** - Purpose: Pluggable skill system — load skills from bundled, managed, and workspace directories - Contains: `SkillRegistry`, `SkillInstaller`, skill loader, skill type definitions - Key files: `src/skills/registry.ts`, `src/skills/installer.ts`, `src/skills/loader.ts`, `src/skills/types.ts` **`src/tools/`:** - Purpose: Tool abstraction layer — registry, execution, policy enforcement - Contains: `ToolRegistry`, `ToolExecutor`, `ToolPolicy`, type definitions - Key files: `src/tools/types.ts`, `src/tools/registry.ts`, `src/tools/executor.ts`, `src/tools/policy.ts` **`src/tools/builtin/`:** - Purpose: Built-in tool implementations shipped with Flynn - Contains: Shell exec, file operations, web fetch, memory ops, web search, media send, image analysis, session management, agent listing, cross-channel messaging, cron management - Key files: `src/tools/builtin/shell.ts`, `src/tools/builtin/file-read.ts`, `src/tools/builtin/file-write.ts`, `src/tools/builtin/file-edit.ts`, `src/tools/builtin/file-patch.ts`, `src/tools/builtin/file-list.ts`, `src/tools/builtin/web-fetch.ts`, `src/tools/builtin/web-search.ts`, `src/tools/builtin/memory-read.ts`, `src/tools/builtin/memory-write.ts`, `src/tools/builtin/memory-search.ts`, `src/tools/builtin/media-send.ts`, `src/tools/builtin/image-analyze.ts`, `src/tools/builtin/audio-transcribe.ts`, `src/tools/builtin/system-info.ts`, `src/tools/builtin/sessions.ts`, `src/tools/builtin/agents-list.ts`, `src/tools/builtin/message-send.ts`, `src/tools/builtin/cron.ts` **`src/tools/builtin/browser/`:** - Purpose: Puppeteer-based browser automation tools - Contains: `BrowserManager` (page lifecycle), browser tool implementations (navigate, screenshot, click, type, content, eval) - Key files: `src/tools/builtin/browser/manager.ts`, `src/tools/builtin/browser/tools.ts` **`src/tools/builtin/process/`:** - Purpose: Background process management tools - Contains: `ProcessManager`, tools for start/status/output/kill/list - Key files: `src/tools/builtin/process/manager.ts`, `src/tools/builtin/process/start.ts`, `src/tools/builtin/process/status.ts`, `src/tools/builtin/process/output.ts`, `src/tools/builtin/process/kill.ts`, `src/tools/builtin/process/list.ts` ## Key File Locations **Entry Points:** - `src/cli/index.ts`: CLI entry point (binary: `flynn`) - `src/daemon/index.ts`: Daemon bootstrap (`startDaemon()`) — the central wiring point - `src/gateway/server.ts`: Gateway WebSocket + HTTP server - `src/frontends/tui/minimal.ts`: TUI readline mode - `src/frontends/tui/fullscreen.ts`: TUI fullscreen Ink mode **Configuration:** - `src/config/schema.ts`: Complete Zod config schema — all types defined here - `src/config/loader.ts`: YAML parse + env expansion + Zod validation - `tsconfig.json`: TypeScript compiler config (strict, ES2022, NodeNext) - `package.json`: Dependencies and scripts - `config/`: Example/default config files directory **Core Logic:** - `src/backends/native/agent.ts`: NativeAgent — the AI tool loop - `src/backends/native/orchestrator.ts`: AgentOrchestrator — delegation, compaction, memory - `src/models/router.ts`: ModelRouter — tier-based model selection with fallback - `src/tools/executor.ts`: ToolExecutor — policy check → hook check → execute - `src/channels/registry.ts`: ChannelRegistry — adapter lifecycle + message routing - `src/daemon/index.ts`: startDaemon() — wires everything together **Testing:** - Test files are co-located with source: `src/path/to/file.test.ts` alongside `src/path/to/file.ts` - No separate test directory ## Naming Conventions **Files:** - Source files: `camelCase.ts` (e.g., `session-bridge.ts`, `lane-queue.ts`) — actually `kebab-case.ts` - React components: `camelCase.ts` in `src/frontends/tui/components/` - Test files: `*.test.ts` suffix (e.g., `agent.test.ts`, `registry.test.ts`) - Index files: `index.ts` barrel exports in every directory - Type-only files: `types.ts` for pure type definitions **Directories:** - Feature-based: `kebab-case/` (e.g., `web-search`, `file-read`) - Platform subdirs: `lowercase/` (e.g., `telegram/`, `discord/`, `slack/`) - Nested features: `parent/child/` (e.g., `tools/builtin/browser/`) **Exports:** - Every directory has an `index.ts` barrel file that re-exports public APIs - Types use `export type` for type-only exports - Registration chain flows: implementation → `builtin/index.ts` → `tools/index.ts` → `daemon/index.ts` ## Where to Add New Code **New Channel Adapter:** - Create directory: `src/channels//` - Create: `adapter.ts` (implements `ChannelAdapter`), `index.ts` (re-exports) - Add test: `adapter.test.ts` - Register in: `src/channels/index.ts` (export), `src/daemon/index.ts` (instantiate + register) - Add config: `src/config/schema.ts` (new optional schema block) **New Model Provider:** - Create: `src/models/.ts` (implements `ModelClient`) - Add export: `src/models/index.ts` - Add case: `src/daemon/index.ts` → `createClientFromConfig()` switch statement - Add config: `src/config/schema.ts` → `modelConfigBaseSchema.provider` enum **New Tool:** - Static tool (no deps): Create `src/tools/builtin/.ts`, export const - Factory tool (needs deps): Create `src/tools/builtin/.ts`, export function - Add to: `src/tools/builtin/index.ts` (export + add to `allBuiltinTools` if static) - Add to: `src/tools/index.ts` (re-export) - Register in: `src/daemon/index.ts` (call factory + register with `toolRegistry`) - Add to profiles: `src/tools/policy.ts` → `PROFILE_TOOLS` if needed **New Tool Group (multi-tool):** - Create directory: `src/tools/builtin//` - Create: `manager.ts` (shared state), individual tool files, `index.ts` - Follow pattern of `src/tools/builtin/process/` or `src/tools/builtin/browser/` **New Gateway Handler:** - Create: `src/gateway/handlers/.ts` (export `createXxxHandlers()`) - Add to: `src/gateway/handlers/index.ts` - Register in: `src/gateway/server.ts` → `registerHandlers()` **New Automation Type:** - Create: `src/automation/.ts` - If it produces messages: implement `ChannelAdapter` interface - Add to: `src/automation/index.ts` - Register in: `src/daemon/index.ts` - Add config: `src/config/schema.ts` → `automationSchema` **New CLI Command:** - Create: `src/cli/.ts` → export `registerXxxCommand(program)` - Register in: `src/cli/index.ts` **Utilities:** - Shared helpers: Place in the most specific layer that uses them - Cross-cutting: `src/channels/utils.ts` for channel utils, `src/models/media.ts` for media utils - No global `utils/` directory — utilities are co-located with their domain ## Special Directories **`dist/`:** - Purpose: Compiled JavaScript output - Generated: Yes (by `pnpm build` / `tsc`) - Committed: No (in `.gitignore`) **`node_modules/`:** - Purpose: Installed dependencies - Generated: Yes (by `pnpm install`) - Committed: No (in `.gitignore`) **`config/`:** - Purpose: Example/default configuration files - Generated: No - Committed: Yes **`src/gateway/ui/`:** - Purpose: Static web dashboard (vanilla HTML/CSS/JS, not compiled) - Generated: No — hand-written vanilla JS - Committed: Yes - Note: Served by the gateway HTTP server at runtime from `dist/gateway/ui/` **`.planning/`:** - Purpose: GSD planning and analysis documents - Generated: By analysis tools - Committed: Yes **`docs/plans/`:** - Purpose: Feature planning documents and state tracking - Generated: No - Committed: Yes --- *Structure analysis: 2025-02-09*