Getting Started

Synthezer is a local-first AI prompt pipeline application. It takes a rough idea and transforms it into a structured, verified, high-quality AI output through a rigorous 5-stage gated process.

The Problem

Most people interact with AI by writing a single prompt and hoping for the best. The result is unpredictable — sometimes great, sometimes useless. There is no structure, no verification, and no way to consistently reproduce quality.

Synthezer solves this by breaking AI interaction into a disciplined pipeline. Instead of one prompt, you go through five stages: Input, Understanding, Research, Implementation, and Output. At each stage, the AI must prove it understands, verify its approach, and meet your criteria before moving forward. The result is consistently better AI output that you can trust.

Who It's For

• Developers — who need reliable, structured code generation and technical planning
• Researchers — who want AI assistance with verified, traceable reasoning
• Content creators — who need consistent, high-quality outputs with clear requirements
• Anyone serious about prompt quality — who is tired of getting mediocre results from unstructured prompting

Key Principles

Installation

Prerequisites

• Node.js 18 or later — download from nodejs.org. This includes npm, which you will need to install dependencies.
• Git — to clone the repository. Download from git-scm.com if you don't have it.

To check if you already have these installed, open a terminal and run:

node --version
npm --version
git --version

You should see version numbers for each. Node.js must be v18.0.0 or higher.

Step 1: Clone the Repository

git clone https://github.com/mervanhasancalik/synthezer.git
cd synthezer

Step 2: Install Dependencies

npm install

This installs the core dependencies, including express (web server) and better-sqlite3 (local database). The install also builds the native SQLite bindings for your platform.

Step 3: Run Synthezer

You have three ways to run Synthezer, depending on your needs:

npm start

npm run server

npm run dev

On Windows, you can also use start.bat to launch the desktop app.

When the server starts, you will see a banner in the terminal confirming the port and URL. By default, Synthezer runs on port 8090.

Quick Start

This walkthrough will guide you through creating and running your first pipeline from start to finish.

1. Connect an AI Provider

Before running any pipeline, you need to connect Synthezer to an AI model. Click the AI button in the top navigation to open the AI panel.

You have two options:

• OpenClaw Gateway — Enter your gateway URL and API key in the Connection tab. This connects to cloud AI models through your configured gateway.
• Local AI — Switch to the Local AI tab. If you have Ollama, LM Studio, or another local provider running, Synthezer can auto-detect it. Select your provider and model from the dropdown.

2. Create a New Pipeline

From the dashboard, click New Pipeline. This creates a blank pipeline and takes you to Stage 1.

3. Write Your Prompt (Stage 1: Input)

Write your raw idea, question, or requirement in the prompt text area. Don't worry about making it perfect — the pipeline is designed to refine rough inputs into structured outputs. You can also attach images (screenshots, diagrams, mockups) for visual context.

For example:

Build a REST API for a task management app with user authentication,
CRUD operations for tasks, and role-based permissions.

4. Select Chips

Below the prompt, you will see five chip categories. Click chips to select them — each chip is a behavioral instruction that tells the AI how to approach your request:

• AI Mind — How the AI should think (e.g., "Step By Step Reasoning", "Code Review Mindset")
• Prerequisites — What the AI must check first (e.g., "Check Existing Patterns", "Read Documentation")
• Implementation — The domain or focus area (e.g., "Backend Development", "Database Design")
• Tools — What the AI can use (e.g., "Node.js", "PostgreSQL")
• No-Go — Hard boundaries (e.g., "No Deprecated APIs", "No Hardcoded Secrets")

Synthezer ships with 180+ built-in chips. You can also create your own custom chips and organize them into chip packs for reuse.

5. Run Gate 1 (Understanding)

Click the gate button to advance to Stage 2. The AI reads your prompt and chips, then asks clarifying questions to make sure it understands your requirements. Answer the questions as thoroughly as you can. The AI may ask follow-up questions until it has enough context to proceed.

This is the most important stage. The AI cannot move forward until both sides agree on what needs to be built.

6. Provide Research (Stage 3)

The AI generates a list of research directives — specific topics where it needs real-world information. You provide documentation, API references, examples, or other research. This ensures the AI works with current, accurate information instead of relying solely on training data.

7. Review the Implementation Plan (Stage 4)

The AI creates a detailed implementation plan with a verification checklist. Every requirement, constraint, and chip instruction is accounted for. Review the plan and provide feedback if anything needs adjustment.

8. Get Your Output (Stage 5)

The AI executes the plan and produces the final output. You will receive:

• Short output — A concise summary of the result
• Detailed output — The complete, structured deliverable
• PAE scores — The AI's self-evaluation of its own work across three dimensions: Accuracy, Completeness, and Confidence (scored 0–100 each)

If the PAE scores are lower than expected, you can iterate by providing additional context or adjusting your chips.

9. Save to Library

Completed pipelines are saved to your local library on the dashboard. You can reopen, duplicate, or delete them at any time. Right-click a pipeline row for quick actions.

Configuration

Data Storage

Synthezer stores all data locally on your machine. By default, the SQLite database is created at:

~/.Synthezer/synthezer.db

On Windows, ~ resolves to your user profile directory (e.g., C:\Users\YourName\.Synthezer\synthezer.db). On macOS/Linux, it is your home directory (e.g., /home/yourname/.Synthezer/synthezer.db).

The database uses WAL (Write-Ahead Logging) mode for reliable concurrent reads. You may see additional files like synthezer.db-wal and synthezer.db-shm alongside the main database — these are normal SQLite operation files.

Environment Variables

You can customize Synthezer's behavior using environment variables. Set these before starting the application:

Examples

Run on a different port:

# Linux / macOS
SYNTHEZER_PORT=3000 npm run server

# Windows (PowerShell)
$env:SYNTHEZER_PORT=3000; npm run server

# Windows (Command Prompt)
set SYNTHEZER_PORT=3000 && npm run server

Use a custom database path:

# Linux / macOS
SYNTHEZER_DB_PATH=/data/synthezer/my.db npm run server

# Windows (PowerShell)
$env:SYNTHEZER_DB_PATH="C:\data\synthezer\my.db"; npm run server

Restrict to localhost only (disable network access):

SYNTHEZER_HOST=127.0.0.1 npm run server

Verifying Your Installation

After starting Synthezer, you can verify everything is working correctly:

Check the Health Endpoint

curl http://localhost:8090/api/health

You should see a JSON response like:

{
  "status": "ok",
  "version": "3.0.0",
  "timestamp": 1707500000000
}

Check the Database

The database is created automatically on first run. You can inspect it with the sqlite3 CLI:

sqlite3 ~/.Synthezer/synthezer.db ".tables"

You should see tables including: pipelines, stage1_input, stage2_understanding, stage3_research, stage4_implementation, stage5_output, chips, chip_packs, library, and pipeline_log.

Open the App

If you used npm start, the Electron window should open automatically. If you used npm run server, open your browser and navigate to http://localhost:8090. You should see the Synthezer dashboard.

Next Steps

Now that Synthezer is running, explore these topics to get the most out of the pipeline: