Skip to main content

Understanding the Codex

The Codex is the lore coordinator behind every recap. After transcription and recap generation, Epicly passes that session through the Codex Update System so it can extract plot beats, NPCs, locations, lore threads, and quests, then update your campaign wiki automatically. This guide mirrors the help link on the in-app Codex page so you can follow along without leaving the tool.

Codex update system​

  • Automatic processing. Every new session upload runs the Codex Update System once the recap is ready. The system extracts entities, updates or creates wiki entries, refreshes the plot overview, and writes a change summary for each automatic edit. You can toggle the entire run off for a campaign from the Settings tab or manually trigger/retry it via the session detail menu when you need to backfill older sessions.
  • Plot overview. The system generates a high-level plot overview with every run, then keeps updating it as the story progresses. You can edit the plot text manually, leave it on auto-update, or lock it by turning the Auto-update toggle off in the overview editor so nothing changes until you want it to.
  • Entity extraction. Codex runs look for locations, factions, player characters, NPCs, lore beats, and quests. For each match it either creates a new wiki entry or updates an existing one, matching against the entry's title, its aliases, and related tags. Keeping aliases current is the single most effective way to prevent duplicates — see the Aliases section for a full breakdown.
  • Folder intelligence. The automation suggests folders for new entries based on inferred geography and relationships. It never moves existing entries; instead, it learns from the folder structure you build so future suggestions follow the patterns you prefer.
  • Entry controls. Each folder and entry has an Auto-update toggle (on by default) and a Private toggle. Turn off Auto-update to keep a lore item frozen, and enable Private to hide the content from players until you’re ready to reveal it.
  • Aliases, tags, and GM notes. Every entry has an alias list, related tags, and a GM notes field. Aliases drive entity matching (see the Aliases section); tags link related entries together; GM notes store hidden reminders only creators and GMs can read.

Modes and proposals​

  • Auto mode. The default mode. Approved Auto-update entries apply changes immediately so your wiki stays continuously in sync.
  • Review mode. When you switch a campaign to review mode (via Settings), every Codex run becomes a proposal queue. Each proposed change appears in the wiki tree and in the session’s Change Report; approve or reject it from there. Before approving you can edit the proposed text, and update proposals show existing vs. proposed content side by side.
  • Review queue toggle. The Wiki tab shows a Review Queue button when there are pending proposals. Clicking it opens the queue (temporarily hiding the regular tree) so you can Approve or Reject each change proposal, and clicking it again returns you to the wiki.

Versions, change summaries, and reports​

  • Version history. Every automatic or manual edit saves a version with a generated change summary. Open the “Show versions” control on any entry or on the plot overview to browse past drafts, compare revisions, or restore an earlier text.
  • Codex Change Report. Each session detail page now has a Change Report card that displays the latest Codex run status, lists entities created or updated by that run, and links to those entries. The report auto-refreshes while the run is processing, players only see approved changes, and GMs see pending proposals.

Exploring the Codex page​

  • Home tab. Tracks campaign stats like time since the last session and your longest weekly streak so you can monitor momentum.
  • Overview tab. Displays the campaign description alongside the live plot overview updated by the Codex.
  • Sessions tab. Lists every session (list and timeline views) and shows separate recap and Codex status indicators so you always know what still needs a run.
  • Wiki tab. This is the heart of the feature:
    • Folders and entries live in the left-hand tree; selecting one reveals its contents in the central pane.
    • Use the … menu beside any folder or entry to rename it, delete it, move it, or access special controls like Auto-update and Private toggles.
    • Auto-update toggle: Disable it to keep that entry/folder untouched by future Codex runs.
    • Private toggle: Enable it to hide the entry (or entire folder) from players—the tree displays a lock icon to signal privacy.
    • Entry editor: Rich text controls let you edit the title, body, related tags, aliases, and GM notes.
    • Related tags jump straight to linked entries, and aliases help the Codex match incoming lore to existing pages.
    • GM notes stay hidden from players while letting creators leave behind-the-scenes reminders.
    • Review queue button, visible when review mode has pending proposals, swaps the tree for the queue view so you can work through approvals without losing your place.
  • Settings tab. Only campaign owners and GMs can turn Codex automation on/off, switch between Auto and Review modes, and configure the help link that points back to this guide.

Player access and wiki permissions​

