Nexa Slide User Guide

Note This guide is based on the main branch of the GitHub repository (v0.13.3 per the CHANGELOG, 2026-10-02). There is no official release (tags or installers) yet; you get it with git clone. For an overview of the app, see /apps/nexa-slide.

Overview

Nexa Slide is a local web service for building PowerPoint decks together with an AI (LLM) session. When you start a small web server on your PC, a slide editor (Studio) opens in your browser, and a Claude Code session opened in the same folder writes drafts or edits slides based on the requests you leave in the editor.

A single deck JSON is the source of truth. The browser view (render.js) and the PPTX converter (export_pptx.py) each draw it using the same rules.
It produces editable PPTX files. Slides are not baked into images; they are exported as native PowerPoint shapes such as text boxes, shapes, tables, connectors, and groups, so you can keep editing them in PowerPoint.
Differences between the screen and PowerPoint are verified numerically (pixel comparison with compare.py, JS↔Python result comparison with check_parity.py).
The server uses only the Python standard library (no external web framework, CDN, or npm). Only PPTX generation requires python-pptx.
It includes 15 design templates, 21 purpose-specific starter contents (15 template types + 6 hand-written examples), and 54 slide types.

How the AI Connection Works

Nexa Slide itself does not call any LLM API and does not take an API key. Instead, a session of the AI coding tool you use (recommended: Claude Code) reads and edits the files in the workspace.

Editor ──(leave request notes · send)──▶ decks/<deck>.requests.json
                                              │
                    watch_requests (request watcher started by the AI session)
                       │  ├─ heartbeat → editor header "Session connected"
                       │  └─ request batch → notifies the AI session
                       ▼
               AI session ──▶ working → edit deck JSON → done + reply
                                              │
                                     editor reloads the changed deck within 2 seconds

In the editor, select an element or area, leave a request note such as “Split this table into two slides,” and send it.
The request watcher (watch_requests) started by the AI session passes the request to the session.
When the AI edits the deck file, marks the request “done,” and leaves a reply, the editor automatically shows the new content.

The CLAUDE.md (for Claude Code) and AGENTS.md (for Codex CLI, Gemini CLI, Cursor, etc.) files created with the workspace describe this handling protocol and the commands, so the AI follows them as written.

Requirements

Component	Required?	Used for
Python 3.10 or later	Required	Server, build, and export — everything
`python-pptx` (1.0 or later)	Required	PPTX export
`Pillow` (10.0 or later)	Recommended	Precise text width measurement, `compare.py` image comparison
git	Required	Getting the engine (`git clone`)
AI coding tool	Required (for the AI connection)	Recommended: Claude Code (terminal, VS Code extension, Claude Desktop). Codex CLI, Gemini CLI, Cursor, and others can also be connected
Chrome or Edge	Recommended	Editor view, `compare.py` headless capture
Node.js 18 or later	Optional	`check_parity.py`, Mermaid diagram rendering (`render_mermaid.py`)
PowerPoint + PowerShell (Windows)	Optional	Editor “PowerPoint render preview”, PPTX with embedded fonts

Operating systems: the server, editor, build, and PPTX export all work on Windows, macOS, and Linux. Only the PowerPoint render preview, PPTX with embedded fonts, and the PowerPoint side of compare.py are Windows-only.
To use Claude Code, you need an account that can use Claude Code (separate from Nexa Slide).

Caution On Windows, depending on how Python was installed, the python3 command may not exist or may redirect to the Microsoft Store. Replace python3 in this guide with py -3 or python. In Git Bash, python may be a different wrapper, so use the Python that has python-pptx installed.

Installation

Keep a single copy of the engine on your PC, and keep slide content separately in workspace folders outside the engine.

macOS / Linux

mkdir -p ~/Projects && cd ~/Projects
git clone https://github.com/SosomLab/nexa-slide.git
python3 -m pip install --user -r nexa-slide/requirements.txt
python3 -c "import pptx, PIL; print('ok')"     # you're ready once it prints ok

Windows (PowerShell)

New-Item -ItemType Directory -Force D:\Projects | Out-Null; Set-Location D:\Projects
git clone https://github.com/SosomLab/nexa-slide.git
python3 -m pip install -r nexa-slide\requirements.txt   # if python3 is missing: py -3 -m pip …
python3 -c "import pptx, PIL; print('ok')"

Note To use a virtual environment, run python3 -m venv ~/.venvs/nexa && source ~/.venvs/nexa/bin/activate on macOS or py -3 -m venv $HOME\.venvs\nexa; & $HOME\.venvs\nexa\Scripts\Activate.ps1 on Windows, then run the same pip install. In that case, also tell the AI session “use the python in ~/.venvs/nexa.”

Fonts (Optional)

The default font set default uses operating system fonts (Malgun Gothic, Consolas), so there is nothing extra to install. To use the recommended set modern (Pretendard, JetBrains Mono, D2Coding — all SIL OFL), install the fonts and then select it in the workspace.

OS	Installation
macOS	`brew install --cask font-pretendard font-jetbrains-mono font-d2coding`
Windows	`pwsh -NoProfile -File <engine>\studio\install_fonts.ps1` (installs for the current user; no admin rights needed)

To change the font set: editor ⋯ → Font set, or python3 <workspace>/nexa.py set_fonts modern. PowerPoint and the browser must be reopened after installing fonts to show them.

Starting and Stopping the Service

The server listens only on 127.0.0.1 (this PC). It has no authentication, so do not expose it to other PCs.

Start Page (Hub)

python3 studio/service.py start     # from the engine folder → http://127.0.0.1:5599/
python3 studio/service.py stop      # stop
python3 studio/server.py            # or run in the foreground (stop with Ctrl+C)

When started without a workspace, it opens the start page (hub). The hub port is 5599; run information and logs are kept in the user settings folder, and nothing is written to the engine folder.

Workspace Server

Each workspace has a launcher, nexa.py, so you don’t have to type the engine path every time.

python3 <workspace>/nexa.py start      # runs in the background on that workspace's port (opens Studio directly if a deck exists)
python3 <workspace>/nexa.py url        # access address
python3 <workspace>/nexa.py status     # workspace, decks, server, session connection, pending/in-progress requests
python3 <workspace>/nexa.py restart    # after changing settings
python3 <workspace>/nexa.py stop       # stops only that workspace's server

