Verbweaver is a writing and design platform that thinks in relationships (graphs). It's designed for writers, artists, engineers, developers, analysts, and anyone who wants to design things while linking every idea together and turning those ideas into manageable tasks. Think and take notes in a way that is natural to you. Then, when it comes time to communicate your ideas or information to other people, use the Compiler and the powerful templating engine to generate a linear document in various common filetypes.

Currently, the desktop application is in Beta. The web server version with enhanced collaboration features is under development and is not yet ready for use.

• Graph-based Design: Visualize relationships between your ideas, documents, and tasks
• Task Management: Turn any idea into a trackable task with Kanban boards
• Markdown-powered: All content is stored as Markdown files with metadata headers. The Pandoc Markdown format is used to enable exporting to many file formats using Pandoc with advanced formatting.
• Write to your heart's content: Use the built-in Editor or your favorite Markdown editor application to write chapters, notes, data, findings, or anything else.
• Unified Data Model: Everything is a node; a node is everything. A single file can be a written document, tracked as a Task, and visualized as a node on a graph.
• Export Anywhere: Compile your non-linear notes into linear documents (PDF, Word, ePub, etc.)
• Git Version Control: Built-in version control for all your projects
• Multi-platform: Available as a web app and desktop app (Windows, Mac, Linux)

The desktop application provides the best offline experience and bundles the frontend, a lightweight local backend, and default templates. It offers unique advantages compared to the web application:

• Offline Mode: Work without internet connection
• Local Storage: Your data stays on your machine
• Cross-platform: Built with Electron, the desktop app works on Windows, MacOS, and Linux
• Native Performance: Faster file operations and Git integration
• System Integration: Native file dialogs, system tray, auto-updates
• No Authentication: Start working immediately

Installers are available for each release:

• Windows: .exe installer
• macOS: .dmg installer
  • If the MacOS .app that you have is unsigned (such as by downloading the version automatically compiled by GitHub Actions), you may need to removed the quarantined attribute in order to run it: xattr -dr com.apple.quarantine Verbweaver.app
• Linux: .AppImage (or .deb / .rpm installers)

Build from source (one-time setup):

# Clone
git clone https://github.com/Verbweaver/verbweaver.git
cd verbweaver

# Install workspace dependencies (root installs shared + frontend + desktop)
npm ci

# Build shared types and frontend (required before desktop packaging)
npm run build:shared
npm run build:frontend

Run in development (per platform)

# Terminal 1 — Backend
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

For Windows, a convenient script to build and run the application in development mode is located at desktop\build-and-run.ps1.

# Terminal 1 — Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

# Terminal 1 — Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

Notes:

• Packaged installers bundle and auto-start a platform-specific backend binary (no separate step needed).
• In development you should run the backend yourself (two terminals as shown above).
• Desktop packaging is handled by electron-builder. See scripts in desktop/package.json (dist, dist:win, dist:mac, dist:linux).

Note: The web server version is incomplete and still in active development.

Perfect for collaboration and cloud access.

Quick start with Docker:

# From repo root
docker-compose up -d

Manual setup (separate terminals):

# Backend (FastAPI)
cd backend
python -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Frontend (Vite)
cd ../frontend
npm install
npm run dev  # serves at http://localhost:5173

Key configuration options can be set via environment variables:

Environment (backend):

# .env
SECRET_KEY=change-me
DATABASE_URL=sqlite+aiosqlite:///./verbweaver.db
BACKEND_CORS_ORIGINS=http://localhost:5173

# OAuth (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GITHUB_CLIENT_ID=your-github-client-id

Using PostgreSQL instead of SQLite:

# .env (PostgreSQL)
SECRET_KEY=change-me
# Async SQLAlchemy driver string using asyncpg
DATABASE_URL=postgresql+asyncpg://verbweaver:verbweaver@localhost:5432/verbweaver
BACKEND_CORS_ORIGINS=http://localhost:5173

# Optional Redis cache
REDIS_URL=redis://localhost:6379/0

See .env.example for all available options.

Notes:

• Ensure PostgreSQL is running locally and a database/user are created. For local dev:
  • user: verbweaver, password: verbweaver, db: verbweaver