GMs control exactly what players can see and do inside the Codex. Each folder and entry has independent permission settings:

  • Visible to players (default). Players can read the entry when they browse the Codex. They cannot edit it unless you explicitly allow it.
  • Players can edit. When enabled on an entry, players can add their own notes, theories, and observations directly to that entry. Useful for location pages or shared lore where the party's collective memory is the point.
  • Private (hidden from players). Enable the Private toggle on any entry or folder to hide it entirely from player view. A lock icon appears in the wiki tree so you can see at a glance what is secret. Players won't even know the entry exists until you reveal it.
  • GM notes. Every entry has a GM notes field that is always hidden from players, even on entries that are otherwise visible. Use it for behind-the-scenes reminders, true motivations, or spoilers you don't want in the main text.

These settings let you share as much or as little of your world as you want — a location the party has fully explored can be open for player annotations, while the villain's true identity stays locked until the reveal.

Aliases — the most important thing you can do for your Codex​

Aliases are the single most impactful thing you can maintain in your Codex. Every time the Codex runs, it scans the session transcript looking for known entities. It finds them by matching against the entry's title and every alias in its list. If a name it encounters doesn't match anything, it creates a new entry — even if the entity already exists under a slightly different name.

This is how duplicates happen:

  • "The Ashen Brotherhood" and "Ashen Brotherhood" — one has "The", one doesn't
  • "Lord Caelen" and "Caelen Duskmore" — same person, two different names used across sessions
  • "Thornwall" and "Thornwall Citadel" — a location referred to both ways depending on context

Every alias you add is a match the Codex can make correctly instead of creating a duplicate.

What to add as aliases​

For each entry, think about every way that entity has been referred to in your sessions:

  • NPCs: Full name, first name only, title + name, nicknames, epithets the party uses ("the hooded woman")
  • Locations: Short name, full name, regional variations ("the citadel", "Thornwall", "Thornwall Citadel")
  • Factions: With and without "the", abbreviations, slang names the party has given them
  • Items: Common name, proper name, how it's described in-session ("the cursed ring", "the signet ring", "Caelen's ring")

Auto-generated aliases​

When the Codex AI creates a new wiki entry, it automatically generates an initial set of aliases based on what it knows about the entity — common name variations, short forms, titles, and alternate spellings it detected in the session. This gives you a solid starting point without any manual work.

That said, the AI can only generate aliases from what it's seen so far. As your campaign evolves and new name variations appear in-session, you'll want to add those manually to keep matching accurate.

How to add aliases​

Open any wiki entry and look for the Aliases field in the entry editor. Add each alias as a separate entry. Changes save immediately and take effect on the next Codex run.

When to add aliases​

  • Right after creating an entry — add every known variant immediately, before the next session runs.
  • When you approve a proposal — if the Codex surfaces a name you don't recognize as a variant of something existing, add that variant as an alias before approving so future sessions route correctly.
  • After merging duplicates — the merge process carries over aliases from both entries automatically, but review them to make sure all variants are covered.
  • When you notice drift — if the party has started calling an NPC by a nickname mid-campaign, add it now rather than waiting for a duplicate to appear.
Make aliases a post-session habit

After each session recap, spend two minutes reviewing new Codex entries and asking: "what other names might come up for this in a future session?" A few aliases per entry keeps your wiki clean indefinitely.

Merging duplicate entries​

When the Codex creates a new entry for something that already exists under a different name (for example, "The Ashen Brotherhood" and "Ashen Brotherhood" as separate entries), you can merge them into a single clean entry with one click.

Open the … menu on either entry and choose Merge. You'll be able to select which entry to keep as the primary (its title and current body text become the merged result) and which to fold in. After merging, the secondary entry is removed and any aliases from it are added to the primary so future Codex runs route new information to the right place.

The best way to avoid duplicates in the first place is keeping aliases current — see Aliases above.

Using the Codex workflow​

  • Status indicators. Every session row now shows both recap and Codex status so you can see at a glance what has finished. Sessions processed before this update will state “Codex not run” until you trigger them manually.
  • Triggering and retrying runs. Use the … menu on any session detail to trigger the Codex run for that session or retry a failed run. It takes a few minutes and Retry only resumes once a failure is resolved.
  • Ordering caution. Running the Codex out of chronological order treats that session as new input, so approve any resulting proposals carefully to avoid mismatched lore.
  • Security guardrails. Only the campaign creator and assigned GMs can see the Codex tabs, review queue, and editing tools.

Backfilling your wiki​

Codex automation is enabled by default. Reprocess your earliest sessions by triggering a Codex run, approve or reject any proposals, then work forward chronologically so your wiki reflects every session, locks in aliases, and is ready for the next play night.

Last updated on