One workspace = one server = one request watcher = one AI session. If each workspace uses a different port, you can run several at the same time.
Starting a second time in the same workspace is refused, and the existing address is shown.
If another program is using the port, it stops with a “port unavailable” message. Change port in nexa-slide.json or use server.py --port auto (finds a free port).

Start Page

This is the first screen you see when you open http://127.0.0.1:5599/. Because Nexa Slide physically separates the authoring tool (engine) from the slides you make, the start page first decides “where to create” and then hands off to Studio (the editor).

Tab	Contents
Start	Create new slides, Open folder/repository, Recent work
Tutorial	A 5-step guide: choose a workspace → template and direction → edit in Studio → request in a Claude session → present and export
Demo	Copies the engine example into `nexa-slide-demo/` in the base folder the first time and opens it. Feel free to edit it; to reset it, delete the folder and open it again
Templates	The design template list (color swatches, descriptions) and starter contents. Each card has a Preview
Browse samples	Add or remove reference sites and open them in a new tab
Template review	A screen (`/review`) for previewing, reviewing, and approving template and layout candidates and reference materials

Creating New Slides

Choose a title, template, and starter content.
Fill in the purpose, audience, writing direction, and reference materials. These are saved to BRIEF.md in the workspace and serve as the basis when the AI writes the draft.
Choose a save location. If you don’t, it is created under NexaSlide/<title> in your operating system’s Documents folder. If you choose a git repository, the subfolder is filled in as slides.
If needed, turn on “Leave a draft request for the Claude session”. A pending request is left on the first slide and delivered as soon as an AI session connects.
Click “Create and open Studio” to create the workspace, start its server, and go to the editor.

Under the form, “Or create with a command” shows the equivalent init_workspace.py command, pre-filled for PowerShell and bash, with a copy button. The button and the command produce the same result.

Port: if left blank, it suggests a free port starting from 5600 that no other workspace uses.
Preview: shows slides actually built from the chosen template × starter content in a window. If no content is selected, it shows layout samples. “Create with this combination” carries the selection straight into the form.

Caution On Windows, if a path contains & (e.g. S&OP), pyenv-win’s python3 may cut off the command. The start page shows a warning and rewrites the command with the real Python path, but if possible, remove & from the folder name.

The ☰ menu at the top left of the start page and Studio takes you to Home, New, Open, Studio, Tutorial, Demo, Templates, Samples, Recent work (search), and Base folder settings.

The base folder is NexaSlide/ under your operating system’s Documents folder (on Windows, including a location moved to OneDrive; ~/Documents on macOS; the XDG documents folder on Linux). You can change it with Base folder settings in the menu or the environment variable NEXA_SLIDE_PROJECTS. User settings are stored in %APPDATA%\nexa-slide\settings.json on Windows, ~/Library/Application Support/nexa-slide/settings.json on macOS, and ~/.config/nexa-slide/settings.json on Linux.

Creating a Workspace

A workspace is the folder on the side where decks are made (e.g. slides/ in a presentation repository). Instead of the start page, you can also create one with a command.

cd ~/Projects/my-talk
python3 ~/Projects/nexa-slide/studio/init_workspace.py slides --title "New Product Launch" --build
python3 slides/nexa.py start          # → http://127.0.0.1:<port>/

Set-Location D:\Projects\my-talk
python3 D:\Projects\nexa-slide\studio\init_workspace.py slides --title "New Product Launch" --build
python3 slides\nexa.py start

What gets created (existing files are left untouched):

slides/
├─ nexa-slide.json   choices only: port · title · engine location · template · font set · logo file
├─ nexa.py           launcher (start · stop · status · build_deck · …)
├─ CLAUDE.md         instructions for the Claude Code session (request watcher · handling protocol · commands)
├─ AGENTS.md         instructions for other AI tools (same rules)
├─ .claude/settings.json   Claude Code hooks — show session activity in the editor
├─ content/          content source <deck>.json  ← the AI writes drafts here
├─ decks/            deck <deck>.json (what the editor edits) · request notes <deck>.requests.json
├─ assets/brand/     logo (a placeholder image at first — replace it with your own logo PNG)
└─ out/              PPTX · renders · session state (excluded from git)

Main options:

Option	Meaning
`--title "title"`	Workspace title
`--template <name>`	Design template (default: the one set by the starter content, otherwise `lecture`)
`--starter <name>`	Copy starter content (table below)
`--deck <name>`	First deck name (default `intro`)
`--port N` or `auto`	Port (a free port is chosen automatically if omitted)
`--build`	Build the content source into a deck after creating
`--purpose` `--audience` `--direction …` `--material …`	Writing brief `BRIEF.md` (direction and material can be given multiple times)
`--ask-draft`	Leave a pending request to write a draft from the brief (implies `--build`)
`--force`	Rewrite only `nexa-slide.json` and `nexa.py`

Running it again on an existing workspace creates only the missing files (such as AGENTS.md). In a git repository, out/ and decks/.history/ are excluded via .gitignore, and you can commit the rest.

Starter Content

Start with a slide structure and example content suited to your purpose. The content is fictional, so replace the numbers, names, and dates.

Group Starter content

15 template types (purpose-specific default structures, 11–17 slides) research-report research report · strategy-plan strategy/annual plan · board-decision executive decision request · periodic-report periodic status report · investor-pitch investor pitch · ir-finance IR/finance · sales-proposal B2B proposal · case-story case study/retrospective · marketing-campaign marketing campaign · consulting consulting · lecture-theory theory lecture · training-course job training · classroom class/student presentation · public-policy public sector/policy · talk-story talk/portfolio

6 hand-written examples lecture-course 3-day course materials · schedule schedule/roadmap · story-retro project retrospective · notice-onboarding internal notice/onboarding · rfp-owner RFP summary · rfp-response proposal

