docs: add README and AGENTS.md documentation
This commit is contained in:
William Valentin
@@ -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