Using Zed with Holonovel

How-to. For Game Masters. You have Zed installed, a model provider configured, a Holonovel server running, and a folder of campaign notes. By the end, you'll keep your GM notes as Markdown files, use research and scene synthesis to enrich them, and load the result into a Novel.

Why Zed for GM notes

Zed is a Markdown editor with three AI surfaces that map cleanly onto campaign preparation:

The Inline Assistant rewrites one selected passage.
Edit Prediction suggests the next words while you type.
The Agent Panel reads the whole project, edits several files, and can call the Holonovel server through MCP.

The division matters. A scene description is a writing problem. Turning that scene into state the engine can enforce is a different problem. Zed handles the first; Holonovel handles the second.

Keep your notes as Markdown

Your notes are plain .md files in one campaign folder. Markdown keeps them readable without Zed, diffable in version control, and portable to any editor.

A layout that works:

valmayor/
├── AGENTS.md
├── running-notes.md
├── canon.md
├── npcs/
│   └── dulcinea.md
├── scenes/
│   └── 07-midnight-rally.md
└── modules/
    └── la-sangre-de-valmayor.md

One topic per file. A scene, an NPC, or a faction gets its own file.
Keep canon separate. canon.md holds facts the AI must not contradict.
Name scenes for the table. 07-midnight-rally.md sorts in play order.
Mark GM-only material. Put *DM only* at the top of a section the players have not earned.

Set up Zed

Install Zed. Download it from https://zed.dev/download, or install it with your package manager. On Fedora, the download page lists the COPR, Flatpak, and Snap options.
Configure a model provider. Open Settings → AI, then choose one:
- Zed-hosted models, billed through Zed.
- Your own API key from a provider such as Anthropic, or a gateway such as OpenRouter.
- A local model server such as Ollama or LM Studio.
Open the campaign folder. Keep the running notes, the adventure modules, and the scene files in one workspace so @-mentions can reach all of them.
Add project instructions. Create AGENTS.md in the campaign folder with the conventions the agent must follow.

A useful campaign AGENTS.md is small:

# Campaign instructions

- Read the running notes before rewriting a scene.
- Never invent a rule that contradicts the bound ruleset.
- Treat canon.md as the source of truth.
- Mark GM-only material with *DM only*.
- Preserve the author's voice; do not add jokes or modern idioms.
- Before editing a scene, restate the player objective in one sentence.

The settings file lives at ~/.config/zed/settings.json on Linux. The keymap lives at ~/.config/zed/keymap.json. Open them with Ctrl-, and Ctrl-K Ctrl-S.

The three AI surfaces