Group	Starter content
15 template types (purpose-specific default structures, 11–17 slides)	`research-report` research report · `strategy-plan` strategy/annual plan · `board-decision` executive decision request · `periodic-report` periodic status report · `investor-pitch` investor pitch · `ir-finance` IR/finance · `sales-proposal` B2B proposal · `case-story` case study/retrospective · `marketing-campaign` marketing campaign · `consulting` consulting · `lecture-theory` theory lecture · `training-course` job training · `classroom` class/student presentation · `public-policy` public sector/policy · `talk-story` talk/portfolio
6 hand-written examples	`lecture-course` 3-day course materials · `schedule` schedule/roadmap · `story-retro` project retrospective · `notice-onboarding` internal notice/onboarding · `rfp-owner` RFP summary · `rfp-response` proposal

python3 <engine>/studio/init_workspace.py <folder> --title "Monthly Report" --starter periodic-report --template graphite

Course Materials Starter (`lecture-course`)

A starter for writing multi-day course materials on the same skeleton. It includes a shared cover, overall table of contents, and EoD (content/_common.json), a course introduction chapter ch00 (24 body slides), and a theory chapter ch01 (12 body slides, including Mermaid diagrams).

python3 <engine>/studio/init_workspace.py <workspace> --title "Course Name" --starter lecture-course
python3 <workspace>/nexa.py build_deck ch00 --force
python3 <workspace>/nexa.py build_deck ch01 --force
python3 <workspace>/nexa.py start

Design Templates

Colors, fonts, font sizes, and check criteria live in the engine’s templates; a workspace only picks a name via template in nexa-slide.json.

Template	Characteristics
`lecture` (default) · `lecture-large`	Lectures and course materials, 16:9 / uniformly larger text
`brief` · `notice` · `schedule` · `proposal`	Purpose-specific (decision, notice, schedule, RFP) colors and corners
`keynote` · `archive` · `blueprint` · `swiss`	Dark stage, gold / off-white paper, terracotta, serif / blueprint teal and orange / white background with a single red
`editorial` · `ledger` · `signal` · `forest`	Off-white, serif, crimson / cream, navy, gold / yellow, black, red / forest green, cream, terracotta
`graphite`	White background, black text, gray tones only with no accent color, no rounded corners

Using the Editor

Open the workspace server address (nexa.py url) in a browser to bring up Studio.

Screen Layout

Area	Contents
Header	Deck tabs · save status · session chip · ▶ Present · History · Export ▾ · ⋯ More (font set, template, shortcuts, reset layout)
Left rail	Thumbnails (drag to reorder, duplicate, delete) · note/request/in-progress/check badges · ＋ New slide
Mode bar	✎ Edit (E) · ◎ Select (M) · ✐ Draw (D) · undo · ✨ Fix layout · ✨ Polish
Format bar	Appears when you select an element in Edit mode — font, size, text color, bold, alignment, line spacing, fill, border, duplicate, delete, lock, ✥ Position
Bottom	Notes · Outline · Check tabs · page navigation · zoom (10–300%)
Right panel	Properties · Requests (list, status, replies) · History (automatic backups) · Changes (changes made outside the editor)

Colors are chosen from the template color palette, not arbitrary HEX values.

Three Modes

Mode	What it does
✎ Edit (E)	Click to select, drag to move (8px grid, Shift = free), resize with handles, double-click or Enter to edit text directly (Esc or Ctrl+Enter to finish)
◎ Select (M)	Click an element to open a note popover right there. Quick chips by element type (polish, make longer, make shorter, split table into two slides, etc.). Enter = add, Shift+Enter = new line
✐ Draw (D)	Mark an area with ▭ box · 〰 pen · 📍 pin and add a note. Elements overlapping that area become the target of the request

Adding Slides and Changing Types

Click ＋ New slide to open the Add Slide dialog.

By type: choose a slide type from preview cards in 8 purpose groups (opening and introduction, message, evidence and data, comparison and judgment, process and plan, people and cases, learning and review, closing and appendix). The chosen type is inserted pre-filled with example content.
By layout: choose by layout name.
Change type: right-click a thumbnail → “Change type…”. The title and notes are kept and the body is converted to the new type (Ctrl+Z to undo).

Saving, History, and Presenting

Autosave: saves 0.7 seconds after an edit. Nothing is saved if nothing changed. Ctrl+S saves immediately.
History: automatic backups are kept on every save (the latest 50) and before a build overwrites the deck. “Restore” takes you back to the deck at that point.
Changes: when the AI or anything else changes the deck from outside, the editor reloads it within 2 seconds and shows the changed slides and elements in the Changes tab, with thumbnail badges, and with blue dashed outlines on the canvas.
Present: F5 from the beginning · Shift+F5 from the current slide · →/Space next · ← previous · N notes and elapsed time · Esc to end.

Keyboard Shortcuts

