Multi-Character Conversation System with Claude Code

A TRPG-style game master system that orchestrates multi-character conversations with AI providers (Claude, Gemini, Droid), maintaining narrative history and workspace context.

What This Skill Does

This skill implements a persona chatbot system where:

Architecture Overview

**Backend (Python):**

**Frontend (Static):**

**Storage:**

Setup Instructions

1. Environment Setup

```bash

Create virtual environment

python3 -m venv venv

source venv/bin/activate # On Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Claude CLI authentication (first time only)

claude auth login

```

2. Configuration

```bash

Copy environment template

cp .env.example .env

Edit .env with required values:

- APP_JWT_SECRET (required if using APP_LOGIN_PASSWORD)

- APP_LOGIN_PASSWORD (optional, for simple auth)

- FACTORY_AUTH_DIR, CLAUDE_AUTH_DIR, GEMINI_AUTH_DIR (for Docker)

```

3. Create Admin Account

**For local development:**

```python

python3 -c "

from server.handlers.db_handler import DBHandler

import asyncio

async def create_admin():

db = DBHandler('./data')

await db.initialize()

success = await db.create_admin_user('admin', 'your_password')

print('Admin created' if success else 'Already exists')

asyncio.run(create_admin())

"

```

**For Docker (must be run inside container):**

```bash

docker compose exec persona-chatbot python3 -c "

from server.handlers.db_handler import DBHandler

import asyncio

async def create_admin():

db = DBHandler('./data')

await db.initialize()

success = await db.create_admin_user('admin', 'password')

print('Admin created' if success else 'Already exists')

asyncio.run(create_admin())

"

```

4. Run the Application

**Local development:**

```bash

python3 -m server.websocket_server

Access at:

- HTTP UI: http://127.0.0.1:9000

- WebSocket: ws://127.0.0.1:8765

```

**Docker:**

```bash

Copy and configure docker-compose

cp docker-compose.yml.example docker-compose.yml

Start containers

docker compose up --build

Ports follow .env settings (HTTP_PORT, WS_PORT)

```

Key Features

AI Provider Integration

The system supports three AI providers:

1. **Claude (via Claude CLI)** - Primary provider using local Claude CLI

2. **Droid** - Alternative Claude-based provider

3. **Gemini** - Google's Gemini API integration

Switch providers via WebSocket actions or workspace configuration.

Conversation History Management

Workspace Context

Authentication

JWT-based authentication with:

Testing

Manual Smoke Tests

```bash

Test all providers end-to-end

python scripts/ws_chat_test.py --provider claude --prompt "Test Claude"

python scripts/ws_chat_test.py --provider droid --prompt "Test Droid"

python scripts/ws_chat_test.py --provider gemini --prompt "Test Gemini"

```

Unit Tests

```bash

Install pytest

pip install pytest

Run tests

pytest -q

Tests should be in tests/ mirroring source structure

Example: tests/handlers/test_history_handler.py

```

Development Guidelines

Code Style

**Python:**

**JavaScript:**

Commit Conventions

Pull Request Guidelines

MCP Tools Integration

Serena MCP (Code Navigation)

```bash

Install once per machine

uvx --from git+https://github.com/oraios/serena serena --help

Create project (local only, don't commit .serena/)

serena project create --name persona-chatbot --language python --index .

Start MCP server

serena start-mcp-server --transport stdio

Call activate_project at session start

```

Use Serena for:

Context7 MCP (Official Docs)

Use Context7 for:

Security Notes

Document Synchronization

This repository uses a base document system:

Project Structure

```

├── server/ # Python backend

│ ├── websocket_server.py # Entry point

│ ├── core/ # Core utilities

│ ├── handlers/ # Business logic

│ ├── http/ # HTTP server

│ └── ws/ # WebSocket routing

├── web/ # Static frontend

│ ├── index.html

│ ├── app.js

│ └── style.css

├── persona_data/

│ └── stories/ # Saved narratives

├── chatbot_workspace/ # Workspace context

├── scripts/ # Utility scripts

├── tests/ # Test suite

└── docs/ # Documentation

```

Troubleshooting

**WebSocket connection fails:**

**Authentication errors:**

**AI provider errors:**

**SQLite lock errors:**

Language Guidelines

Version Information