Skip to content

Aaron-arn/kalon-ai

BranchesTags

Repository files navigation

Kalon - Personal Autonomous AI Assistant

Version: beta v2
License: MIT
Author: Aaron Dalibard
Repository: https://github.com/Aaron-arn/kalon-ai

Overview

Kalon is a self-hosted, autonomous personal AI assistant with 50+ built-in skills. It runs locally on your machine and supports multiple AI providers including OpenAI, Anthropic, Google, Meta, and many open-source models via OpenRouter, Groq, and NVIDIA NIM.

Key Features:

  • Multi-provider support (200+ AI models)
  • 50+ integrated skills (files, web, code, calendar, notes, images, deployment, crypto, etc.)
  • Fully self-hosted - your data stays on your machine
  • Terminal and web interfaces
  • Mobile access via tunnel
  • Channels integration (Telegram, Discord, WhatsApp, Slack, etc.)
  • Autonomous task execution with proactive suggestions

Installation

Windows

install.bat

Linux / macOS

chmod +x install.sh && ./install.sh

The installation scripts automatically install:

  • Python packages (requirements.txt)
  • Node.js (required for WhatsApp channel)
  • cloudflared (for remote access tunnel)
  • Whisper (local speech-to-text)
  • pyttsx3 / edge-tts (text-to-speech)

Quick Start

Terminal Mode

kalon

Web Interface

kalon --web
# Access at http://127.0.0.1:8080

Without Alias

python kalon.py
python kalon.py --web

Mobile Access

The local web interface is accessible from any device on your local network. For external access:

  1. Type /iwd in the Kalon terminal
  2. A Cloudflare tunnel will be created
  3. Scan the QR code with your phone

Supported AI Providers

Provider Models Free Tier
OpenRouter 200+ (Llama, Claude, GPT, Gemini) Yes
NVIDIA NIM Llama 3.1, Nemotron, Mistral, Gemma Yes
OpenAI gpt-4o, gpt-4o-mini, o1, o3 No
Anthropic claude-opus-4, claude-sonnet-4-5 No
Google gemini-2.5-pro, gemini-2.0-flash Yes
Mistral mistral-large, codestral No
Groq llama-3.3-70b, mixtral-8x7b Yes
Qwen AI qwen-plus, qwen-max Yes
Ollama (Local) llama3.3, qwen2.5, deepseek-r1 Yes (local)
Ollama Cloud Any Ollama model Yes
LM Studio Any local model Yes (local)
DeepSeek deepseek-chat, deepseek-reasoner No

Additional providers: xAI, Cohere, Together, Perplexity, Fireworks, and more.

Directory Structure

kalon/
├── kalon.py                    # Main entry point
├── kalon_web.html             # Web interface
├── install.bat / install.sh   # Installation scripts
├── package.bat                # Create distributable zip
├── core/
│   ├── engine.py              # AI engine + agentic loop
│   ├── terminal.py            # Terminal interface
│   ├── web_server.py          # Flask web server
│   ├── config.py              # Configuration management
│   ├── memory.py              # Persistent memory
│   ├── scheduler.py           # Task scheduler
│   ├── autonomy.py             # Proactive autonomous engine
│   ├── remote_access.py       # Cloudflare tunnel + sync
│   └── ...
├── skills/                    # 50+ skill modules
│   ├── file_ops.py            # File operations
│   ├── shell_ops.py           # Shell commands
│   ├── web_ops.py             # Web search & scraping
│   ├── browser_ops.py         # Playwright browser automation
│   ├── google_ops.py          # Google Drive/Gmail/Calendar
│   ├── agenda_ops.py          # Calendar management
│   ├── notes_ops.py           # Note-taking
│   ├── image_ops.py           # Image manipulation
│   ├── imagegen_ops.py        # AI image generation
│   ├── crypto_ops.py          # Cryptocurrency tracking
│   ├── deploy_ops.py          # Netlify/Vercel deployment
│   └── ...
├── channels/                  # Communication channels
│   ├── telegram_channel.py
│   ├── discord_channel.py
│   ├── whatsapp_channel.py
│   ├── slack_channel.py
│   └── ...
└── remote_frontend/
    └── index.html             # Optional remote UI

