managarten/services/matrix-chat-bot/CLAUDE.md

Matrix Chat Bot - Claude Code Guidelines

Overview

Matrix Chat Bot provides AI chat capabilities via Matrix chat. It integrates with the Chat backend for conversations, AI completions, and message history.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: Chat API (port 3002)
• Auth: Mana Core Auth (JWT)

Commands

# Development
pnpm install
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

Project Structure

services/matrix-chat-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3327)
│   ├── app.module.ts         # Root module
│   ├── health.controller.ts  # Health check endpoint
│   ├── config/
│   │   └── configuration.ts  # Configuration & help messages
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   ├── chat/
│   │   ├── chat.module.ts
│   │   └── chat.service.ts   # Chat Backend API client
│   └── session/
│       ├── session.module.ts
│       └── session.service.ts  # User session & auth management
├── Dockerfile
└── package.json

Bot Commands

Command	Aliases	Description
!help	hilfe	Show help message
!login email pass	-	Login
!logout	-	Logout
!status	-	Bot status

Quick Chat (Stateless)

Command	Aliases	Description
!chat [message]	fragen, ask	Quick AI response (no history)

Conversation Management

Command	Aliases	Description
!neu [titel]	new	Create new conversation
!gespraeche	conversations, liste	List all conversations
!gespraech [nr]	conversation, select	Select/view conversation
!senden [message]	send, s	Send message in current conversation
!verlauf	history, nachrichten	Show message history

Conversation Actions

Command	Aliases	Description
!titel [nr] [title]	title	Change conversation title
!archiv [nr]	archive	Archive conversation
!archiviert	archived	List archived conversations
!wiederherstellen [nr]	restore, unarchive	Restore from archive
!pin [nr]	-	Pin conversation
!unpin [nr]	-	Unpin conversation
!loeschen [nr]	delete	Delete conversation

Model Selection

Command	Aliases	Description
!modelle	models	List available AI models
!modell [nr]	model	Select model for new conversations

Model Providers

Provider	Icon	Description
ollama	🏠	Local models (self-hosted)
openrouter	☁️	Cloud models via OpenRouter
openai	🤖	OpenAI models
anthropic	🧠	Anthropic Claude models

Example Usage

# Login
!login max@example.com mypassword

# Quick chat (no conversation needed)
!chat Was ist die Hauptstadt von Frankreich?

# Create a conversation
!neu Programmierung Hilfe

# Send message in conversation
!senden Erklaere mir Python Listen

# View message history
!verlauf

# List conversations
!gespraeche

# Select conversation
!gespraech 1

# Change model
!modelle
!modell 2

# Archive and restore
!archiv 1
!archiviert
!wiederherstellen 1

# Pin conversation
!pin 1
!unpin 1

# Delete conversation
!loeschen 1

Environment Variables

# Server
PORT=3327

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_ALLOWED_ROOMS=#chat:matrix.mana.how
MATRIX_STORAGE_PATH=./data/bot-storage.json

# Chat Backend
CHAT_BACKEND_URL=http://localhost:3002
CHAT_API_PREFIX=

# Mana Core Auth
MANA_CORE_AUTH_URL=http://localhost:3001

Docker

# Build locally
docker build -f services/matrix-chat-bot/Dockerfile -t matrix-chat-bot services/matrix-chat-bot

# Run
docker run -p 3327:3327 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e CHAT_BACKEND_URL=http://chat-backend:3002 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-chat-bot-data:/app/data \
  matrix-chat-bot

Health Check

curl http://localhost:3327/health

Chat Backend API Endpoints Used

Endpoint	Method	Description
/health	GET	Health check
/models	GET	List AI models (public)
/models/:id	GET	Get model details (public)
/chat/completions	POST	Create AI completion
/conversations	GET	List conversations
/conversations	POST	Create conversation
/conversations/archived	GET	List archived
/conversations/:id	GET	Get conversation
/conversations/:id	DELETE	Delete conversation
/conversations/:id/messages	GET	Get messages
/conversations/:id/messages	POST	Add message
/conversations/:id/title	PATCH	Update title
/conversations/:id/archive	PATCH	Archive
/conversations/:id/unarchive	PATCH	Unarchive
/conversations/:id/pin	PATCH	Pin
/conversations/:id/unpin	PATCH	Unpin

Chat Modes

The bot supports different ways to chat:

1. Quick Chat (!chat): Stateless, single message/response, no history
2. Conversation Chat (!senden): Stateful, maintains message history, context-aware

Number-Based Reference System

The bot uses a number-based reference system for ease of use:

1. User runs !gespraeche or !modelle to get a list
2. Bot stores the list internally for the user
3. User can reference items by their list number
4. Numbers are valid until the user runs a new list command

This allows simple commands like:

• !gespraech 3 - Select conversation #3
• !archiv 1 - Archive conversation #1
• !modell 2 - Select model #2