docs: add README and AGENTS.md documentation
This commit is contained in:
William Valentin
@@ -0,0 +1,87 @@
|
|||||||
|
# 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
|
||||||
@@ -0,0 +1,205 @@
|
|||||||
|
# Flynn
|
||||||
|
|
||||||
|
Self-hosted personal AI assistant with Telegram and Terminal interfaces.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Multi-Frontend**: Telegram bot + Terminal UI (minimal & fullscreen modes)
|
||||||
|
- **Multi-Model**: Anthropic Claude, OpenAI, Ollama with intelligent routing
|
||||||
|
- **Model Switching**: Switch between cloud/local models on demand
|
||||||
|
- **Session Persistence**: SQLite-backed conversation history
|
||||||
|
- **Fallback Chains**: Automatic failover when primary model fails
|
||||||
|
- **Hook Engine**: Confirmation system for sensitive operations
|
||||||
|
- **Session Transfer**: Move conversations between frontends
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Copy and configure
|
||||||
|
cp config/default.yaml ~/.config/flynn/config.yaml
|
||||||
|
# Edit config with your API keys and Telegram bot token
|
||||||
|
|
||||||
|
# Build and run
|
||||||
|
pnpm build
|
||||||
|
pnpm start
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Config location: `~/.config/flynn/config.yaml` (or set `FLYNN_CONFIG`)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
telegram:
|
||||||
|
bot_token: "your-telegram-bot-token"
|
||||||
|
allowed_chat_ids: [123456789] # Your Telegram user ID
|
||||||
|
|
||||||
|
models:
|
||||||
|
default:
|
||||||
|
provider: anthropic
|
||||||
|
model: claude-opus-4-5-20251101
|
||||||
|
api_key: sk-ant-api03-...
|
||||||
|
local:
|
||||||
|
provider: ollama
|
||||||
|
model: qwen2.5:14b
|
||||||
|
fallback_chain: [local]
|
||||||
|
|
||||||
|
hooks:
|
||||||
|
confirm: [shell.*, file.write]
|
||||||
|
log: [web.*, file.read]
|
||||||
|
silent: [notify]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Model Providers
|
||||||
|
|
||||||
|
| Provider | Config |
|
||||||
|
|----------|--------|
|
||||||
|
| Anthropic | `provider: anthropic`, `api_key` or `auth_token` |
|
||||||
|
| OpenAI | `provider: openai`, `api_key`, optional `endpoint` |
|
||||||
|
| Ollama | `provider: ollama`, `model`, optional `endpoint` |
|
||||||
|
|
||||||
|
### Model Tiers
|
||||||
|
|
||||||
|
Configure multiple models for different purposes:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
models:
|
||||||
|
fast: { provider: anthropic, model: claude-sonnet-4-... }
|
||||||
|
default: { provider: anthropic, model: claude-opus-4-5-... }
|
||||||
|
complex: { provider: anthropic, model: claude-opus-4-5-... }
|
||||||
|
local: { provider: ollama, model: qwen2.5:14b }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Telegram Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/start` | Initialize bot |
|
||||||
|
| `/reset` | Clear conversation history |
|
||||||
|
| `/status` | Show current model and status |
|
||||||
|
| `/local` | Switch to local model |
|
||||||
|
| `/cloud` | Switch to cloud model |
|
||||||
|
| `/model` | Show model info and options |
|
||||||
|
|
||||||
|
## Terminal UI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Minimal mode (readline)
|
||||||
|
pnpm tui
|
||||||
|
|
||||||
|
# Fullscreen mode (React/Ink)
|
||||||
|
pnpm tui:fs
|
||||||
|
```
|
||||||
|
|
||||||
|
### TUI Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/help` | Show help |
|
||||||
|
| `/reset` | Clear history |
|
||||||
|
| `/status` | Show session info |
|
||||||
|
| `/fullscreen` | Switch to fullscreen mode |
|
||||||
|
| `/transfer telegram` | Transfer session to Telegram |
|
||||||
|
| `/quit` | Exit |
|
||||||
|
|
||||||
|
## Running as Service
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create systemd user service
|
||||||
|
mkdir -p ~/.config/systemd/user
|
||||||
|
|
||||||
|
cat > ~/.config/systemd/user/flynn.service << 'EOF'
|
||||||
|
[Unit]
|
||||||
|
Description=Flynn Personal AI Assistant
|
||||||
|
After=network.target ollama.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
WorkingDirectory=/path/to/flynn
|
||||||
|
ExecStart=/usr/bin/pnpm start
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5
|
||||||
|
Environment=NODE_ENV=production
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Enable and start
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user enable --now flynn
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
journalctl --user -u flynn -f
|
||||||
|
```
|
||||||
|
|
||||||
|
## Hook Engine
|
||||||
|
|
||||||
|
Control sensitive operations with pattern matching:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hooks:
|
||||||
|
confirm: # Requires user approval via Telegram
|
||||||
|
- shell.*
|
||||||
|
- file.write
|
||||||
|
log: # Logs but doesn't block
|
||||||
|
- web.*
|
||||||
|
- file.read
|
||||||
|
silent: # Executes without notification
|
||||||
|
- notify
|
||||||
|
```
|
||||||
|
|
||||||
|
## Session Management
|
||||||
|
|
||||||
|
- Sessions persist in `~/.local/share/flynn/sessions.db`
|
||||||
|
- Session ID format: `{frontend}:{userId}` (e.g., `telegram:123456789`)
|
||||||
|
- History survives restarts
|
||||||
|
- Transfer sessions between frontends with `/transfer`
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── index.ts # Daemon entry
|
||||||
|
├── tui.ts # TUI entry
|
||||||
|
├── config/ # YAML config + validation
|
||||||
|
├── models/ # Model providers + router
|
||||||
|
├── backends/native/ # Agent implementation
|
||||||
|
├── session/ # SQLite persistence
|
||||||
|
├── hooks/ # Confirmation engine
|
||||||
|
├── daemon/ # Lifecycle management
|
||||||
|
└── frontends/
|
||||||
|
├── telegram/ # Telegram bot
|
||||||
|
└── tui/ # Terminal UI
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Dev mode with watch
|
||||||
|
pnpm dev # Daemon
|
||||||
|
pnpm tui:dev # TUI
|
||||||
|
|
||||||
|
# Type check
|
||||||
|
pnpm typecheck
|
||||||
|
|
||||||
|
# Lint
|
||||||
|
pnpm lint
|
||||||
|
|
||||||
|
# Test
|
||||||
|
pnpm test
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
| Variable | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| `FLYNN_CONFIG` | Override config path |
|
||||||
|
| `ANTHROPIC_API_KEY` | Anthropic API key (fallback) |
|
||||||
|
| `OPENAI_API_KEY` | OpenAI API key (fallback) |
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
Reference in New Issue
Block a user