OpenScribe

The CI check covers the supported Python test matrix, coverage floor, Ruff lint, Word task-pane tests, dependency audit, Bandit scan, secret scan, documentation validation, package build, and CLI smoke tests. The Windows package check builds and exercises the installer and portable distribution.

Open source desktop, terminal, and command-line writing software for books and other long-form projects.

Status: Active pre-release alpha

Version: 0.1.2

Supported Python: 3.11, 3.12, and 3.13

OpenScribe keeps your manuscript in ordinary Markdown files with YAML metadata. The files remain readable without OpenScribe and can be backed up with normal file tools or Git.

This is alpha software. Keep an independent backup of your manuscript. Real Microsoft Word round trips, native accessibility, and physical power-loss recovery are not fully validated.

If this is your first time using OpenScribe, follow the Windows getting-started guide. The packaged installer does not require Python or Git.

Choose the interface that fits your work:

All interfaces use the same project files and safety rules.

For a packaged release:

1. Open the OpenScribe releases page.
2. Download OpenScribe-Setup-VERSION-x64.exe and SHA256SUMS.txt from the release.
3. Run the setup file. It installs for your Windows account and does not require administrator access.
4. Open OpenScribe from the Start menu.

The installer includes the desktop application and command-line tools. Python and Git are not required. Release packages are not digitally signed yet, so Windows may show an unrecognized-app warning. Confirm that the file came from this repository and that its SHA-256 value matches SHA256SUMS.txt before continuing.

The portable ZIP is an alternative for users who do not want an installer. Extract the entire ZIP before opening OpenScribe.exe. Do not run it from inside the ZIP.

Use this route for development or when no packaged release is available. Install Git for Windows and Python 3.11 or newer first.

Then run these commands in PowerShell:

Set-Location $env:USERPROFILE\Documents
git clone https://github.com/mickpletcher/openscribe.git
Set-Location .\openscribe
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[desktop]"
openscribe --help

If activation or command discovery fails, use Troubleshooting.

The easiest route is:

openscribe desktop

With the packaged installer, open OpenScribe from the Start menu instead.

Select New project, choose an empty folder, enter a title, add a chapter and scene, and start writing.

To create the same project from PowerShell:

$projectPath = Join-Path $env:USERPROFILE "Documents\OpenScribe\my-novel"
openscribe init "My Novel" --path $projectPath --template fiction
Set-Location $projectPath
openscribe desktop --project .

OpenScribe creates this structure:

my-novel/
  .openscribe/
    project.yaml
  manuscript/
  characters/
  research/
  notes/
  build/

Do not run openscribe init in the OpenScribe source checkout unless you intend to turn that folder into a writing project. Use --path or choose an empty folder in the desktop application.

1. Open the project in the desktop application, TUI, or your text editor.
2. Add chapters and scenes.
3. Write and press Ctrl+S to save.
4. Create a checkpoint before major structural changes.
5. Use Brainstorm to map ideas into a flowchart and preview a book outline.
6. Review your outline and word counts.
7. Export a review copy to DOCX, PDF, or EPUB.
8. Keep a separate backup outside the project folder.

Common commands:

openscribe new part "Opening"
openscribe new chapter "Arrival" --part "Opening"
openscribe new scene "Bus Stop" --chapter "Arrival"
openscribe outline
openscribe status
openscribe snapshot save "end-of-session"
openscribe compile --format docx

See the complete CLI reference for every command group.

OpenScribe protects writing in several ways:

• unsaved desktop and TUI drafts survive navigation
• closing with unsaved text requires a Save, Discard, or Cancel decision
• saving checks whether another program changed the chapter on disk
• saves and structural changes create checkpoints before replacing manuscript files
• snapshot restore previews changes before --apply
• restore creates an automatic backup before touching managed files and uses a recovery journal
• migrations and identity repair are explicit operations, not ordinary reads
• duplicate chapter or scene titles require immutable IDs instead of ambiguous aliases
• hosted AI and proofreading require a disclosure and explicit transfer approval

These controls reduce risk. They do not replace an independent backup. Read Safety and recovery before using OpenScribe for important work.

• fiction, nonfiction, technical, screenwriting, and research templates
• desktop binder, editor, search, research views, export, checkpoints, and restore
• Textual TUI with manuscript editing, planning views, and keyboard actions
• immutable chapter and scene identities
• chapter and scene creation, movement, splitting, merging, and metadata
• outlines, project status, search, reports, and derived indexes
• draggable brainstorming flowcharts that preview and create grouped book outlines
• planning boards, story ideas, characters, settings, items, aliases, and relations
• research notes, citations, paper structure, and conference material workflows
• DOCX, PDF, and EPUB export
• optional local LanguageTool proofreading
• optional AI page and chapter drafting plus review, with explicit hosted-transfer consent
• experimental tagged Word export and import
• per-user Windows installer and portable Windows package