Core Features

Terminal Interface

  • Natural conversation with persistent memory
  • 50+ skills for files, web, code, calendar, notes, images, email
  • Multi-step autonomous agents
  • Task scheduler
  • /iwd command for instant mobile access

Web Interface (kalon --web)

  • Real-time SSE streaming chat
  • Multiple views: Dashboard, Notes, Calendar, Memory, Agents, Scheduler, Channels, Skills, Settings
  • Inline forms for creating notes and events
  • Think Mode: Off, Minimal, Medium, Deep
  • Provider and model selection in settings

Channels

  • Telegram
  • Discord
  • WhatsApp (Baileys - no Puppeteer required)
  • Slack
  • IRC
  • Matrix
  • Mattermost
  • SMS

Autonomy System

The autonomy engine provides proactive suggestions based on:

  • Time of day (morning routine, end of day)
  • Conversation context (detecting crypto, coding, email topics)
  • Learned patterns from previous interactions

Configuration

WhatsApp Setup

/channels
→ Select 3 (WhatsApp)
→ Configure
→ Choose "qr" method
→ Scan QR code with WhatsApp → Linked Devices
→ Session persists - no need to rescan

API Keys

Configure your AI provider API keys in the web interface settings or via environment variables:

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GOOGLE_API_KEY
  • MISTRAL_API_KEY
  • GROQ_API_KEY
  • NVIDIA_API_KEY
  • QWEN_API_KEY
  • etc.

Skills Reference

File Operations

  • file_read, file_write, file_delete, file_list
  • file_copy, file_move, file_search, file_replace
  • file_zip, file_unzip, file_verify

Web Operations

  • web_search (Google, Brave, Wikipedia, GitHub)
  • web_fetch, page_scroll, extract_data
  • summarize, compare, news, search_images

Code & Shell

  • shell, python, install, open_app
  • git operations (status, commit, push, pull, branch, diff)
  • sandbox execution

Media & Images

  • image_info, image_resize, image_convert
  • imagegen_generate (Pollinations, DALL-E, FLUX)
  • screenshot, screen_record

Data & APIs

  • csv_read, csv_write, json_read, json_write
  • xml_read, yaml_read
  • webhook_send, mcp_call

Productivity

  • notes (create, read, list, delete)
  • agenda (add, list, today)
  • schedule (add, list, remove)
  • timer, pomodoro, countdown

Integrations

  • Google Drive, Gmail, Calendar
  • Obsidian vault sync
  • GitHub issues
  • Home Assistant
  • MQTT
  • Stripe payments
  • Notion
  • Airtable

Crypto & Finance

  • crypto_price, crypto_market, crypto_watchlist
  • crypto_analyze, crypto_news

Security

  • cyber_hash, cyber_b64_encode/decode
  • cyber_password, cyber_strength
  • cyber_whois, cyber_dns, cyber_portscan

System Requirements

Required

  • Python 3.10+
  • One AI provider API key (OpenAI, Anthropic, Mistral, Groq, NVIDIA, Qwen, etc.)

Optional (auto-installed)

  • Node.js 18+ (for WhatsApp channel)
  • openai-whisper (local speech-to-text)
  • pyttsx3 / edge-tts (text-to-speech)
  • pyautogui + Pillow (screenshots)
  • cloudflared (remote tunnel)

Packaging

To create a clean distribution zip:

package.bat

This removes unnecessary files (pycache, .pyc, etc.) and creates a properly structured zip archive.

Troubleshooting

Common Issues

No response from AI:

  • Check API key is valid in settings
  • Try a different provider or model

Web interface not loading:

  • Port 8080 may be in use
  • Check firewall settings

WhatsApp not connecting:

  • Ensure Node.js 18+ is installed
  • Try regenerating QR code

Module import errors:

  • Run pip install -r requirements.txt
  • Check Python version (3.10+ required)

Contributing

Contributions are welcome. Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

License

MIT License - See LICENSE file for details.

If you use this code, please credit Aaron Dalibard / kalon-ai.

Support

About

Personal AI agent · Terminal-first · 17 providers · Autonomous agents · Cross-platform

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages