Getting started

This page covers installing JustWrite, opening it for the first time, finding your way around, and (optionally) wiring up AI features. Plan on about ten minutes.

Install

JustWrite is a desktop app. Download the installer for your operating system from the JustWrite website, run it, and open the app. There is no account to create, no subscription, nothing to register.

The first launch may take a few seconds longer than usual while the app sets up its workspace on your computer.

Your first project

The very first time you open JustWrite, a welcome screen greets you. It sums up what the app does — chapters & scenes, the story bible, plot strands & timeline, AI assistance, goals & pace, export — and offers the two ways to begin:

Start a new project — give it a title and (optionally) an author, and you’re writing.
Try the tutorial project — opens The Ninth Facet, a complete sample novel (more below).

The same screen introduces the optional AI features: Run Quick Setup installs a free local model that runs privately on your own PC, Connect an online provider points JustWrite at any OpenAI-compatible service, and you can skip both — everything is available later in AI settings. The welcome screen shows once; you can reopen it any time from the Help page (sidebar → Help → “Show welcome screen”). When your first project opens, JustWrite offers the AI setup once more — unless an AI provider is already your default.

A fresh workspace has no projects yet — the welcome screen is where the first one is born, and it stays your home screen until one exists. Once you have projects, the sidebar’s project switcher at the top of the left rail is where you rename them, create more, and move between them.

Try tutorial project

If you’d rather explore with a complete example first, the project switcher has a “Try tutorial project” item alongside the usual “+ New project” button. It opens The Ninth Facet — a real, complete sample novel (a magitech guild-adventure) with characters, locations, objects, groups, worldbuilding, chapters, plot strands, and events — so you can click through every screen without building anything yourself. It is created only when you ask for it, it is a real project you can edit freely, and when you’re done you can delete it from the same switcher (the button brings it back fresh any time).

A quick tour

The sidebar on the left is the main map. It is grouped into five sections:

Manuscript — Search, Home, Architecture, Strands, Chapters, Ask the book
Story world — Characters, Locations, Objects, Groups, Worldbuilding
Planning — Plot board, Timeline, Notes, Relations
Project — Analysis, Export, Trash, Settings

Hover any item to see its name. Click to open it. Drag the right edge of the sidebar to resize it; press Ctrl/⌘ + \ to hide it entirely (and again to bring it back).

Most sections have a tree under them. Click the chevron next to Chapters in the sidebar to see your Parts and chapters. Click the chevron next to Characters to see your cast. Each tree has a + button to add a new item.

If you’re not sure what a pane does, look for the small ? button next to its title. Clicking it opens a help drawer on the right with the docs for that surface — so you can get an answer without leaving the app or switching to a browser tab.

Make a new project

You can have several projects at once.

Click the project name at the top of the sidebar (it shows the current title and author).
Choose New project from the dropdown.
Give it a title and (optionally) an author name.

JustWrite creates a fresh blank project and switches to it. Switch back at any time from the same dropdown.

Starting from an existing draft

If you already have a manuscript in Word, Markdown, EPUB, or LibreOffice, you do not need to retype it.

Open Import from the sidebar’s Project section, drag your file onto the page (or use the file picker), and let the parser detect your chapters. You can review and rename them before they are added. See Import and export for the full walkthrough.

Optional: connect an AI provider

JustWrite’s writing tools, “Ask the book” chat, critique, and entity extraction all use AI. None of them are required — you can write an entire novel in JustWrite with zero AI calls. But if you want to use them, you choose the provider.

The choice is yours, and you can have several at once. Common options:

OpenAI (paid, cloud) — writing. Excellent quality. Add your API key in Settings.
Anthropic Claude (paid, cloud) — writing only. Excellent quality, particularly for critique and longer prose work. Add your sk-ant-… key.
The built-in local engine (free, private) — writing only. Runs entirely on your machine: the Quick Setup wizard on the AI page checks your graphics card, downloads the best catalog model that fits it, and sets it as the model every AI feature uses — one click, nothing else to install. Prefer running your own server? Ollama, LM Studio and any OpenAI-compatible endpoint are supported as providers too.

To add a provider:

Open AI Settings in the sidebar.
Click Add provider.
Choose a preset, paste any API key needed, and click Test to confirm the connection.

See AI providers for setup instructions for each engine.

A typical first session

A common rhythm for a writer’s first day with the app:

Open Settings → Project and fill in your book’s title, your name, the genre, a deadline (picked from a calendar), and a word goal.
Open Architecture and write a paragraph in the Premise document — what the book is about in one breath.
Open Characters and add your protagonist. Fill in Wants / Needs / Lie / Truth (the Motivation panel). You can come back and finish the rest later.
Open Chapters, add Chapter 1, and start writing.

You don’t have to do these in this order, and you don’t have to do all of them. JustWrite works the same whether you plan first and write later, write first and plan later, or jump between the two.

