https://github.com/unscripted/persona
Multi-persona conversation threading for Claude projects.
https://github.com/unscripted/persona
Last synced: 3 months ago
JSON representation
Multi-persona conversation threading for Claude projects.
- Host: GitHub
- URL: https://github.com/unscripted/persona
- Owner: unscripted
- Created: 2026-03-16T16:17:16.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-16T16:17:19.000Z (3 months ago)
- Last Synced: 2026-03-29T01:25:48.417Z (3 months ago)
- Language: Python
- Homepage:
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Persona MCP
Multi-persona conversation threading for Claude projects. Invoke different expert personas sequentially in a single persistent thread — each one sees the full history of what came before.
## What it does
You define personas as YAML files (founder, architect, ops lead, etc.), start a conversation, and invoke them one at a time. Each persona responds with full context of every prior message, so perspectives build on each other rather than starting fresh every time.
## Prerequisites
[uv](https://docs.astral.sh/uv/) must be installed. It manages Python and all dependencies — no separate Python install needed.
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
## Quick start
**Option A – run directly from GitHub (recommended for multi-machine use):**
Add to your Claude Code MCP config (`~/.claude.json`):
```json
{
"mcpServers": {
"persona": {
"command": "uvx",
"args": ["--from", "git+https://github.com/unscripted/persona-mcp", "persona-mcp"]
}
}
}
```
`uvx` fetches and runs the package straight from GitHub — no cloning required.
**Option B – run from a local clone:**
```bash
git clone https://github.com/unscripted/persona-mcp
cd persona-mcp
uv sync
```
Then add to your Claude Code MCP config:
```json
{
"mcpServers": {
"persona": {
"command": "uv",
"args": ["run", "--directory", "/path/to/persona-mcp", "persona-mcp"]
}
}
}
```
Once configured, call tools in Claude Code:
```
init_project → list_personas → invoke_persona
```
## Project structure
```
src/persona_mcp/
├── server.py # MCP server (primary entry point)
├── app.py # FastAPI REST interface (optional, for local inspection)
├── models.py # SQLAlchemy ORM: Conversation, Message
├── schemas.py # Pydantic schemas for tools and routes
├── personas.py # YAML/JSON persona file I/O
└── database.py # Engine, session factory, table creation
examples/ # Starter personas to copy into your project
├── persona.founder.yaml
└── persona.architect.yaml
pyproject.toml
```
In a project that uses persona-mcp, live personas sit at `.claude/personas/` alongside your other Claude project config.
## MCP tools
| Tool | Description |
|---|---|
| `init_project` | Create `.claude/personas/` dir, SQLite DB, and initial conversation |
| `list_personas` | Show all persona files in the project |
| `get_conversation` | Fetch conversation history, optionally filtered by persona |
| `add_message` | Append a raw message without invoking a persona |
| `invoke_persona` | Ask a persona a question; response is persisted to history |
| `create_persona` | Write a new persona YAML to disk |
| `delete_conversation` | Remove a conversation and all its messages |
## Persona files
Personas live as `persona..yaml` files in `.claude/personas/` within each project. Copy them between projects freely — or use the files in `examples/` as a starting point.
```yaml
name: Founder
role: Product strategy, positioning, go-to-market
context: >
Building ility, thinking about pricing and ICP alignment.
system_prompt: >
You are the founder of ility. Think strategically about product
positioning, market fit, and long-term vision...
```
Create a new persona via the tool:
```
create_persona(name="Compliance Expert", role="Regulatory mapping", system_prompt="...")
```
Or just drop a YAML file directly into `.claude/personas/`.
## Data model
Each project gets its own `persona.db` SQLite file. Two tables:
- **conversations** – `id`, `title`, `created_at`, `updated_at`
- **messages** – `id`, `conversation_id`, `persona_name`, `role`, `content`, `created_at`
The DB lives alongside the project. Back it up or commit it to version control if you want persistent history.
## Optional REST API
For local inspection or testing, run the FastAPI server:
```bash
uv run uvicorn persona_mcp.app:app --reload
# Docs at http://localhost:8000/docs
```
## Tech stack
- **Python 3.10+**
- **[FastMCP](https://github.com/jlowin/fastmcp)** – MCP server framework
- **FastAPI** – REST interface
- **SQLAlchemy 2** – ORM over SQLite
- **Pydantic v2** – schema validation
- **PyYAML** – persona file parsing
- **Anthropic Python SDK** – Claude invocation in `invoke_persona`