THE MANUAL
Return to FactoryWriter's Studio Wiki
The ultimate documentation for Writer's Studio - A distraction-free, hierarchical writing environment
Table of Contents
Overview
Writer's Studio is not just a note-taking app - it's a complete writing studio environment designed specifically for authors, journalists, and content creators who need deep focus and professional-grade tools. Unlike traditional note-taking applications that encourage fragmented ideas, Writer's Studio focuses on structured document management, seamless export workflows, and features dedicated to the writing process.
What Makes Writer's Studio Unique
- Anti-Note-Taking Philosophy: Designed for long-form writing, not fragmented notes
- Hierarchical Structure: Infinite nested folders and documents
- Professional Export: EPUB, PDF, and Markdown generation
- Story Wizard AI: Advanced narrative engine with RAG-powered consistency using ChromaDB
- Multi-Agent MCP System: Modular AI system for web browsing, file operations, and more
- Audio Integration: Built-in audio playback, transcription, and fast AI voice (Kokoro)
- Visual Storytelling: Cover images, images, and media embedding
Key Features
📚 Binder & Organization
Hierarchical Structure
Organize your writing into an unlimited tree of Folders and Text documents. Create project structures that match your creative process with infinite nesting depth.
Drag & Drop Reordering
Easily restructure your project by dragging items in the Binder. Move entire sections, reorder chapters, or reorganize your entire project in seconds.
Document Duplication
Quickly clone existing documents or entire folder structures to experiment with different versions without risking your original work.
Search & Replace
Global search across your entire project with batch replace functionality. Instantly find and update content across all documents.
Custom Icons
Personalize your workspace by assigning unique icons to folders and documents. Create visual cues that help you navigate complex projects.
✍️ Writing Experience
Distraction-Free Editor
Clean, minimalist interface with no clutter. Focus on what matters - your words.
Focus Mode
Highlight only the current paragraph or section. Eliminate distractions by hiding everything else.
Teleprompter Mode
Scrolling text display with adjustable speed for reading drafts or presenting work.
Inspector Panel
Manage metadata alongside your writing:
- Status: Draft, Revised, Final
- Synopsis: Brief overview of the document
- Research Notes: Keep reference materials linked
- Cover Images: Upload images for EPUB covers
- Audio Files: Upload audio for blog posts or podcasts
History Manager
Comprehensive Undo/Redo stack protects your work from accidental changes.
Auto-Save
Every change is automatically saved to the local SQLite database. No more lost work.
Dark Mode
Toggle between light and dark themes for comfortable writing at any time of day.
HTML Source Toggle
View and edit the raw HTML source of your documents directly in the editor (via the ℹ️ icon).
Markdown to HTML Conversion
Instantly transform Markdown text into clean, structured HTML (via the </> icon). Supports tables, lists, blockquotes, code blocks, and complex inline formatting.
🔄 Import & Export
Scrivener Import
Import entire .scriv projects (via .scrivx file). Automatically parses your Binder structure, synopses, and notes from Scrivener.
EPUB Support
Export: Generate production-ready EPUB files directly from your project tree
Open/Reader: Built-in EPUB reader to view external files
Cover Images: Uses folder cover images for EPUB covers
Project Backup
Export your entire project as JSON backup, or export as a single Markdown file for sharing.
Audio Integration
Upload MP3 and WAV files directly to documents. Audio is automatically managed during publishing and embedded via a custom player.
Automated Post Importer
Import Markdown blog posts directly into the Studio with automatic metadata mapping (YAML front-matter), asset ingestion (Base64 embedding), and template stripping.
🧙♂️ Story Wizard & Prose Generator
The Story Wizard is an AI-powered narrative engine that transforms high-level outlines into immersive prose using a two-stage generation process:
- Beat Architect: Breaks a scene synopsis into 4 distinct, logical narrative beats.
- Prose Expansion: Expands each beat into ~300+ words of immersive narrative.
- Story Bible (RAG): Uses ChromaDB to maintain strict consistency with character profiles and style guides.
- Humanization Protocol: Enforces constraints to avoid "AI-sounding" text and maintain specific pacing styles.
Installation & Setup
Prerequisites
- Node.js (LTS recommended)
- npm
- Python 3.10+ (for MCP agents)
- Conda (Anaconda or Miniconda - optional but recommended)
Quick Start
- Install Dependencies
cd writer-studio
npm install - Initialize Database
node init_db.js - Start the Application
./start_app.sh - Access the App
Local: http://localhost:3000
Remote: Secure Tailscale URL provided by startup script
Technology Stack
| Component | Technology |
|---|---|
| Backend | Node.js + Express |
| Database | SQLite3 (writing_app.db) |
| Frontend | Vanilla JavaScript (ES6 Modules) |
| Styling | Vanilla CSS with Dark Mode |
| AI Memory | ChromaDB |
| AI Voice | FastKoko (Kokoro-82M) |
| AI Chat | OpenAI |
| Workflow | n8n Automation |
| Remote Access | Tailscale Proxy |
| Browsing | Playwright |
| Protocol | Model Context Protocol (MCP) |
| Static Site | Eleventy (11ty) |
Key Files
| File | Description |
|---|---|
server.js |
Main Express server handling API routes, database operations, and EPUB generation |
db.js |
SQLite database connection and helper methods |
public/js/writer_v2.js |
Core frontend logic: state management, API calls, event handling |
public/index.html |
Main application entry point |
mcp_file_server.py |
Sandboxed file operations server |
manager.py |
Central orchestrator for multi-agent system |
transcriber.py |
Audio-to-text using MLX-Whisper |
Multi-Agent MCP System
Writer's Studio includes a sophisticated multi-agent AI system built on the Model Context Protocol (MCP).
Components
| Component | File | Role |
|---|---|---|
| Manager | manager.py |
Central brain orchestrates tasks and connects to all sub-agents |
| Model Agent | model-agent.py |
Manages model registry, API keys, and context windows |
| WebAgent | webagent_mpc.py |
Browser automation with Playwright, test runner, YouTube subtitles |
| Agent Flow | agent-flow.py |
Triggers external n8n workflows |
| File Server | mcp_file_server.py |
Safe filesystem access within jail directory |
| Transcriber | transcriber.py |
Audio-to-text using MLX-Whisper |
Available Tools
Browser Automation
browser_navigate, browser_click, browser_typebrowser_screenshot, browser_run_codebrowser_console_messages
Test Automation
discover_tests, run_playwright_test, run_test_by_namesmart_heal_test - Auto-fix failing testssmart_generate_test - Generate tests from descriptionssmart_plan_test - Plan comprehensive test suites
File Operations (Sandboxed)
fs_list_directory, fs_read_file, fs_write_filefs_delete_file, fs_move_file, fs_find_file
Media & Content
transcribe_audio - Local audio transcriptionget_youtube_subtitles - Download YouTube subtitlesfs_search_transcripts - Search through transcripts
Eleventy / Site
create_post, list_all_posts, remove_postpublish_site - Trigger Eleventy build
Writer Tools
read_active_document, edit_active_document, open_documentprose_stats - Analyze word count, readability, and banned wordsrestart_speech - Restart the remote Kokoro speech enginerestart_server - Restart the entire application suite (detached process)generate_qr_code - Generate QR codes for sharing links
AI Models
Dynamic model switching with runtime model propagation to all sub-agents.
Support for Ollama and OpenAI-compatible APIs.
API Reference
Document Management
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/documents |
Fetch all documents |
GET |
/api/documents/:id |
Get single document |
POST |
/api/documents |
Create new document |
PUT |
/api/documents/:id |
Update document |
DELETE |
/api/documents/:id |
Delete document |
POST |
/api/documents/batch-delete |
Delete multiple documents |
POST |
/api/documents/batch-stats |
Calculate word counts |
GET |
/api/documents/search?q=term |
Search documents |
POST |
/api/documents/replace |
Search and replace |
Import, Export & Backup
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/export |
Export project as JSON backup |
POST |
/api/restore |
Restore from JSON backup |
GET |
/api/export/epub?rootId=id |
Generate EPUB file |
POST |
/api/documents/import |
Import parsed data |
Story Wizard & AI
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/wizard/run |
Start AI generation (streamed) |
POST |
/api/wizard/save |
Save generated story |
GET |
/api/wizard/files |
List wizard templates/stories |
DELETE |
/api/wizard/files/:filename |
Delete story file |
POST |
/api/wizard/generate |
Generate story concept |
GET |
/api/config/models |
List available AI models |
ALL |
/api/manager/* |
Proxy to MCP Manager Agent |
System Configuration
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/config |
Get server configuration |
🧪 Plugin API Testing
The Writer's Studio includes a robust Playwright-based test suite specifically designed to test the inter-agent JSON-RPC communication bridge (the plugin_host.py MCP Server) without causing unintended side effects (like actually moving emails or editing live documents).
The Test Suite (transcripts/tests/plugin_api_test.spec.ts)
This test suite performs a realistic, integration-level API test by directly spawning the plugin_host.py backend and communicating with it via standard input/output (STDIO), exactly as the AI Manager Agent does in production.
It tests all 22+ plugins, including:
- Email Actions:
fetch_email,read_email,flag_spam,move_email - Document Actions:
open_document,edit_active_document - Build Automations:
build_jeff,make_epub_jeff,syncronize_project
How It Works (The MOCK_PLUGINS Architecture)
To make the tests 100% realistic while remaining completely safe, the system uses a bypass flag architecture:
- Spawning the Server: The Playwright
beforeAllhook uses Node'schild_process.spawnto launchpython3 plugin_host.py, injecting a special environment variable:MOCK_PLUGINS=true. - Schema Validation: When the test sends a JSON-RPC request, the
plugin_hostfully processes the request. It parses the plugin's python file, extracts the docstring schema, and maps the JSON arguments to positional command-line arguments. - Safe Interception: Instead of using
subprocess.runto execute the underlying code (which would modify the user's system),plugin_host.pyintercepts the call immediately prior to execution because it detects theMOCK_PLUGINS=trueflag. - Mock Response: It safely returns a standardized
[MOCK_RESPONSE]string back through the STDIO pipe.
Why This Matters
This approach ensures we are testing the actual server code and argument parsing logic rather than relying on tautological (self-fulfilling) mocks. If a plugin's argument schema changes or if the JSON-RPC implementation breaks, this test suite will fail, providing high confidence in the stability of the Multi-Agent API without risking user data.
Examples
Creating a New Project
- Start Writer's Studio
- Create a root Folder for your project
- Add Text documents as chapters or sections
- Use the Binder to organize your structure
- Add metadata via the Inspector panel
- Export to EPUB when ready
Using the Story Wizard
- Click the 🧙♂️ icon to open the Wizard panel
- Select your AI model (local or cloud)
- Define genre, tone, and structural directives
- Configure your character profiles
- Set up your chapter synopses
- Click Run Wizard to generate content
- Generated content appears in a new folder
Browser Automation with WebAgent
In interactive mode with the Manager:
> browser_navigate https://example.com
> browser_screenshot
> browser_click e15
> browser_type "search query" e20
Audio Transcription
- Place audio file in
transcripts/directory - In Manager interactive mode:
> transcribe audio document myfile.mp3
The system will automatically locate and transcribe the file.
Deployment Workflow
- Sync files:
./resync_project.sh - SSH to server:
ssh [email protected] - Update dependencies:
cd ~/writer-studio
npm install
Support & Contact
For issues or questions, contact: [email protected] (reference error IDs if applicable)