Where to go next

Core concepts — what Parts, Chapters, and Scenes actually mean in JustWrite, and how undo + autosave work.
Writing — the editor in detail.
AI providers — provider-by-provider setup, if you decided to enable AI.

For developers

JustWrite is open source. The repository lives at github.com/delebash/justwrite-app.

If you want to run from source instead of using a packaged installer:

git clone https://github.com/delebash/just-core.git
(cd just-core/packages/core && npm install)
git clone https://github.com/delebash/justwrite-app.git
cd justwrite-app
npm install
npm run dev

You will need Node.js 24 or newer — nothing else. JustWrite is plain JavaScript: a desktop window (Electron), the Vue 3 interface, and a small local server that keeps your books. The shared AI kit (just-core) sits beside the app’s folder, as above.

Running from source keeps its data in the data folder inside the checkout.

Command	What it does
`npm install`	JS dependencies (first run only; then once `cd src-electron && npm install` for the desktop app)
`npm run dev`	The desktop app, with the interface reloading as you edit
`npm run build`	The installer for the current OS, in the `dist/electron/Packaged` folder
`npm run dev:spa`	The interface only, in a plain browser tab (no desktop window — start the server with `npm run server`)
`npm run server`	The server alone, with no window (see Headless access)
`npm run build:spa`	The interface build only, for the browser (`dist/spa`)
`npm run bump <version>`	Update the version number in `package.json`
`npm run release`	Trigger the GitHub Actions cross-platform release build (manual only)
`npm run release:windows`	Same, but build Windows only — useful for iteration before going full release
`npm run release:macos`	Same, macOS only
`npm run release:linux`	Same, Linux only

The architecture and contribution notes live in the repo’s CLAUDE.md and README.md.

Releasing

The release pipeline is manual on purpose — no build runs on push, PR, or tag. Releases are kicked off explicitly with npm run release, which calls gh workflow run release.yml against the GitHub Actions workflow at .github/workflows/release.yml.

The typical flow:

npm run bump 0.2.0                                  # updates package.json's version (no commit)
git commit -am "release: v0.2.0"
git tag v0.2.0
git push && git push --tags
npm run release                                     # confirms, then triggers the workflow

Single-platform iteration. When you’re testing on one OS and don’t want to spend ~20 min waiting for builds you won’t use, target a single platform:

npm run release:windows     # only spins up the Windows runner
npm run release:macos       # only macOS
npm run release:linux       # only Linux

The GitHub Release picks up whichever binaries land first; re-running with a different platform later adds those binaries to the same release.

The workflow runs these jobs:

build — matrix build with electron-builder on macOS (universal .dmg), Windows (.exe installer), and Linux (.AppImage + .deb). Each runner checks out the shared kit and the sync engine beside the app, at the commits the app was tested with (npm run release passes them). The matrix is computed dynamically from the platforms workflow input (all / windows / macos / linux). Each runner then starts the packaged app as a user would, starts the server on its own through justwrite-server, and checks that both use the same data folder.
linux-user — opens the AppImage the way a Linux user does, on the current Ubuntu LTS.
publish — only when every check passed: creates the GitHub Release and attaches the installers and the update feed.
attach-docs — packs the docs/ folder into docs.tar.gz and attaches it to the release. The marketing site treats this as the source of truth for the docs at this version.
notify-website — fires a repository_dispatch to justwrite-website, which rebuilds and redeploys with the new docs.

A dry run builds and checks everything without publishing: gh workflow run release.yml -f tag=master -f publish=false (the files stay on the run for 7 days).

One-time setup for releases:

Install gh and run gh auth login.
Create a Personal Access Token with repo scope on justwrite-website, then add it as a repository secret named WEBSITE_DISPATCH_TOKEN on justwrite-app. Without it, the build still succeeds — the marketing site just won’t auto-rebuild.

Code signing. Skipped intentionally. macOS users see a “unidentified developer” Gatekeeper prompt on first launch (right-click → Open to bypass); Windows users may see SmartScreen warnings. Add an Apple Developer Certificate + Windows code-signing cert later if the friction becomes a problem.

Auto-update. On. The desktop app checks the GitHub Releases page for a newer version when it starts, every six hours while it runs, and when the computer wakes from sleep; Settings → Updates says when one is out, Download fetches it, and it installs when the app quits (or at once with Restart now). On a Mac, which can’t install an unsigned update, it opens the release page instead. The updater finds the installer by its file name, which therefore has no spaces.

Before a project exists

With no project loaded, the Welcome screen is home — the only other surfaces that work project-less are AI Settings and Help, and both link back to Welcome.

Each sidebar section has a filter box (type to narrow long lists), and items support drag-to-reorder — including parts and chapters, which reorders the manuscript itself. Settings → About shows your runtime, where images are stored, workspace statistics, and how many items sit in Trash.