Finna - Multi-Channel AI Assistant Platform

Your AI assistant, everywhere you work.

Finna is a multi-channel AI assistant platform built on the Claude Agent SDK. It connects to your favorite messaging platforms (WhatsApp, Telegram, Slack, Discord, and more) while supporting both single-user local deployments and multi-tenant team setups.

Inspired by Clawdbot, Finna takes it further with enterprise-ready features: team workspaces, PostgreSQL storage, SSO, and audit logging.

Highlights

• Claude Agent SDK - Official Anthropic SDK for reliable, future-proof agent capabilities
• Multi-Channel Inbox - WhatsApp, Telegram, Slack, Discord, Signal, and more
• Flexible Storage - File-based (local), SQLite (middle ground), PostgreSQL (teams)
• Multi-Tenant Ready - Team workspaces with role-based access control
• WebSocket Gateway - Real-time control plane with Hono + Bun
• Tool Ecosystem - Extensible tools with JSON Schema definitions
• Self-Hostable - Run on your infrastructure, own your data

Quick Start

Prerequisites: Bun 1.1+, pnpm 10+

# Clone the repository
git clone https://github.com/your-org/finna-agent.git
cd finna-agent

# Install dependencies
pnpm install

# Start the gateway
bun run --filter gateway dev

# In another terminal, start chatting
bun run --filter cli chat

Installation

Single User (Local)

# Install globally
pnpm add -g finna@latest

# Run the onboarding wizard
finna onboard

# Start the gateway
finna gateway run

Team Deployment (PostgreSQL)

# Set up your database
export DATABASE_URL="postgres://user:pass@host:5432/finna"

# Run migrations
finna db migrate

# Start with multi-tenant mode
finna gateway run --mode team

Docker

docker run -d \
  -p 51004:51004 \
  -v ~/.finna:/data \
  ghcr.io/your-org/finna:latest

How It Works

WhatsApp / Telegram / Slack / Discord / Signal / Web
               │
               ▼
┌────────────────────────────────────┐
│             Gateway                │
│        (Hono + Bun WebSocket)      │
│       ws://127.0.0.1:51004         │
└──────────────┬─────────────────────┘
               │
               ├─ Claude Agent SDK
               ├─ Storage (File/SQLite/PostgreSQL)
               ├─ CLI (finna ...)
               ├─ Web Dashboard
               └─ Channel Adapters

Project Structure

finna-agent/
├── apps/
│   ├── gateway/        # Bun + Hono WebSocket server
│   ├── web/            # TanStack Start dashboard
│   └── cli/            # CLI application
├── packages/
│   ├── core/           # Shared core logic + storage
│   ├── channels/       # Channel adapters
│   ├── tools/          # Tool implementations
│   └── sdk/            # Public SDK for integrations
├── specs/              # Specification documents
└── docs/               # Documentation

Storage Modes

Mode	Storage	Users	Best For
Local	File (JSONL)	1	Personal use
Desktop	SQLite	1	Single user with search
Team	PostgreSQL	Many	Teams and enterprise

Local Storage (Default)

~/.finna/
├── config.json
├── agents/
│   └── main/
│       └── sessions/     # JSONL transcripts
└── media/

Team Storage (PostgreSQL)

DATABASE_URL=postgres://user:pass@host:5432/finna

Channels

Finna supports multiple messaging channels through adapters:

Channel	Status	Notes
WebChat	Planned	Built-in web interface
Telegram	Planned	grammY integration
WhatsApp	Planned	Baileys integration
Slack	Planned	Bolt integration
Discord	Planned	discord.js integration
Signal	Planned	signal-cli integration

Configuration

// ~/.finna/config.json
{
  "gateway": {
    "port": 51004,
    "bind": "loopback"
  },
  "storage": {
    "driver": "file",  // or "sqlite", "postgres"
    "path": "~/.finna"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "BOT_TOKEN"
    }
  }
}

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Claude API key
FINNA_CONFIG_PATH	Config file location
FINNA_GATEWAY_TOKEN	Gateway auth token
DATABASE_URL	PostgreSQL connection string

Development

# Install dependencies
pnpm install

# Development (with watch)
bun run dev

# Build all packages
bun run build

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Type check
bun run typecheck

# Lint
bun run lint

Tech Stack

• Runtime: Bun 1.1+ (primary), Node.js (compatibility)
• Language: TypeScript 5.4+ (ESM, strict mode)
• Gateway: Hono + Bun WebSocket
• Dashboard: TanStack Start + shadcn/ui
• Design System: "Warm Precision" (terracotta + golden amber)
• Database: Drizzle ORM
• Validation: TypeBox (JSON Schema)
• Build: Turbo (monorepo), pnpm workspaces
• Testing: Bun test (TDD approach)

Comparison with Clawdbot

Feature	Clawdbot	Finna
Agent Core	Custom loop	Claude Agent SDK
Storage	File only	File/SQLite/PostgreSQL
Users	Single user	Single + Multi-tenant
Channels	12+ channels	Growing (same patterns)
Dashboard	Lit-based	TanStack Start
License	MIT	MIT

Finna adopts many proven patterns from Clawdbot while extending them for team use cases.

Roadmap

• Phase 1: Foundation - Monorepo, storage abstraction, gateway skeleton
• Phase 2: Agent Integration - Claude SDK, conversation management
• Phase 3: Channels - Telegram, WhatsApp, Slack adapters
• Phase 4: Dashboard - TanStack Start web interface
• Phase 5: Tools - Browser control, file operations, custom tools
• Phase 6: Enterprise - SSO, audit logging, team management

Contributing

Contributions welcome! Please read the contributing guide before submitting PRs.

# Fork and clone
git clone https://github.com/your-username/finna-agent.git

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and test
bun test

# Submit a PR

Security

• Never commit API keys or tokens
• Use environment variables for secrets
• Report vulnerabilities responsibly

License

MIT License - see LICENSE for details.

Acknowledgments

• Clawdbot - Inspiration and patterns (MIT licensed)
• Claude Agent SDK - Agent capabilities
• Hono - Web framework
• TanStack Start - Full-stack React framework
• shadcn/ui - UI components
• Bun - JavaScript runtime

---

Built with the Claude Agent SDK