LanguageTool is not required. OpenScribe defaults to a disabled local endpoint at http://127.0.0.1:8081/v2/check.

After starting a self-hosted LanguageTool server and enabling it in .openscribe\project.yaml, run:

openscribe proofread chapter "Arrival"

The desktop and TUI can preview and apply suggestions to the current draft with undo support. They do not use hosted endpoints. Licensed hosted endpoints require HTTPS and explicit --allow-data-transfer approval in the CLI. Automated use of LanguageTool's free public endpoint is rejected.

See LanguageTool setup and troubleshooting.

Connect a hosted or local model, select a chapter or scene, and choose Write with AI. Describe what should happen, including the intended events, characters, setting, tone, point of view, and constraints. Generate either an approximately 250 to 350 word page or a complete chapter draft.

OpenScribe previews generated prose before applying it. An accepted page is inserted at the cursor. An accepted chapter replaces only the selected chapter in the editor. It remains an unsaved recovery draft until you review it and press Ctrl+S; the normal conflict check and checkpoint run before the manuscript file changes.

AI is not required for manual writing, saving, searching, recovery, or export.

On its first desktop launch, OpenScribe asks whether to connect an AI model. The setup supports OpenAI, Anthropic Claude, Google Gemini, Mistral, xAI Grok, DeepSeek, Azure OpenAI, Hugging Face, OpenRouter, FreeLLMAPI, a dedicated LM Studio preset, and Meta Llama through a named local Ollama preset. It also supports other OpenAI-compatible hosted and local APIs. The connection test sends no manuscript text. Pasted API keys are saved separately by provider in the operating system credential store, never in the project. Select Not now to keep AI disabled. Use AI setup later to change the provider, model, or endpoint.

Install provider support only if you need it:

python -m pip install -e ".[ai]"

OpenScribe shows the provider, model, and character count before manuscript text is sent from the desktop to a hosted service and asks for approval on every writing request. Each hosted CLI command requires --allow-data-transfer. Hugging Face and OpenRouter can route requests to upstream inference providers. The Meta Llama preset uses the local Ollama loopback endpoint by default. Local loopback endpoints do not require transfer approval unless the selected provider is FreeLLMAPI, which routes requests from its local gateway to hosted providers.

LM Studio can run on the same computer or another computer. For a remote model, LM Link is the simplest supported route. A direct network endpoint must use HTTPS because OpenScribe rejects nonlocal plain HTTP. OpenScribe cannot tell when a loopback service such as LM Link forwards a request to another computer, so review that service's routing before sending private writing.

See AI setup.

Normal openscribe compile --format docx creates a review or submission document. It does not import changes back.

The separate Word round-trip workflow adds identity tags and a local baseline:

openscribe word export --output build\roundtrip.docx
openscribe word import build\roundtrip.docx
openscribe word import build\roundtrip.docx --apply

The first import is a preview. Apply is blocked for conflicts, missing or duplicate identity controls, structural changes, and unresolved tracked changes. Markdown remains canonical.

This workflow is experimental. Use synthetic or copied writing until real Word validation is complete. See Safety and recovery.

Files under specs/ are development plans, not user instructions or contractual requirements.

The built-in help is always the exact reference for the installed version:

openscribe --help
openscribe COMMAND --help
openscribe COMMAND SUBCOMMAND --help

Examples:

openscribe snapshot --help
openscribe scene split --help
openscribe word import --help

Most project commands must run from the project folder or one of its subfolders. A valid project contains .openscribe\project.yaml.

Development setup:

python -m pip install -e ".[dev]"
python -m ruff check src tests scripts/check-secrets.py scripts/check_markdown_links.py
python -m pytest --cov=openscribe --cov-report=term-missing --cov-fail-under=80
python scripts/check_markdown_links.py
pwsh -File scripts/docs-check.ps1 -FailOnGap

Windows package build:

python -m pip install -e ".[packaging]"
pwsh -File scripts/build-windows.ps1

See VALIDATION.md for supported Python versions, package checks, security checks, and known validation limitations.

• The project is pre-release alpha software.
• Windows release packages are not digitally signed.
• Native desktop and TUI accessibility are not fully verified.
• Physical power-loss durability is not proven.
• Licensed hosted LanguageTool and live hosted AI providers are covered only by limited or mocked contract tests.
• Word round trips and the Office task pane require real-host validation and independent review.
• Rich scene metadata and drag-based binder reordering are not implemented.

Keep independent backups. Do not use the experimental Word workflow on the only copy of a manuscript.

• Current assessment
• Technical debt
• Validation limitations
• Decision records
• Completed upgrades
• Future upgrades
• Changelog