Codex Narrative Engine

An Obsidian plugin that adds narrative intelligence to your TTRPG campaign vault. Codex indexes your world-building notes, surfaces broken links, detects logical contradictions in your story, and brings AI assistance directly into your creative workflow — so you can focus on running the game instead of auditing your lore.

Quick Start

1. Install the plugin (via BRAT or manually; community listing coming soon).
2. Add frontmatter to your notes — at minimum type: npc, type: location, etc. — so Codex can index them.
3. Open the warnings panel (ribbon icon or Codex: Open narrative warnings) to see dead links and state conflicts.
4. Set up an AI provider in Settings > Codex Narrative Engine > AI provider to unlock Lore Chat and AI-powered generation.

Features

World Management

• Entity indexing — reads frontmatter to build a live index of every entity in your vault.
• Smart autocomplete — type [[ to search your entity index; filter by type with [[npc:, [[location:, etc.
• Hover previews — hover any [[wiki-link]] for a quick summary from the entity's frontmatter and opening text.
• Dead-link detection — unresolved links are underlined in the editor, flagged in the gutter, and listed in the Narrative Warnings panel.
• State conflict warnings — catches contradictions like a dead NPC listed as present in a session, or an item held by a dead character.
• Create & rename entities — create new entity files from templates, or rename an entity and have every reference updated automatically.

AI-Powered Tools (Bring Your Own Key)

All AI features use your own API key — no subscription required. Supports Google Gemini, OpenAI, Anthropic (Claude), Ollama, LM Studio, and any OpenAI-compatible endpoint.

• Lore Chat — a sidebar conversation panel grounded in your campaign lore, with edit / regenerate / save-all-as-notes.
• Enhance Note — expands a stub entity into a fully fleshed-out note while preserving existing content.
• Generate Entity — creates a new NPC, location, item, or other entity from a short description, complete with frontmatter and optional stat block.
• Describe Scene — generates atmospheric read-aloud text for a location or session scene.
• Extract Entities — scans a session log or narrative note and creates individual entity files for each named NPC, location, or item.
• Revise Selection — select any text, give a natural-language instruction, and review the AI's changes in a diff before applying.

Documentation

Installation

Via BRAT (recommended)

BRAT installs plugins directly from GitHub and keeps them updated automatically.

1. Install BRAT from Settings > Community Plugins (search "BRAT")
2. Open Settings > BRAT > Add Beta Plugin
3. Enter djinnmind/codex-narrative-engine and click Add Plugin
4. Enable Codex Narrative Engine in Settings > Community Plugins

From Obsidian Community Plugins (coming soon)

1. Open Settings > Community Plugins
2. Search for Codex Narrative Engine
3. Click Install, then Enable

Manual / Sideload

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create a folder in your vault: .obsidian/plugins/codex-narrative-engine/
3. Copy the downloaded files into that folder.
4. Open Settings > Community Plugins, refresh the list, and enable Codex Narrative Engine.

Building from Source

Requires Node.js 18+.

git clone https://github.com/djinnmind/codex-narrative-engine.git
cd codex-narrative-engine
npm install
npm run build

The built plugin files will be at packages/codex-obsidian/main.js and packages/codex-obsidian/manifest.json.

To develop with hot-reload:

npm run dev

Running Tests

npm test

Runs the codex-core unit test suite (entity indexing, link resolution, diagnostic rules).

Project Structure

packages/
  codex-core/       Editor-agnostic narrative engine (indexing, diagnostics, link resolution)
  codex-obsidian/   Obsidian plugin (UI, commands, vault integration)

codex-core has no dependency on Obsidian and can be reused in other editors.

License

MIT