# Flynn AGENTS.md

## Build, Lint, and Test Commands

```bash
# Build
pnpm build                    # Compile TypeScript to dist/

# Development
pnpm dev                      # Run daemon with watch mode
pnpm tui                      # Run TUI in minimal mode (readline)
pnpm tui:fs                   # Run TUI in fullscreen mode (React/Ink)
pnpm tui:dev                  # Run TUI with watch mode

# Run
pnpm start                    # Start production build

# Testing
pnpm test                     # Run tests in watch mode
pnpm test:run                 # Run tests once (no watch)

# Linting and Type Checking
pnpm lint                     # Run ESLint
pnpm typecheck                # Run TypeScript compiler (no emit)
```

## Code Style Guidelines

### Imports

- Use `.js` extensions for imports (e.g., `import { readFileSync } from 'fs';`)
- Use `type` keyword for type-only imports: `import type { Config } from './schema.js';`
- Group imports: stdlib → third-party → local
- Export all public APIs from `index.ts`

### Naming Conventions

- **Classes/Interfaces/Types**: PascalCase (`AnthropicClient`, `NativeAgentConfig`)
- **Functions**: camelCase (`loadConfig`, `expandEnvVars`)
- **Private fields**: camelCase with underscore (`_client`, `_model`)
- **Files**: camelCase for .ts files, PascalCase for .tsx files
- **Test files**: `*.test.ts` suffix

### TypeScript Configuration

- `tsconfig.json` uses strict mode
- Target: ES2022
- Module resolution: NodeNext
- Module format: NodeNext
- Enables `declaration`, `declarationMap`, and `sourceMap` for all builds

### Error Handling

- Throw errors with descriptive messages
- Check for undefined/null with context: `throw new Error('Environment variable ${envVar} is not set')`
- In stream handlers, wrap errors in try-catch and yield error events
- Use `instanceof Error` for error type checking: `error instanceof Error ? error.message : 'Unknown error'`
- Catch errors and convert to appropriate error types with context

### React/Ink Patterns

- Use `useCallback` for event handlers to prevent unnecessary re-renders
- Use `useRef` for mutable values that don't trigger re-renders
- Define interface props explicitly
- Event handlers receive `(inputChar: string, key: KeyInfo)` as arguments

### Project Structure

```
src/
├── config/          # YAML config + validation
├── models/          # Model providers + router
├── session/         # SQLite persistence
├── hooks/           # Confirmation engine
├── daemon/          # Lifecycle management
├── frontends/       # Telegram bot, TUI
└── backends/native/ # Agent implementation
```

## Testing

- Use Vitest for testing
- Follow `describe`/`it` pattern
- Use `expect()` for assertions
- Test both success and failure cases
- Clean up test resources (files, dirs) in `afterEach` or `it` cleanup blocks
- Mock file system and environment variables when needed