flynn/README.md

# 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