Category	Keys
Modes	E Edit · M Select · D Draw
Slides	PageUp/PageDown · Home/End
Zoom	Ctrl+wheel · Ctrl+= / Ctrl+- · Ctrl+0 fit · Ctrl+1 100% · Space+drag to pan
Editing	Ctrl+Z/Y · Ctrl+C/X/V/D · Ctrl+B bold · Delete · Enter/F2 edit text · Ctrl+S save
Order	Ctrl+] / Ctrl+[ (forward/backward) · Alt+Ctrl+] / Alt+Ctrl+[ (to front/to back)
Other	F5 / Shift+F5 present · Ctrl+\ right panel · Esc close · ? help

Making Slides with an LLM (Claude Code)

Overall Flow

Step	What happens
① Create	Create a workspace from the start page or with `init_workspace.py` and start the server. The AI is not connected yet
② Connect the AI session	Open the AI in the workspace folder and say “start the request watcher” → the editor chip shows Session connected
③ Iterate	Leave requests in the editor → send → AI handles them → done + reply → editor refreshes automatically
④ Finish	Check shows 0 ERRORs → export PPTX → commit (if using git)

Requests left before connecting are not lost. They stay pending in requests.json and are delivered all at once as soon as the watcher starts.

Step 1 — Open a Claude Code Session and Start the Watcher

Terminal

cd '<workspace>'
claude

Type one line in the chat.

Start the nexa-slide request watcher for this workspace.

Claude reads CLAUDE.md and starts the following watcher with the Monitor tool (you can also type it yourself).

python3 <workspace>/nexa.py watch_requests --stream --takeover --label "<session name>"     (timeout 1800000)

VS Code: open the workspace (or its repository) with File → Open Folder and type the same line in the Claude Code chat. You can also view the editor inside VS Code with the command palette’s Simple Browser: Show.
Claude Desktop: create a Code (local folder) session, choose the workspace as the folder, and type the same line. If you open the editor in the built-in browser panel, Claude can also look at the screen directly to check its work.
A session opened in a folder other than the workspace (such as a parent repository) does not read the workspace’s CLAUDE.md automatically. Include the path in your request, for example: “<workspace> is a nexa-slide workspace. Read the CLAUDE.md in that folder first, then start the request watcher.” It helps to add a line to the repository root CLAUDE.md such as “Slide work is in slides/ — read slides/CLAUDE.md first.”

Note The watcher (--stream) ends on its own after about 30 minutes (1780 seconds) and emits {"event":"ttl"}. Following the CLAUDE.md protocol, Claude restarts it with the same command. --takeover cleans up any leftover previous watcher and takes over from it.

Step 2 — Check the Connection

Editor header chip	Meaning
Green Session connected	The watcher is running — sent requests are delivered right away
Blue Session working n	The AI is handling n requests
Gray No session connected	No watcher — requests are saved and delivered once the watcher starts

With Claude Code, the chip also shows session activity — “Working in chat for N min · n requests pending”, “Handling request”, “Idle — will handle requests right away”, “N other sessions”. The hooks in the workspace’s .claude/settings.json record this information, and Claude Code may ask you to confirm trust the first time you open it.

Step 3 — The First Draft

If you turned on the draft request when creating the workspace, the request “Please write a draft of this deck based on the purpose, audience, writing direction, and reference materials in BRIEF.md” is delivered as soon as the session connects. If you didn’t, saying “Write a draft from BRIEF.md” in the chat does the same. The AI works in this order:

Reads BRIEF.md and checks the layouts and fields with nexa.py layout_samples.
Writes content/<deck>.json (the content source). When choosing slides, it uses the slide type that fits the nature of the content.
Builds the deck with build_deck <deck> --force and clears overlap, overflow, and minimum-font-size ERRORs with check_layout <deck>.
Marks the request done and leaves a summary and follow-up questions (about anything left blank because it wasn’t in the materials) as a reply.

If you want to hand it off directly with a command, you can ask like this:

Write a draft of content/intro.json with the content below. Check the layouts with python3 nexa.py layout_samples,
reduce ERRORs with build_deck intro --force → check_layout intro, and make it viewable in the editor.
- Topic: <presentation topic>
- Audience and length: <for whom, how many minutes>
- Number of slides: <e.g. 10–12>
- Materials: <paths, documents, URLs to reference> (do not make up figures or quotes without a source)

Step 4 — Leaving Request Notes in the Editor

What	How
A single element	Click the element in ◎ Select (M) and write a note (Enter) — e.g. “Split this table into two slides”
An area	Draw a box, pen stroke, or pin with ✐ Draw (D) and write a note
The whole slide	Write a note in the slide request field of the Requests tab on the right (Enter = add, Shift+Enter = new line)
Sending	”Send N requests” in the bottom bar. When connected, they are delivered after 8 seconds of inactivity; “Send now” delivers them immediately
Fixing check results	✨ Fix layout — immediately sends a request containing this slide’s check results
Polishing content	✨ Polish — requests cleanup of logic and alignment while keeping the style

Notes first accumulate as drafts (number badges on the canvas, ✎ badges in the rail), and once sent they move through pending → working → done. Input you haven’t added yet is also kept in the browser, so it isn’t lost when you move to another slide or refresh.

When the AI needs clarification, it leaves the request pending and asks a question in its reply. Add your answer in the Requests tab and it is delivered again. When the AI creates a new deck, a new deck tab appears right away along with a “New deck — [Open]” notice.

Editing Directly from the Chat

You can also just tell the AI in the chat without request notes — “Change the title on slide 3 to a conclusion-style headline and keep tables to 6 rows or fewer,” “Cut the deck down to 10 slides.” The AI edits content/ and rebuilds, and the editor automatically loads the changed deck.

Caution If there are slides you edited directly in the editor, build_deck --force stops and tells you, because rebuilding from the content source would discard those edits. Ask the AI to “move the edits made in the editor into content and rebuild.” The state before overwriting can be restored from History.

Other AI Tools (Codex CLI, Gemini CLI, Cursor, etc.)

These tools read the workspace’s AGENTS.md (Gemini CLI reads GEMINI.md by default, so copy AGENTS.md to GEMINI.md or add it to the contextFileName setting). Because they cannot receive notifications from long-running commands, they connect using a wait-once loop.

This folder is a nexa-slide slide workspace. Read CLAUDE.md first (the same rules apply to you).
1) Run python3 nexa.py watch_requests --label "<tool name>". It waits until a request arrives, prints the list, and exits.
2) For each request: set status to working → edit the deck → reflect it in content as well → set status to done, with one or two sentences in reply.
3) When finished, run 1) again. Repeat until I tell you to stop.

For tools that cannot use a shell, skip the watcher: after sending requests, say “Handle the requests with status open in the requests.json files in decks/.” These tools have no session activity display (only the connected and working chips).

Finishing and Resuming

Closing the AI session stops the watcher, and the chip changes to “No session connected.” Stop the server with python3 <workspace>/nexa.py stop.
To resume next time: nexa.py start → open the AI session → “Start the request watcher.”

Deck JSON Structure Summary

There are two sources.

File	Contents	Who edits it
`content/<deck>.json`	Content source — a layout name + fields for each slide	Mainly the AI (drafts, large edits)
`decks/<deck>.json`	Deck — the content source built out with element coordinates	The editor (direct edits), the AI (handling requests)

Content source example:

{
  "id": "intro", "title": "New Product Launch", "part": "day1", "version": "0.1",
  "slides": [
    {"layout": "cover", "title": "New Product Launch", "subtitle": "Subtitle"},
    {"layout": "bullets", "title": "Why change", "items": ["Point 1", {"text": "Point 2", "sub": ["Supporting detail"]}], "notes": "Speaker notes"},
    {"layout": "table", "title": "Comparison", "header": ["Item", "Current", "New"], "rows": [["Speed", "1x", "**3x**"]]},
    {"layout": "summary", "title": "Summary", "items": ["Key takeaway"]},
    {"layout": "end", "title": "End of Document", "sub": "New Product Launch"}
  ]
}

Slides are based on 1280×720 px, converted to PPTX as pt = px × 0.75.
Deck element types: rectangle, ellipse, pill (pill), text box, image, line, arrow, curve, table, bullets, code, action plan, and more.
Inline emphasis: **bold** · ==highlight== · [[token|colored text]] · {page} (page number).
There are 56 layouts, including cover, table of contents, section cover, bullets, table, comparison, flow, cards, KPI, Gantt, roadmap, donut, and heatmap. See the list and field examples with python3 <workspace>/nexa.py layout_samples.
For long Korean sentences, breaking lines yourself with \n is the safest way to keep the screen and PowerPoint in sync.

PPTX Export

Method	Result
Editor Export ▾ → PPTX	`out/<deck>.pptx`
`python3 <workspace>/nexa.py export_pptx <deck>`	Same
Export menu “PPTX — embed fonts” or `nexa.py embed_fonts <deck>`	`out/<deck>-fonts.pptx` — embeds fonts for only the characters used (Windows, requires PowerPoint)
Export menu PowerPoint render preview	View an image actually rendered by PowerPoint in the editor (Windows, requires PowerPoint)

The exported PPTX consists of native PowerPoint shapes, so you can open it and edit it right away. Speaker notes are also included as PPTX slide notes.
Each export records the fonts used (free / system / custom) in out/<deck>.fonts.json.

Caution Edits made in PowerPoint do not flow back into the deck JSON (one-way). For content you will keep refining, edit it in the editor or through AI requests and export again.

Before exporting, make sure the Check tab at the bottom shows 0 ERRORs. Checks run automatically on every save and report text overlap, overflow, out-of-slide elements, minimum font size, and monospace column alignment. Click an item to jump to the element.

Verifying Screen–PowerPoint Consistency

Both renderers use the same rules so that the screen (browser) and the PPTX look the same, and you can check the result numerically. For most users, checking visually with the PowerPoint render preview is enough.

python3 studio/compare.py -W <workspace> <deck>: pixel comparison of the browser view and the PowerPoint render (Windows + PowerPoint + Chrome/Edge). For the 15-slide example deck, the difference is 0.3–2.7% (at the level of text edges).
python3 studio/check_parity.py -W <workspace>: checks that the screen (JS) and PPTX (Python) calculations produce the same results (requires Node.js).
Line layout correction values were measured with Malgun Gothic and Consolas. If you use other fonts, it’s a good idea to re-measure with compare.py.

Troubleshooting

Symptom	Check / fix
`python3` not found (Windows)	Run with `py -3` or `python` instead. Also tell the AI “use `py -3` instead of python3"
"Port unavailable”	Another workspace or program is using that port — change `port` in `nexa-slide.json` or use `--port auto`
”Already running”	That workspace’s server is already running — check the address with `nexa.py url`
”No deck” in the editor	Check whether there is a deck in `decks/` — if not, run `nexa.py build_deck <deck>`
Chip stays “No session connected”	Check that the AI actually ran the watcher command. If the session was opened in another folder, include the workspace path in your request
”Connected” but requests aren’t delivered	An expired watcher may be left over — restart it with the same command plus `--takeover`
`{"event":"refused"}`	Another session is watching this workspace — use that session or take over with `--takeover`
Request stuck in “working”	The AI session dropped mid-task — in the Requests tab, “Mark as done” → “Reopen” to return it to pending, then reconnect
`build_deck` stops	There are slides edited directly in the editor — move them into content, then build (see “Editing Directly from the Chat” above)
Logo not showing / image 404	Check that `brand.logo` in `nexa-slide.json` and the image paths in the deck are relative to `assetRoot`
PowerPoint render fails	Check that PowerPoint is installed and the `pwsh` path. If a previous render is still running, try again shortly
Repeated save conflicts	Check whether the same deck is open in another browser tab (no automatic merging)

Finding the process using a port:

# Windows
Get-NetTCPConnection -LocalPort 5600 -State Listen | % { Get-CimInstance Win32_Process -Filter "ProcessId=$($_.OwningProcess)" } | select ProcessId, CommandLine

# macOS / Linux
lsof -iTCP:5600 -sTCP:LISTEN
pgrep -fl watch_requests

Note On Windows, kill in Git Bash may end only the wrapper and leave python running. Use Stop-Process -Id <PID> -Force or taskkill /F.

Version History

Note Nexa Slide has not created any git tags or GitHub releases yet. The versions below are the engine versions recorded in the repository’s CHANGELOG.md, merged into the main branch in sequence.

Version Flow Summary

Version	Date	Highlights
v0.13.0 – v0.13.3	2026-10-02	Template parts, change type, per-deck/per-slide fonts, session activity display, 15 starters, 5 visual templates added
v0.11.0 – v0.12.0	2026-10-02	54 slide types, 19 new layouts, 4 approved templates
v0.10.0 – v0.10.2	2026-10-02	Changes tab, workspace fonts, PPTX with embedded fonts, template review
v0.7.0 – v0.9.0	2026-10-02	Start page and main menu, purpose-specific starters and designs, preview and create-with-command
v0.5.0 – v0.6.0	2026-10-01 – 10-02	Editor UI overhaul (3 modes, in-place notes), new workspace tool, course materials starter
v0.2.0 – v0.4.1	2026-10-01	Split into a standalone repository, layout checks, design templates, more stable session connection

v0.13.3 — 2026-10-02

Added Visual template graphite — white background, black text, only gray tones and weights with no accent color, no rounded corners, page numbers only.

v0.13.2 — 2026-10-02

Added 4 recommended visual templates — editorial (off-white, serif, crimson) · ledger (cream, navy, gold) · signal (yellow, black, red) · forest (forest green, cream, terracotta).

v0.13.1 — 2026-10-02

Added All 15 template types as starter content — purpose-specific default structures mixing 11–14 slide types (11–17 slides). 10 new ones (research-report, investor-pitch, sales-proposal, case-story, marketing-campaign, consulting, training-course, classroom, public-policy, talk-story).
Improved The existing 5 starters were expanded the same way. All 15 have 0 layout check ERRORs.

