Covel

A modern, agentic AI RPG. Customize every mechanic with a plugin.

English · 简体中文

Current public release: v0.0.4. Covel is still early access: APIs, data formats, and plugin frontmatter may change between versions. Official prebuilt binaries currently target macOS Apple Silicon.

---

What is Covel

Covel is an AI-driven role-playing game where every gameplay mechanic — narration, NPC relationships, world lore, character creation, memory — runs as its own autonomous agent. A single turn can chain several agents together. Each agent is a plugin: install one, swap one, or write your own.

See it in action

The gif above is one normal turn. While the narrator writes the scene, four other agents work in parallel:

• Narrator + Guide — drive the story and offer next actions
• NPC Graph — extracts relationships and surfaces who-knows-whom
• Codex — accumulates world lore as you play
• Memory — keeps long-range context across the session

Every agent is its own plugin. Disable one, swap one, or write your own.

Quick start

Play it

Grab the official v0.0.4 macOS Apple Silicon build from GitHub Releases — Covel-electron-0.0.4-mac-arm64.dmg. The rolling release list is available at Releases.

Open Settings, paste an LLM API key, pick one of the four sample worlds (cloudmere / mistport / neonridge / haruka-academy), and play.

v0.0.4 focuses on turn-flow hardening, plugin/session resolution, localized framework UI, refreshed plugin templates, and release documentation. Full notes: docs/CHANGELOG.md#004---2026-05-28.

Your data lives at ~/.covel/ — config, keys, SQLite, custom worlds, logs. Full schema → docs/guide/desktop-config.en.md.

For Windows, Intel Mac, and Linux, build from source. Electron is the only desktop shell in the current codebase.

Run from source

pnpm install
cp llm.toml.example llm.toml        # model IDs and endpoints
cp .env.llm.example .env.llm        # provider API keys
pnpm dev                            # web :5173 + server :3001 (SQLite)

Open http://localhost:5173; debug page at /debug.

Need PostgreSQL, in-memory mode, or alternative paths? See docs/guide/env-registry.md.

Make your own

You can create a working plugin or world pack through the repo's two Claude Code skills:

• /create-plugin — describe the agent you want; the skill generates a PLUGIN.md (frontmatter + skill prompt) and a minimal package.json.
• /create-world — describe a setting; the skill produces world.yaml, WORLD.md, and data/world.data.yaml ready to drop into ~/.covel/worlds/.

Open Claude Code in this repository, type /create-plugin or /create-world, and have a conversation.

An official community for sharing plugins and world packs is on the roadmap. For now, share via Gist or fork.

Develop

For hand-writing plugins, debugging the runtime, or extending the kernel.

Bundled plugin packages

Plugin	Kind	Role
branch-reply	Function	Reply candidates and accepted-variant storage
char-creator	Mixed	Player creation and character tracking
character-blueprint	Function	Reusable character blueprints
character-presence	Function	Character portraits, sprites, voice, and media
chat-mode-narrator	Agent	Dialogue-focused narration
codex	Agent	World-knowledge codex
guide	Agent	Action guidance and option generation
living-world-rules	Function	Persistent world rules and lorebook projection
memory	UI	Memory panel
narrator	Agent	Main traditional-story narration
npc-graph	Mixed	Relationship graph retrieval and extraction
player-identity	Function	Hero voice, goals, and boundaries
pregame	Function	Pre-game bootstrap
scene-cast	Function	Current scene cast and active-speaker context
scene-prompts	Agent	Dialogue-mode short action prompts
world-init	Mixed	World schema and lore initialization

Write a plugin manually

Minimum: PLUGIN.md + package.json. Frontmatter declares trigger and tools; the markdown body is the agent's skill prompt.

---
name: my-plugin/main
priority: 500
model: plugin
trigger: { type: scheduled, interval: 1 }
tools:
  builtin: [create-form, plugin-data-set]
---
You are an XXX agent. On this turn you need to…

Full walkthrough → Plugin authoring guide. Existing plugins under plugins/ are good references too. See also: plugin registry · tool registry.

Repo layout

covel/
├── apps/
│   ├── web/              Frontend (React 19 + Vite)
│   ├── server/           Backend (Hono + Drizzle)
│   └── desktop/          Electron shell
├── packages/             Internal packages (runtime / context / ai-provider / store / memory / tools / …)
├── plugins/              Bundled plugin packages
├── worlds/               Sample world packs
├── prompts/              Externalised prompt templates
└── docs/                 Reference docs and author guides

pnpm workspaces + Turborepo · ESM-only · TypeScript strict. Full package list → CLAUDE.md.

Documentation

Topic	Link
Architecture & turn pipeline	docs/architecture/flow.md
Writing plugins	docs/guide/plugin-authoring.md
Plugin / tool registries	docs/reference/plugins.md · docs/reference/tools.md
API / SSE protocol	docs/reference/api.md · docs/reference/protocol.md
Desktop config	docs/guide/desktop-config.en.md
Desktop packaging	apps/desktop/PACKAGING.md

Full index → docs/README.md. The in-app debug page at /debug shows session timeline, runtime traces, and prompt diffs.

Roadmap

• Windows / Linux / Intel Mac builds
• Official community for sharing plugins and world packs
• Plugin marketplace inside the desktop app

Contributing & releases

• Issues and PRs welcome — please read docs/CONTRIBUTING.en.md first.
• Releases are driven by Git tags: pushing a v* tag triggers .github/workflows/release.yml to build the Electron macOS arm64 .dmg and .zip, then publish a GitHub Release.

License

MIT © 2026 Covel Contributors