Your AIr friends custom chatbot with integrated shell and skills. Powered by ACP AI agents, it remembers conversations across channels while keeping your data organized in isolated workspaces.
- 🤖 Multi-Platform: Currently works on Discord and Misskey
- 🧠 Persistent Memory: Remembers conversations across different channels
- 🗜️ Memory Maintenance: Optional scheduled agent task to summarize and compact old memories
- ⏰ Scheduled Reminders: Users can set one-time reminders via DM, delivered at the specified time
- 📝 Agent Knowledge Base: Personal workspace for long-term knowledge notes and reflections
- 🔒 Privacy First: Isolated workspaces per user with access control
- 💾 Git Backup: Automatic versioned backup of memories and notes to GitHub
- 🐳 Easy Deploy: One-command container deployment
- 🎨 Customizable: Template-based personality prompt system
- 🔌 Extensible: Skill-based architecture with external skill auto-installation
The recommended way to run AIr-Friends is by using containers:
-
Prepare .env file
# Download example file wget https://raw.githubusercontent.com/jim60105/AIr-Friends/master/.env.example -O .env # Edit with your credentials vim .env
-
Run with Podman (or Docker)
podman run -d --rm \ -v data:/app/data \ --env-file .env \ --name air-friends \ ghcr.io/jim60105/air-friends:latest
-
Or use Compose
wget https://raw.githubusercontent.com/jim60105/AIr-Friends/master/compose.yml podman compose up -d
That's it! Your bot should now be online.
Change the personality of your bot!
Override individual character prompt files — only the files you mount will be replaced; others keep their container defaults.
With Compose (recommended — see compose.yml):
volumes:
- data:/app/data:Z
# Mount only the prompt files you want to override
- ./prompts/character_name.md:/app/prompts/character_name.md:ro,Z
- ./prompts/character_info.md:/app/prompts/character_info.md:ro,Z
- ./prompts/character_personality.md:/app/prompts/character_personality.md:ro,Z
- ./prompts/character_speaking_style.md:/app/prompts/character_speaking_style.md:ro,Z
- ./prompts/character_reference_terms.md:/app/prompts/character_reference_terms.md:ro,ZWith Podman/Docker run:
podman run -d --rm \
-v data:/app/data \
-v ./prompts/character_name.md:/app/prompts/character_name.md:ro \
-v ./prompts/character_info.md:/app/prompts/character_info.md:ro \
--env-file .env \
--name air-friends \
ghcr.io/jim60105/air-friends:latestWith Helm (see helm/ chart):
# values.yaml
prompts:
enabled: true
files:
character_name.md: |
Yuna
character_info.md: |
An AI assistantSee Development Guide -- Customizing the Bot section for details.
Control who can interact with your bot using the channels-based reply policy:
replyPolicy: "channels" # Options: all, public, channels
channels:
- id: "discord/account/123456789012345678"
enabled: true
spontaneousPost: false
channelLurk: false
rateLimitBypass: true
yolo: true
- id: "misskey/account/abcdef1234567890"
enabled: true
spontaneousPost: false
channelLurk: false
rateLimitBypass: false
yolo: false
- id: "discord/channel/873618490202931231"
enabled: true
spontaneousPost: true
channelLurk: true
yolo: falseSee Development Guide -- Access Control & Reply Policy section for details.
Prevent excessive API usage per user with configurable rate limiting:
rateLimit:
enabled: false
maxRequestsPerWindow: 10
windowMs: 600000 # 10-minute sliding window
cooldownMs: 600000 # Cooldown after limit exceededAllow users to set one-time reminders via DM. The bot delivers them at the scheduled time:
reminders:
enabled: false
maxRemindersPerUser: 20 # Max active reminders per user
minIntervalMs: 60000 # Minimum delay from now (1 minute)
checkIntervalMs: 30000 # How often to check for due reminders- DM-only: Reminders can only be set and are delivered in direct messages
- One-time: Each reminder fires exactly once (no recurring support)
- Restart-safe: Overdue reminders are picked up automatically after bot restart
- Skills:
set-reminder,cancel-reminder,list-reminders
Dynamically select LLM models per user or context to control costs and quality:
agent:
model: "gpt-5-mini" # default fallback
modelRouting:
enabled: true
rules:
- match: { channel: "discord/account/12345678901234567" }
model: "openrouter/deepseek/deepseek-v3.2"
- match: { sessionType: "spontaneous" }
model: "openrouter/deepseek/deepseek-v3.2"Rules are evaluated in order (first-match wins). See Development Guide -- Model Routing for details.
AIr-Friends acts as an ACP (Agent Client Protocol) client, delegating AI reasoning to external agents while maintaining persistent memory:
┌─────────────────────────────────────────┐
│ Platform (Discord/Misskey) │
│ ↓ │
│ AIr-Friends (ACP Client) │
│ ↓ │
│ External AI Agent │
│ (Copilot/Gemini/OpenCode) │
│ ↓ │
│ Skills & Memory System │
└─────────────────────────────────────────┘
See Design Document for detailed architecture.
The official container image includes:
- Pre-installed AI agent binaries (Copilot CLI, Gemini CLI, OpenCode CLI)
- Auto-approval mode enabled for isolated execution
- Health check endpoint on port 8080
- Default prompts at
/app/prompts(can be overridden)
See Development Guide for complete setup instructions.
GNU GENERAL PUBLIC LICENSE Version 3
Copyright (C) 2026 Jim Chen [email protected].
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.