Surface	Linux shortcut	What it does	Use it for
Inline Assistant	`Ctrl-Enter`	Sends the current selection or line to the model and replaces it with the response.	Rewriting one paragraph, one read-aloud block, or one NPC note.
Edit Prediction	`Alt-\` to request manually	Suggests the next edit from recent changes and cursor context.	Finishing a sentence or a table while you type.
Agent Panel	`Ctrl-?` to toggle focus	Reads and searches the project, edits files, runs commands, and calls MCP tools.	Researching a topic, restructuring a module, or driving Holonovel through MCP.

On macOS, substitute Cmd for Ctrl in the main shortcuts. The Inline Assistant is Cmd-Enter, and the Agent Panel toggles with Cmd-?. Manual Edit Prediction is Alt-Tab in the default macOS keymap. Check Settings → Keymap if your layout differs.

Older Zed tutorials use Ctrl-Shift-A for the Agent Panel. Current Linux defaults bind that chord to other actions. Open the panel with Ctrl-?, the sparkle icon in the status bar, or the command palette action agent: new thread.

Connect Holonovel as an MCP server

Zed's Agent Panel can call Holonovel directly if you register the server under Settings → AI → MCP Servers. Add a local server with a command that starts the Holonovel server:

{
  "context_servers": {
    "holonovel": {
      "command": "sh",
      "args": ["-c", "cd /path/to/holonovel && exec npx tsx src/index.ts"],
      "env": {
        "TTRPG_NOVEL": "default"
      }
    }
  }
}

Replace /path/to/holonovel with your checkout. The wrapper sets the working directory because the documented custom-server format has no separate cwd field. If your Zed build supports cwd, use it instead of the sh -c wrapper.

Once the indicator next to the server is green, mention it by name in the Agent Panel:

"Using the holonovel server, switch to the Valmayor campaign and set the scene to the amphitheater at midnight."

Tool-calling quality varies by model. If the agent ignores the server, create an Agent Profile that enables only the Holonovel tools and disables the built-in file and terminal tools. That removes the competition.

Workflow A: turn a paragraph into playable GM notes

The example comes from two stages of the same campaign: the running notes in running-notes.md, and the later table-ready module la-sangre-de-valmayor.md. The prose survives the rewrite. The structure is what changes.

Spoiler warning. The example contains plot points from the author's home campaign. Read it as a worked example, not as a published adventure.

The source paragraph

Tonight, Dulcinea is leading her monthly rally. Hours of music and dance with a midnight speech by Dulcinea. She tells stories of her monster hunter ancestors, her own adventures, monsters and how to slay them, and especially stories of vampires. Residents of Valmayor are familiar with supernatural and dark magic because of these monthly stories.

This paragraph tells the GM what happens. It does not tell the GM how to run it. The table still needs an objective, an opening image, a social contract, a way for the scene to fail forward, and a reason the scene ends.

The missing pieces

A playable scene needs seven pieces:

Player objective — what the party is trying to get.
Read-aloud — the only text you say at the table.
Senses — three concrete details that make the place real.
What do you do? — the question that hands the scene to the players.
Navigating — the beats, pressures, and choices inside the scene.
NPC contract — what the NPC wants, will accept, and will not do.
Succeeding and failing — both outcomes move the story.

The prompt

Select the paragraph in Zed, press Ctrl-Enter, and use a prompt that names the shape you want:

Turn this paragraph into a playable social scene for Holonovel.

Return, in this order:
1. Player objective, one sentence.
2. Read-aloud, at most 80 words, second person, present tense.
3. Three sensory details.
4. "What do you do?"
5. Navigating: three to four social beats and the pressure that ends the scene.
6. NPC contract for the scene's host: Wants / Will Accept / Won't.
7. Checks with DCs and what each check reveals.
8. A countdown clock and what happens when it empties.
9. Succeeding and failing, both fail-forward.
10. One exit line that hands the scene back to the players.

Use @running-notes.md for canon. Use @modules/la-sangre-de-valmayor.md for the
scene skeleton. Do not invent lore that contradicts the notes.

The @-mentions are the important part. The Inline Assistant otherwise sees only the selected paragraph. Mention the running notes and the module that already works.

The transformed scene

The result is a block you can paste into an adventure module. It folds the rally and the attack that follows into one runnable scene. It is longer than the source paragraph because it carries the decisions the paragraph left implicit.

### Scene 7: The Midnight Rally — *DM only*

**Player objective:** Get Dulcinea's public blessing and a consecrated stake
before the strige reach the amphitheater.

**Read aloud:**

> The plaza is packed shoulder to shoulder, lantern light on whitewashed walls,
> the smell of lamp oil and orange peel. Dulcinea Montebello stands on the
> amphitheater steps with her whip coiled at her belt and her shield catching
> the firelight. She tells the old stories — the Montebello hunters, the things
> they buried, the things that came back — and the crowd answers her like a
> congregation. Then the wind turns cold, and the bell rope creaks though no one
> is ringing it.

**Senses:** lamp oil and orange peel · the crowd's answer coming back like a
wave · the bell rope creaking in the dark.

**What do you do?**

**Navigating:** The rally runs as four social beats.

1. **The story.** Dulcinea holds the crowd. A player can listen (History DC 12)
   or study the crowd (Insight DC 15).
2. **The petition.** The party asks for a stake. Dulcinea will not hand one out
   in public without an oath. A Persuasion DC 15 check, or a public oath, moves
   her.
3. **The omen.** A cold wind and a distant shriek. Perception DC 14 spots
   shapes on the rooftops. Dulcinea sees them too and does not break character.
4. **The attack.** When the clock empties, two strige descend on the
   amphitheater. Dulcinea takes one; the party takes the other.

**NPC contract — Dulcinea Montebello**

| Wants | Will Accept | Won't |
|---|---|---|
| Public calm · the town's trust · the party's help | A public oath · proof of the strige · a private conversation after the rally | Admit the militia in public · abandon the rally · hand out a consecrated stake without an oath |

**Checks:** History DC 12 (the Montebello story) · Religion DC 10 (the prayer
she recites) · Insight DC 15 (she knows more about the attacks than she says) ·
Persuasion DC 15 (a stake before the attack) · Perception DC 14 (the shapes on
the rooftops).

**Clock:** *The Strige Arrive* — 4 Beats. Tick one Beat when a social beat
fails or the party gives the crowd a reason to panic. At zero, the strige attack.

**Succeeding:** The party leaves with a consecrated stake, Dulcinea's public
blessing, and the crowd's trust. Dulcinea fights beside them.

**Failing:** The rally panics. Civilians are in the strige's path, and Dulcinea
must choose between the party and the crowd. The stake is still available
later, but it now costs a favor.

**Exit:** *"You have the town's eyes now. Use them well, or do not come back."*

The rewrite is better at the table for three reasons:

It gives the GM a decision surface. The objective, the clock, and the failure state answer "what happens if the players do nothing?"
It makes the NPC playable. The contract tells the GM when to say yes, when to call for a check, and when to refuse.
It keeps the prose. The read-aloud is still prose. The structure sits around it, not inside it.

Workflow B: research and synthesize new material

Two kinds of enrichment feed your notes. Research brings in outside facts. Synthesis generates campaign-consistent material from the server's own state. Use both, then edit the result in your own voice.

Research outside material

The Agent Panel can search the web and read the results. Ask for the facts you need, not a finished scene, and ask for sources so you can check them.

"Research medieval Spanish vampire folklore. List five details I can use in the Valmayor arc, with a source for each."

"Read these two articles on running social scenes and summarize the techniques that fit a horror campaign."

Fold the notes into canon.md or the scene file. Keep the citation next to the claim so you can verify it later.

Synthesize from the campaign state

Holonovel's synthesis surface generates advice and material from your ruleset and your Novel — NPCs, lore, and journal state. It runs in two external tiers plus Ruleset Wisdom:

Tier	Source	Removable
Ruleset Wisdom	Your rulebooks and vendor craft content	No — build output
External Synthesis	Web research — GM advice, actual-play notes	Yes — ask the server to revert it
Internal Synthesis	Your own Novel state — NPCs, lore, journal	Yes — independently

Ask for what you need, then review it before it reaches the table:

"Using the holonovel server, synthesize scene ideas for the midnight rally from the current campaign state."

"Generate a social encounter for the amphitheater. Keep it consistent with Dulcinea's established voice and the strige threat."

"Synthesize community GM advice for running a horror rally, then show me what you added."

External and internal synthesis are inert until you activate them; Ruleset Wisdom is active by default. Keep what fits the campaign, revert the rest:

"Revert all Synthesis content."

Ruleset Wisdom and player-authored items persist through a revert. External and internal synthesis are removed.

Turn synthesized material into notes

Generated material is a draft, not canon. Copy the useful parts into a scene file, mark GM-only secrets, and run the Workflow A prompt over anything that will be read aloud. Then load the notes into the campaign.

Source: spec §11 (Synthesis), Synthesis, Building a Server.

Load your notes into Holonovel

The GM notes are the script. Holonovel is the state. Create the state by talking to the server in the Game Master badge. The tool names stay in the engine; you say what you mean.

Create the campaign

"Start a new game called Regreso a Torre Nosferatu. Bind it to the D&D 2024 ruleset."

If the server has no ruleset installed, start with the ruleset-free base. The scene, NPCs, lore, and countdowns work without one.

Set the scene

"Set the scene: the amphitheater in Guardarrama at midnight, the night of Dulcinea's monthly rally. The scene type is social."

The scene description becomes the context for lore matching, action suggestions, and the GM briefing. Set location, time of day, and atmosphere as structured fields when you have them.

Create the people

"Create Dulcinea Montebello. She is the guard captain of Valmayor, the daughter of Don Fernando, and the public face of the Montebello family. She speaks in clipped Castilian and never raises her voice. Here are three lines she would say: ..."

Voice examples matter. They teach the AI how the NPC speaks, not only what the NPC knows. Create Alonso, Lucero, and the strige the same way.

Add the lore

"When anyone mentions the rally, the Montebello family, or the strige, remind me: Dulcinea formed a secret militia after Castle Nosferatu was moved. She does not want the creature attacks traced back to the castle."

Lore entries fire on keywords. Mark the entry GM-only if the players have not earned it. A shared entry can reveal the public story; a GM-only entry holds the secret.

Start the clock

"Start a countdown called 'The Strige Arrive' at 4 beats. It is Game Master only."

A GM-only countdown keeps the threat hidden. A shared countdown gives the players a visible clock; name a shared clock for the pressure, not the secret. Advance it when a social beat fails or the scene stalls.

Run the encounter

"Start combat: two strige attack the amphitheater. Dulcinea takes the nearer one. The crowd is in the blast radius."

Combat state is tracked by the engine: initiative, turns, conditions, and outcomes. You describe the tactics; the engine resolves the mechanics.

Record what happened

"Record in the story journal: the party swore the Oath of the Night's Kin. Dulcinea gave them one consecrated stake. The crowd saw the strige and will not forget it."

"Capture Dulcinea Montebello to the Codex."

The story journal keeps the decisions and consequences. The Codex keeps the NPC for the next campaign. Neither depends on the prose staying in the context window.

Save it as an adventure module

Put the scene in a Markdown file under TTRPG_ADVENTURE, then load it:

"Load the Regreso a Torre Nosferatu adventure."

Follow the format in Adventure Modules. The short version:

# Regreso a Torre Nosferatu

## Overview — *DM only*
A sequel campaign set 25 years after the fall of Castle Nosferatu.

## Adventure Hook
The dead rise in Avila with the sigil of Count Orlok on their graves.

## Region: Guardarrama

### Scene 7: The Midnight Rally — *DM only*
...

The server indexes the file and makes it searchable through the rules lookup. GM-only sections stay hidden from the Player badge.

Workflow C: keep the prose consistent

A model will flatten your campaign into generic fantasy. A few habits prevent that.

Keep Edit Prediction out of prose. It is useful for tables and code, and distracting in a read-aloud block. Disable it for Markdown or for the campaign folder:

{
  "languages": {
    "Markdown": { "show_edit_predictions": false }
  },
  "edit_predictions": {
    "disabled_globs": ["campaigns/**", "novels/**"]
  }
}

To turn it off entirely, set "edit_predictions": { "provider": "none" }.

Use the Inline Assistant for one move at a time. "Make this colder." "Cut this to two sentences." "Rewrite this in Dulcinea's voice." Small, explicit transforms keep the author's voice. A single prompt that asks for a whole rewrite tends to replace the voice with the model's default.

Use the Agent Panel for structure, not sentences. Ask it to split a module into scenes, build a table of NPC contracts, or check every scene for a missing failure state. Then do the prose pass yourself, or with the Inline Assistant.

Use @thread for continuity. When a scene was refined in a long Agent Panel thread, @thread in the Inline Assistant brings that context to a focused edit without re-explaining the campaign.

@thread Refine Scene 7's read-aloud using the same constraints.

Generate variants on purpose. Multiple cursors send the same prompt to several places at once. inline_alternatives sends the same prompt to several models:

{
  "agent": {
    "default_model": {
      "provider": "zed.dev",
      "model": "claude-sonnet-4-5"
    },
    "inline_alternatives": [
      { "provider": "zed.dev", "model": "gpt-5-mini" },
      { "provider": "zed.dev", "model": "gemini-3-flash" }
    ]
  }
}

Use the variants for read-aloud tone, not for canon. Pick one, then edit it in your own voice.

Shortcut cheat sheet

Action	Linux	macOS
Open the Inline Assistant	`Ctrl-Enter`	`Cmd-Enter`
Request Edit Prediction	`Alt-\`	`Alt-Tab`
Toggle the Agent Panel	`Ctrl-?`	`Cmd-?`
Start a new agent thread	`Ctrl-N`	`Cmd-N`
Add the selection to the current thread	`Ctrl->`	`Cmd->`
Open the command palette	`Ctrl-Shift-P`	`Cmd-Shift-P`
Open `settings.json`	`Ctrl-,`	`Cmd-,`
Open `keymap.json`	`Ctrl-K Ctrl-S`	`Cmd-K Cmd-S`

Rebind any of these in keymap.json. The Inline Assistant also supports a prefilled prompt binding, which is useful for a fixed transformation such as "rewrite this read-aloud in second person, present tense, at most 80 words."

Troubleshooting

The Inline Assistant returns nothing. Check that a model provider is configured under Settings → AI → Default Model and that you are signed in for Zed-hosted models. Inline Assistant uses Zed-configured providers; external agents do not power inline generations.

The Agent Panel cannot use tools. Confirm that the selected model supports tool calling, and that the thread's Agent Profile includes the tools you need. A model without tool support shows a "No tools" label.

Edit Prediction interferes with prose. Disable it for Markdown or for the campaign folder with the settings in Workflow C.

The Holonovel MCP server is not active. Check the working directory in the command, the Node.js version, and the server logs. Run the same command in a terminal first. If it starts there, the problem is the Zed configuration, not the server.

The agent rewrites in the wrong voice. Add voice examples to the NPC entry, add a short style block to the campaign AGENTS.md, and @-mention both. A model follows examples more reliably than adjectives.

Sources

Zed — Inline Assistant: https://zed.dev/docs/ai/inline-assistant
Zed — Agent Panel: https://zed.dev/docs/ai/agent-panel
Zed — Edit Prediction: https://zed.dev/docs/ai/edit-prediction
Zed — Instructions: https://zed.dev/docs/ai/instructions
Zed — MCP servers: https://zed.dev/docs/ai/mcp
Zed — Key bindings: https://zed.dev/docs/key-bindings
Zed — Linux default keymap: https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json
Holonovel — spec §11 (Synthesis), Appendix K (adventure module format)

Maintenance notes

Deliberate departures to preserve across future updates:

This page is about GM notes and the Holonovel MCP server, not about contributing to the Holonovel codebase. Do not reintroduce spec-driven development, repository skills, or gate commands.
Any MCP-capable client and model works. Do not harden the workflow into a Zed-only or single-provider dependency.
Prompt examples are intentionally terse. Do not expand them back into paragraph-length examples.

Last updated: 2026-10-25.

Holonovel

Start here

Convert

Converting Rulebooks

Build

Synthesis

Synthesis

Update

Updating a Server

Codex

Codex

Novel

GM notes in a Novel

Playing a Novel

Reference

Repository

Using Zed with Holonovel

Using Zed with Holonovel

Why Zed for GM notes

Keep your notes as Markdown

Set up Zed

The three AI surfaces

Connect Holonovel as an MCP server

Workflow A: turn a paragraph into playable GM notes

The source paragraph

The missing pieces

The prompt

The transformed scene

Workflow B: research and synthesize new material

Research outside material

Synthesize from the campaign state

Turn synthesized material into notes

Load your notes into Holonovel

Create the campaign

Set the scene

Create the people

Add the lore

Start the clock

Run the encounter

Record what happened

Save it as an adventure module

Workflow C: keep the prose consistent

Shortcut cheat sheet

Troubleshooting

See also

Sources

Maintenance notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally