Local LAN web app for generating editable PowerPoint decks through an already logged-in coding-agent CLI such as Claude Code, OpenCode, Cursor Agent, Codex CLI, Gemini CLI, or Trae Agent.
- Next.js web app
- Local user accounts and job history
- PPT template picker and template upload/import
- Optional brand assets bundled with imported templates, plus image uploads in chat
- Targeted slide revisions after generation
- Persistent local task queue with two concurrent generation slots, cancellation, and restart recovery
- Adaptive OpenCode heartbeat nudges for stalled runs, based on historical job progress
- Project-bundled ppt-agent pipeline and validator
- Project-bundled PPTX template analyzer
- Per-slide PPTX previews generated after successful output
- A user chats with the local web app, uploads source material, and chooses a PPT template.
- The server creates an isolated job workspace under
.ppt-agent-data/jobs/. - The selected coding-agent CLI runs against that workspace using the bundled ppt-agent pipeline.
- The app validates the generated editable
output/final.pptx, prepares per-slide previews, and exposes downloads.
The app does not call a cloud API directly. Model access comes from the coding-agent CLI session already installed and logged in on the host machine.
Prerequisites:
- Node.js 22 LTS or newer
- At least one supported agent CLI installed and logged in: Claude Code, Cursor, Codex CLI, Gemini CLI, Trae Agent, or OpenCode
- Python 3 is recommended for PPTX validation and template import helpers
Clone and start:
git clone https://github.com/NimaChu/ppt-agent.git
cd ppt-agent
npm run start:lanOr double-click/run one of the root scripts:
- macOS:
start-lan.command - Linux/macOS terminal:
./start-lan.sh - Windows:
start-lan.bat
The launcher will install npm dependencies when needed, build the production app when the build is missing or stale, create the initial admin user if no users exist, and bind the service to all network interfaces.
Default first-run admin:
username: admin
password: ppt-agent-admin
You can override it before the first run:
PPT_AGENT_ADMIN_USERNAME=admin PPT_AGENT_ADMIN_PASSWORD=change-me npm run start:lanAfter startup, open the printed LAN address from another computer on the same network, for example:
http://192.168.1.20:3007
LAN access requires the host firewall/router to allow inbound TCP port 3007.
Generation jobs are queued locally and at most two run at once. Running jobs time out after 20 minutes by default; customize this before startup with PPT_AGENT_JOB_TIMEOUT_MINUTES=30 npm run start:lan. Each new job receives its own template snapshot, so later template management does not alter work already in progress.
On Windows, use:
start-lan.batNo administrator permission is required if Node.js, Python, and the chosen coding-agent CLI are already available on the machine. If Windows Firewall prompts for access, allow private network access for LAN users.
OpenCode is supported on Windows, but its runtime can be sensitive to local security software, network stability, and PATH inheritance. The app passes prompts with shell: false, injects NODE_PATH, and writes a .ppt-agent-opencode-prompt.md copy inside each job workspace for debugging.
By default, the app auto-detects the first available CLI in this order:
Claude Code -> Codex CLI -> Gemini CLI -> OpenCode -> Cursor Agent -> Trae Agent
Admins can override this in 管理员设置 / Admin Settings. The selected executor is persisted and used for later jobs until changed. This is useful when a company computer only has one usable CLI, such as OpenCode.
The chat UI separates source documents from visual assets.
Content documents:
.md, .txt, .docx, .pdf, .pptx, .xlsx, .csv
Visual assets:
.svg, .png, .jpg, .jpeg, .webp
Documents are pre-extracted into sources/sources.md before the agent starts. Visual assets remain available in the job workspace so the agent can use supplied logos, screenshots, product images, or other explicitly described material.
Starter PPT templates live in the tracked data/templates/ directory and are copied into runtime data on first launch.
Admins can:
- Upload
.pptxor.potxfiles to create reusable templates - Edit template name, description, and tags
- Reorder templates by drag and drop
- Delete templates
Imported templates include generated metadata such as design_spec.md and spec_lock.md. The spec lock captures reusable constraints for color, typography, page size, layout regions, image/logo rules, and generation prohibitions.
Every job copies the selected template into that job's workspace before generation. This keeps running and historical jobs stable even if an admin edits or deletes templates later.
- Maximum concurrent generation jobs:
2 - Queued jobs show their position and can be cancelled before they start
- Running jobs can be cancelled from the UI
- Service restarts return interrupted jobs to the queue
- The final PPTX is validated before completion
OpenCode runs have an adaptive heartbeat:
- Different steps use different heartbeat windows, such as shorter windows for todo updates and longer windows for generation-script writing
- The app learns normal progress intervals from recent job history
- If OpenCode stops producing useful progress, the app nudges the same OpenCode session to continue from existing artifacts instead of restarting the whole job
- Heartbeat nudges are limited; if the agent still makes no progress, the normal no-progress timeout stops the job
The validator checks required files, slide count consistency, invalid JSON, text outside the slide canvas, obvious text overlaps, and a common PPTX layout failure where content is generated in a 10 x 5.625 inch region inside a 13.333 x 7.5 inch canvas.
QA reports are retained for admin jobs. For ordinary users, QA reports are hidden and removed after the app uses them for validation or automatic repair.
npm install
npm run dev:lanOpen:
http://localhost:3007
Create or reset an admin user:
npm run user:add -- --username admin --password ppt-agent-admin --name Admin --role adminWhen started from a cloned repository, mutable runtime data lives in:
.ppt-agent-data/
The tracked data/templates/ directory contains starter templates copied into runtime data on first launch. Windows installer builds keep mutable data in %ProgramData%\ppt-agent\data.
Typical runtime layout:
.ppt-agent-data/
auth/
jobs/
templates/
Do not commit .ppt-agent-data/; it contains local users, sessions, uploads, logs, and generated PPT files.
npm run start:lan
npm run dev:lan
npm run user:add -- --username alice --password change-me --name Alice --role user
npm run user:add -- --username admin --password change-me --name Admin --role admin
npm run typecheck
npm run lint -- --max-warnings=0
npm run build