• If you use docker-compose up -d, the compose file already provisions Postgres and Redis and points the backend to them.

For detailed setup instructions, see the Getting Started Guide.

If you are developing templates:

• Global/default templates are bundled under assets/templates and copied into desktop builds.
• The Compiler supports schema-driven variables and per-node variables; see docs/compiler-template-system.md.

Deploy Verbweaver using Docker:

docker-compose up -d

This will start:

• Backend API on port 8000
• Frontend on port 3000
• PostgreSQL database (optional)
• Redis for caching (optional)

Verbweaver uses a modern, scalable architecture:

• Backend: Python with FastAPI, SQLAlchemy, and GitPython
• Frontend: React with TypeScript, Vite, and Tailwind CSS
• Desktop: Electron with secure IPC communication
• Database: SQLite (default) or PostgreSQL
• Real-time: WebSockets for collaboration

verbweaver/
├── assets/                          # Static assets bundled with apps
│   └── templates/
│       ├── compiler/                # Default compiler templates by format
│       └── nodes/                   # Default node templates
├── backend/                         # FastAPI backend
│   ├── app/
│   │   ├── api/                     # API endpoints
│   │   ├── core/                    # Config, security
│   │   ├── db/                      # Sessions, redis client
│   │   ├── models/                  # Database models
│   │   ├── schemas/                 # Pydantic schemas
│   │   └── services/                # Business logic (compiler, templates, git)
│   └── tests/                       # Backend tests
├── desktop/                         # Electron desktop app
│   ├── src/
│   │   ├── main/                    # Main process
│   │   └── preload/                 # Preload scripts
│   └── resources/                   # Icons, packaging resources, defaults
├── docs/                            # Documentation site and guides
├── frontend/                        # React + Vite frontend
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── store/
│   │   └── views/
│   └── package.json
├── nginx/                           # Reverse proxy configs
│   └── nginx.conf
├── shared/                          # Workspace with shared TS types/constants
│   ├── src/
│   │   ├── config.ts
│   │   ├── constants/
│   │   └── types/
│   └── package.json
├── docker-compose.yml               # Full-stack dev/deploy (backend, frontend, db, redis)
├── start-dev.ps1                    # Convenience dev script
├── start-dev.sh
└── README.md

Comprehensive documentation is available in the docs directory:

• Getting Started Guide - Installation and setup
• Architecture Overview - System design
• API Reference - REST API documentation
• User Guide - How to use Verbweaver
• Developer Guide - Contributing and development
• Repository Paths - How project storage works
• Deployment Guide - Production deployment

Run the test suites:

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

# Desktop tests
cd desktop
npm test

# E2E tests
npm run test:e2e

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License + Commons Clause - see the LICENSE file for details.

The MIT License ensures that you have unrestricted rights to use, modify, and redistribute Verbweaver free of charge. However, the Commons Clause rider prohibits you from selling Verbweaver or a providing a service (such as a cloud-hosting solution) "whose value derives, entirely or substantially" from Verbweaver. If you wish to purchase a license exception to this clause, then please contact us with your offer.

• Pandoc for the document file type conversion
  • Pandoc is a separate program invoked by Verbweaver to generate documents in various formats. It is not "part of" Verbweaver in any way.
  • The source code to the exact version of Pandoc that Verbweaver uses may be found at: https://github.com/jgm/pandoc/tree/3.8.1
• Tectonic for the LaTeX typesetting system that can be run all as one binary
• FastAPI for the excellent Python web framework
• React for the UI library
• React Flow for graph visualization
• Monaco Editor for the code editor
• Electron for cross-platform desktop apps
• GitPython for Git integration
• FullCalendar (core, daygrid) © Adam Shaw — MIT License. We redistribute CSS assets for offline availability. See license: https://fullcalendar.io/license/mit
• All our contributors and supporters!

• Documentation: docs/
• Issues: GitHub Issues
• Discord: Join our community
• BlueSky: BlueSky
• Email: https://verbweaver.design/contact

Built with ❤️ by the Verbweaver team