A complete solution for running a Claude AI assistant in Nextcloud Talk:
- Nextcloud App (
claudebot/) — Permission management UI and API - Bot Service (
bot/) — Python daemon that connects Nextcloud Talk to Claude Code CLI
User (Talk) → NC Talk API → Bot Service → Claude Code CLI
↑ ↓
Permission ← NC App API (check)
- Users send messages (text, voice, or files) in any Nextcloud Talk conversation with the bot
- The bot service polls for new messages via long-polling (one thread per room)
- Before responding, it checks the permission API (provided by the NC app)
- Voice messages are transcribed locally using faster-whisper (GPU accelerated)
- Files (images, PDFs, etc.) are downloaded and passed to Claude for analysis
- If allowed, the message is forwarded to Claude Code CLI
- The response is sent back to the Talk conversation
The app provides an admin UI and REST API for managing who can use the bot.
- User permissions — Allow individual users
- Group permissions — Allow entire groups
- Admin UI — Settings → Administration → Claude Bot
- Autocomplete — Search users/groups with Nextcloud's built-in autocomplete
- Nextcloud 28 — 32
- PHP 8.0+
From the App Store: Search for "Claude Bot" in your Nextcloud app management.
Manual:
tar xzf claudebot-*.tar.gz -C /path/to/nextcloud/apps/
occ app:enable claudebotThe bot username defaults to bot-claude. Change it with:
occ config:app:set claudebot bot_user --value="your-bot-user"The Python bot runs on any server with Claude Code CLI installed.
- Python 3.9+
- Claude Code CLI (
claude) installed and authenticated - Network access to your Nextcloud instance
- Optional: faster-whisper + NVIDIA GPU for voice message transcription
- Create a Nextcloud user for the bot (e.g.
bot-claude) - Copy config:
cd bot/ cp config.example.json config.json - Edit
config.jsonwith your Nextcloud URL, bot credentials, and preferences - Install the NC app and add yourself to the allowed users
- Run the bot:
python3 claude_bot.py
| Key | Default | Description |
|---|---|---|
nextcloud.base_url |
— | Your Nextcloud URL |
nextcloud.username |
— | Bot user's username |
nextcloud.password |
— | Bot user's app password |
claude.model |
sonnet |
Default Claude model (sonnet/opus/haiku) |
claude.max_response_length |
3500 |
Max response length before truncation |
claude.working_directory |
$HOME |
Working directory for Claude CLI |
claude.max_turns |
0 |
Max agentic turns (0 = unlimited) |
permission_cache_ttl |
300 |
Permission cache TTL in seconds |
admin_users |
[] |
Users who see extended /status info |
Users can send these commands in any Talk conversation with the bot:
| Command | Description |
|---|---|
/clear |
Start a new Claude session |
/stop |
Cancel a running request |
/model [name] |
Show/change model (sonnet, opus, haiku) |
/effort [level] |
Set response quality (low, medium, high, max) |
/cost |
Show token usage and costs for current session |
/compact [focus] |
Compress session context |
/status |
Show session info |
/help |
Show available commands |
- 1:1 chats: Bot responds to all messages
- Groups with only bot + 1 user: Bot responds to all messages
- Groups with multiple users: Bot responds only to @mentions or /commands
- Voice messages: Automatically transcribed and forwarded to Claude
- File attachments: Downloaded and passed to Claude for analysis (images, PDFs, etc.)
- Message queue: Messages sent while Claude is busy are queued and processed in order
sudo cp claude-bot.service.example /etc/systemd/system/claude-bot.service
# Edit the service file with your paths and username
sudo systemctl enable --now claude-bot.serviceAll endpoints use OCS and require the header OCS-APIRequest: true.
GET /ocs/v2.php/apps/claudebot/api/v1/check/{userId}
→ {"ocs": {"data": {"allowed": true, "reason": "user"}}}
GET /ocs/v2.php/apps/claudebot/api/v1/permissions
POST /ocs/v2.php/apps/claudebot/api/v1/permissions
{"type": "user"|"group", "target": "name"}
DELETE /ocs/v2.php/apps/claudebot/api/v1/permissions/{id}
AGPL-3.0-or-later — see LICENSE