v0.13.0 — 2026-10-02

Added Template parts — within the same layout, the template chooses only the look of common parts such as labels, footer bands, and large page numbers.
Added Editor Change type — switch to a different slide type while keeping the title and notes.
Added Per-deck and per-slide font sets (slide > deck > workspace precedence).
Added Session activity display — Claude Code hooks show “Working in chat for N min · n requests pending” and similar in the editor chip.
Added AGENTS.md in new workspaces (instructions for Codex, Gemini CLI, Cursor).
Improved The start page warns when a path contains & and shows the command with the real Python path.

v0.12.0 — 2026-10-02

Added 4 approved visual templates — keynote · archive · blueprint · swiss.
Added 5 approved template types as starter content (periodic-report, board-decision, ir-finance, strategy-plan, lecture-theory).
Added Layouts donut (arcs editable in PPTX) · heatmap.
Changed Overlapping templates (story, report) and starters (weekly-report, monthly-report, decision-brief) are hidden from the lists — existing workspaces and --starter still work.
Improved Added “selection signals” to the 54 slide types so the AI picks a type that fits the content when drafting or handling requests (nexa.py slide_types).

v0.11.0 — 2026-10-02

Added 17 new layouts — conclusion panel, line chart, range bars, funnel, option comparison, quadrant, tree, person cards, photo plates, step-by-step solution, quiz, references, anticipated questions, and more.
Added 52 slide types (8 groups by purpose and structure) and the editor’s Add Slide dialog (by type / by layout).
Added Slide type review screen.

v0.10.2 — 2026-10-02

Changed Template review moved to a tab on the start page (/review).

v0.10.1 — 2026-10-02

Added A review registry for registering, previewing, reviewing, and approving template and layout candidates and reference materials.

v0.10.0 — 2026-10-02

Added Editor Changes tab — records and shows before/after per slide and element when a deck changed from outside (e.g. by the AI) is reloaded.
Added Workspace fonts (fonts/ + a custom font set), editor font dialog, record of fonts used (out/<deck>.fonts.json).
Added PPTX with embedded fonts (PPTX — embed fonts, requires PowerPoint on Windows) and a free fonts guide page.

v0.9.0 — 2026-10-02

Added Start page Preview — view slides actually built from template × starter content in a window.
Added Create with a command — shows the init_workspace.py and server start commands, filled in with the form values, for PowerShell and bash.
Added init_workspace.py options --port, --build, brief options (--purpose, etc.), and --ask-draft.
Improved The editor detects new decks, settings, and engine changes, refreshing deck tabs and showing a “New deck — [Open]” notice.
Added AI connection docs — how to connect Claude Code and other AI tools.
Fixed Build errors caused by empty samples in some layouts (column_chart, stack_bars).

v0.8.0 — 2026-10-02

Added 8 purpose-specific starter materials (weekly and monthly reports, decision request, schedule, retrospective, notice/onboarding, RFP issuing and response) and 6 design templates.
Added 16 layouts — status table, KPI tiles, Gantt, roadmap, weekly table, bar chart, and more.

v0.7.0 — 2026-10-02

Added Start page (hub) and the main menu at the top left — New, Open, Recent work, Tutorial, Demo, Templates, Samples.
Changed Slide content is no longer kept in the engine folder — the default workspace location is Documents/NexaSlide/<title>.

v0.6.0 — 2026-10-02

Added Course materials starter lecture-course and init_workspace.py --starter.
Fixed The launcher nexa.py raised a syntax error when the workspace was on a different drive from the engine (Windows).

v0.5.3 — 2026-10-02

Improved In the slide request field of the Requests tab, Enter = add note, Shift+Enter = new line.

v0.5.2 — 2026-10-02

Improved Footer footnotes are laid out horizontally with more visible numbers.
Improved Request input not yet added is kept in the browser (survives moving between slides and refreshing).

v0.5.1 — 2026-10-01

Added New workspace creation with init_workspace.py (automatic free port selection), layout samples layout_samples.py, and a detailed new project guide (macOS, Windows).

v0.5.0 — 2026-10-01

Changed Editor UI overhaul — Edit, Select, and Draw modes, in-place note popover, “Send N requests,” a docked format bar, and a position menu.
Added Zoom 10–300%, presentation mode (notes, elapsed time), History (restore from automatic backups), ✨ Fix layout · ✨ Polish.
Improved Nothing is saved if nothing changed. Slide designs are unchanged.

v0.4.1 — 2026-10-01

Fixed After the request watcher expired, it still showed “Connected” but requests were not delivered — the watcher now ends on its own after a set time (ttl), and --takeover takes over a leftover watcher.

v0.4.0 — 2026-10-01

Added Design templates — colors, fonts, font sizes, and check criteria are bundled into engine templates, and a workspace only picks a name. lecture (default) · lecture-large (larger text).

v0.3.0 — 2026-10-01

Added Layout checks — text overlap, overflow, out-of-slide elements, minimum font size, monospace alignment. Editor “Check” tab (runs automatically on every save; clicking an item jumps to the element).

v0.2.0 — 2026-10-01

Added Split into a standalone repository — engine and workspaces separated, multiple workspaces running at once on per-workspace ports, background service (start, stop, status).
Added Claude session connection — request watcher stream, editor session chip, “Send now.”
Added MIT license, example workspace, documentation.

Earlier versions (0.1, 2026-09) were developed as an internal tool (Slide Studio v0) inside another repository.

Known Limitations

Pre-release: there are no tags or installers; you get it with git clone. Development is moving quickly, so screens and commands may change.
Requires a separate AI tool: Nexa Slide does not call an LLM directly. Drafting and request handling are done by a session you open, such as Claude Code. Tools other than Claude Code connect via the wait-once loop or manually, and have no session activity display.
One-way conversion: edits made in PowerPoint do not flow back into the deck JSON.
Windows-only features: PowerPoint render preview, PPTX with embedded fonts, and the PowerPoint comparison in compare.py.
Editor: auto-fit text (shrink on overflow), rotation, shadows, transparency, and gradients are not supported. There are no multi-select or alignment tools.
Tables: rounded corners on header rows are square because PowerPoint tables don’t support them. In PowerPoint tables, rows grow automatically when text is larger than the cell (on screen it appears to overflow).
Concurrent editing: if the same deck is open in two browsers, whichever saves later gets a conflict notice (no automatic merging).
Local only: the server listens only on 127.0.0.1 and has no authentication. It is not meant for access from other PCs.
Screen–PowerPoint line layout correction is calibrated for Malgun Gothic and Consolas. Line positions may differ slightly with other fonts.

License

Nexa Slide is distributed under the MIT License and is free to use, including for commercial purposes. For third-party component notices, see THIRD_PARTY_NOTICES.md in the repository.

The engine repository does not include trademark files such as company logos or font files. The logo in the examples is a placeholder image; put your own logo in the workspace’s assets/brand/ and custom fonts in the workspace’s fonts/.
The recommended fonts (Pretendard, JetBrains Mono, D2Coding) are SIL OFL fonts; get them from their official distribution sites.

↑ Back to top

구성	필수 여부	쓰는 곳
Python 3.10 이상	필수	서버·빌드·내보내기 전부
`python-pptx` (1.0 이상)	필수	PPTX 내보내기
`Pillow` (10.0 이상)	권장	글자 폭 정밀 측정, `compare.py` 이미지 비교
git	필수	엔진 받기(`git clone`)
AI 코딩 도구	필수(AI 연결 시)	권장: Claude Code(터미널·VS Code 확장·Claude Desktop). 그 밖에 Codex CLI·Gemini CLI·Cursor 등도 연결 가능
Chrome 또는 Edge	권장	편집기 화면, `compare.py` 헤드리스 캡처
Node.js 18 이상	선택	`check_parity.py`, Mermaid 다이어그램 렌더(`render_mermaid.py`)
PowerPoint + PowerShell (Windows)	선택	편집기 “PowerPoint 렌더 미리보기”, 글꼴 포함 PPTX

탭	내용
시작	새 슬라이드 만들기, 폴더·저장소 열기, 최근 작업
튜토리얼	작업 공간 정하기 → 템플릿·방향 → Studio 편집 → Claude 세션 요청 → 발표·내보내기의 5단계 안내
데모	엔진 예제를 기준 폴더의 `nexa-slide-demo/`로 처음 한 번 복사해 엽니다. 마음껏 고쳐도 되고, 처음 상태로 돌리려면 폴더를 지우고 다시 엽니다
템플릿	디자인 템플릿 목록(색 견본·설명)과 시작용 내용. 카드마다 미리 보기
샘플 둘러보기	참고할 사이트를 등록·삭제하고 새 탭으로 엽니다
템플릿 검토	템플릿·레이아웃 후보와 참고 자료를 미리 보고 검토·승인하는 화면(`/review`)

옵션	뜻
`--title "제목"`	작업 공간 제목
`--template <이름>`	디자인 템플릿(기본: 시작용 내용이 정한 것, 없으면 `lecture`)
`--starter <이름>`	시작용 내용을 복사(아래 표)
`--deck <이름>`	첫 덱 이름(기본 `intro`)
`--port N` 또는 `auto`	포트(생략하면 빈 포트 자동)
`--build`	만든 뒤 내용 원본을 덱으로 빌드
`--purpose` `--audience` `--direction …` `--material …`	작성 브리프 `BRIEF.md` (방향·자료는 여러 번 줄 수 있음)
`--ask-draft`	브리프로 초안을 써 달라는 대기 요청을 남김(`--build` 포함)
`--force`	`nexa-slide.json`·`nexa.py`만 다시 씀

템플릿	특징
`lecture` (기본) · `lecture-large`	강의·교재 16:9 / 글자만 일괄 확대
`brief` · `notice` · `schedule` · `proposal`	목적별(결정·공지·일정·RFP) 색·모서리
`keynote` · `archive` · `blueprint` · `swiss`	어두운 무대·금색 / 종이 미색·테라코타·명조 / 도면 청록·주황 / 흰 바탕·빨강 하나
`editorial` · `ledger` · `signal` · `forest`	미색·명조·진홍 / 크림·남색·금색 / 노랑·검정·빨강 / 숲녹색·크림·테라코타
`graphite`	흰 바탕·검정 글자, 강조색 없이 회색 단계만, 모서리 없음

영역	구성
머리줄	덱 탭 · 저장 상태 · 세션 칩 · ▶ 발표 · 기록 · 내보내기 ▾ · ⋯ 더보기(글꼴 세트·템플릿·단축키·배치 초기화)
왼쪽 레일	썸네일(끌어서 순서 바꾸기·복제·삭제) · 메모/요청/처리 중/검사 배지 · ＋ 새 슬라이드
모드 바	✎ 편집(E) · ◎ 선택(M) · ✐ 그리기(D) · 실행 취소 · ✨ 레이아웃 고치기 · ✨ 다듬기
서식 줄	편집 모드에서 요소를 고르면 나타남 — 글꼴·크기·글자색·굵게·정렬·줄 간격·채우기·테두리·복제·삭제·잠금·✥ 위치 조정
아래	노트 · 개요 · 검사 탭 · 쪽 이동 · 확대(10~300%)
오른쪽 패널	속성 · 요청(목록·상태·답변) · 기록(자동 백업) · 변경(밖에서 바뀐 내용)

모드	하는 일
✎ 편집 (E)	클릭으로 선택, 끌어서 이동(8px 격자, Shift = 자유), 핸들로 크기 조절, 두 번 클릭 또는 Enter로 글자 직접 편집(Esc·Ctrl+Enter 종료)
◎ 선택 (M)	요소를 누르면 그 자리에 메모 팝오버. 종류별 빠른 칩(다듬기·더 길게·더 짧게, 표 두 장으로 나누기 등). Enter = 추가, Shift+Enter = 줄바꿈
✐ 그리기 (D)	▭ 박스 · 〰 펜 · 📍 핀으로 영역을 표시하고 메모. 그 영역과 겹치는 요소가 요청 대상이 됩니다

범주	키
모드	E 편집 · M 선택 · D 그리기
슬라이드	PageUp/PageDown · Home/End
확대	Ctrl+휠 · Ctrl+= / Ctrl+- · Ctrl+0 맞춤 · Ctrl+1 100% · Space+끌기 이동
편집	Ctrl+Z/Y · Ctrl+C/X/V/D · Ctrl+B 굵게 · Delete · Enter/F2 글자 편집 · Ctrl+S 저장
순서	Ctrl+] / Ctrl+[ (앞·뒤로) · Alt+Ctrl+] / Alt+Ctrl+[ (맨 앞·맨 뒤)
기타	F5 / Shift+F5 발표 · Ctrl+\ 오른쪽 패널 · Esc 닫기 · ? 도움말

단계	하는 일
① 만들기	시작 페이지나 `init_workspace.py`로 작업 공간을 만들고 서버를 띄웁니다. AI는 아직 연결 전입니다
② AI 세션 연결	작업 공간 폴더에서 AI를 열고 “요청 감시 시작” → 편집기 칩이 세션 연결됨
③ 고치기 반복	편집기에서 요청 남기기 → 보내기 → AI 처리 → 완료 + 답변 → 편집기 자동 갱신
④ 마무리	검사 ERROR 0 → PPTX 내보내기 → (git이면) 커밋

편집기 머리줄 칩	뜻
초록 세션 연결됨	감시가 돌고 있음 — 보낸 요청이 바로 전달됩니다
파랑 세션 처리 중 n	AI가 요청 n건을 처리 중
회색 세션 연결 없음	감시가 없음 — 요청은 저장되고 감시를 시작하면 전달됩니다

무엇을	어떻게
요소 하나	◎ 선택(M) 으로 요소를 누르고 메모(Enter) — 예: “이 표를 두 장으로 나눠 줘”
영역	✐ 그리기(D) 로 박스·펜·핀을 그리고 메모
슬라이드 전체	오른쪽 요청 탭의 슬라이드 요청 칸에 메모(Enter = 남기기, Shift+Enter = 줄바꿈)
보내기	아래 바 “요청 N개 보내기”. 연결되어 있으면 8초 조용해진 뒤 전달되고, “지금 보내기” 는 바로 전달
검사 결과 고치기	✨ 레이아웃 고치기 — 이 슬라이드의 검사 결과를 담아 바로 요청
내용 다듬기	✨ 다듬기 — 스타일을 유지하며 논리·정렬 정리 요청

파일	내용	누가 고치나
`content/<덱>.json`	내용 원본 — 슬라이드마다 레이아웃 이름 + 필드	주로 AI(초안·대규모 수정)
`decks/<덱>.json`	덱 — 내용 원본을 빌드해 요소 좌표까지 풀어 놓은 것	편집기(직접 수정), AI(요청 처리)

방법	결과
편집기 내보내기 ▾ → PPTX	`out/<덱>.pptx`
`python3 <작업 공간>/nexa.py export_pptx <덱>`	같음
내보내기 메뉴 “PPTX — 글꼴 포함” 또는 `nexa.py embed_fonts <덱>`	`out/<덱>-fonts.pptx` — 쓴 글자만 글꼴을 포함(Windows, PowerPoint 필요)
내보내기 메뉴 PowerPoint 렌더 미리보기	PowerPoint로 실제 렌더한 그림을 편집기에서 확인(Windows, PowerPoint 필요)

증상	확인·조치
`python3`을 찾을 수 없음(Windows)	`py -3` 또는 `python`으로 바꿔 실행. AI에게도 “python3 대신 `py -3`을 써”라고 알려 줍니다
”포트를 쓸 수 없다”	다른 작업 공간·프로그램이 그 포트를 사용 중 — `nexa-slide.json`의 `port`를 바꾸거나 `--port auto`
”이미 실행 중”	그 작업 공간 서버가 이미 떠 있음 — `nexa.py url`로 주소 확인
편집기에 “덱 없음”	`decks/`에 덱이 있는지 확인 — 없으면 `nexa.py build_deck <덱>`
칩이 계속 “세션 연결 없음”	AI가 감시 명령을 실제로 실행했는지 확인. 다른 폴더에서 연 세션이면 작업 공간 경로를 넣어 요청
”연결됨”인데 요청이 안 감	만료된 감시가 남았을 수 있음 — 같은 명령에 `--takeover`를 붙여 다시 겁니다
`{"event":"refused"}`	다른 세션이 이 작업 공간을 감시 중 — 그 세션을 쓰거나 `--takeover`로 넘겨받기
요청이 “처리 중”에서 멈춤	AI 세션이 처리 도중 끊김 — 요청 탭에서 “완료로 표시” → “다시 열기”로 대기로 돌린 뒤 다시 연결
`build_deck`이 멈춤	편집기에서 직접 고친 슬라이드가 있음 — content에 옮긴 뒤 빌드(위 “대화창에서 바로 고치기” 참고)
로고가 안 보임 / 그림 404	`nexa-slide.json`의 `brand.logo`, 덱의 그림 경로가 `assetRoot` 기준 상대 경로인지 확인
PPT 렌더 실패	PowerPoint 설치·`pwsh` 경로 확인. 이전 렌더가 진행 중이면 잠시 뒤 다시
저장 충돌이 반복	같은 덱을 다른 브라우저 탭에서 열었는지 확인(자동 병합 없음)

버전	날짜	핵심
v0.13.0 ~ v0.13.3	2026-10-02	템플릿 부품·유형 바꾸기·덱/슬라이드별 글꼴·세션 활동 표시, 시작용 15종, 시각 템플릿 5종 추가
v0.11.0 ~ v0.12.0	2026-10-02	슬라이드 유형 54개, 새 레이아웃 19종, 승인 템플릿 4종
v0.10.0 ~ v0.10.2	2026-10-02	변경 기록 탭, 작업 공간 글꼴, 글꼴 포함 PPTX, 템플릿 검토
v0.7.0 ~ v0.9.0	2026-10-02	시작 페이지·기본 메뉴, 목적별 시작용·디자인, 미리 보기·명령으로 만들기
v0.5.0 ~ v0.6.0	2026-10-01 ~ 10-02	편집기 UI 개편(3모드·그 자리 메모), 새 작업 공간 도구, 강의 교안 시작용
v0.2.0 ~ v0.4.1	2026-10-01	독립 저장소로 분리, 레이아웃 검사, 디자인 템플릿, 세션 연결 안정화