Documentation

Getting Started

Installation

Download the OpenEditor desktop app for macOS. It’s a native app built with Tauri — no browser required.

Open the secure download flow →

First Launch

1. Your projects appear automatically. OpenEditor scans ~/Documents/GitHub for projects and lists them on the home screen.
2. Click a project to open it. Your routes load as live, interactive frames on an infinite canvas.
3. Or open any folder. Click New > Open Folder to pick any local project directory.

Supported Frameworks

Agent-Friendly Setup

OpenEditor projects are easiest for coding agents when the repo includes a small set of explicit files. Agents should inspect the repo first, preserve existing config, and write the smallest correct setup instead of inventing routes or credentials.

Use the OpenEditor skill

When your agent supports skills, ask it to use openeditor-project-setup. That skill is responsible for detecting the framework, creating OpenEditor config, and generating useful test metadata.

Use the openeditor-project-setup skill.
Inspect this repo and make it OpenEditor-ready.
Create or update .logic-editor.json.
Create oe-tests.json for stable preview routes.
For iOS or SwiftUI projects, create oe-swift.json.
Do not include secrets, tokens, account IDs, or private deployment values.

Expected agent outputs

AGENTS.md snippet

Add a short repo-level instruction file when a project needs repeatable agent behavior. Keep it public-safe and avoid machine-specific secrets.

# Agent Notes

Use the openeditor-project-setup skill for OpenEditor config work.
Before editing, read .logic-editor.json, oe-tests.json, and oe-swift.json if present.
Prefer conservative route detection; default to / when route signals are weak.
Run the project verification command before reporting completion.
Never write API keys, bearer tokens, account IDs, or private deployment values into config files.

Agent checklist

• Read existing .logic-editor.json, oe-tests.json, oe-swift.json, and AGENTS.md before editing.
• Inspect high-signal files first: package.json, lockfiles, route folders, .xcodeproj, and .xcworkspace.
• Use conservative defaults when route detection is weak: one / route labeled Home.
• Keep secrets out of generated files. Use environment variable names only when configuration needs to refer to credentials.
• After writing config, run the smallest relevant verification command and report what still needs manual confirmation.

The Canvas

Every route in your project becomes a live, interactive frame on an infinite canvas. Frames are not screenshots — they render your actual running app.

• Pan — click and drag the background, or two-finger trackpad scroll
• Zoom — pinch on trackpad, or Cmd + scroll wheel
• Resize — drag the handles on a selected frame to test breakpoints
• Interact — click inside a frame to use your app normally

View Tabs

• Views — your route frames on the canvas
• Elements — auto-detected components rendered in isolation
• Code — built-in Monaco editor with your file tree
• Data — visual schema builder
• Style — extracted design tokens (colors, fonts, spacing)
• Config — route and state configuration

Dev Server

OpenEditor manages your dev server automatically:

• Auto-start on hover — hovering a project card on the home screen starts the server in the background
• Manual control — use the play/stop button in the navbar
• Port detection — the app auto-detects which port your server binds to
• HMR — code changes appear instantly in all frames via hot module replacement

Project Configuration

OpenEditor looks for this file in your project root. If it doesn’t exist, the app auto-detects your framework and creates one for you.

{
  "name": "my-project",
  "type": "react",
  "port": 5173,
  "requiredPorts": [5173],
  "runCommand": "bun dev",
  "routes": [
    { "path": "/", "label": "Home" },
    { "path": "/products/example", "label": "Product Page" }
  ],
  "canvas": {
    "artboardsPerRow": 2
  }
}

Configuration Fields

Route Definitions

Each item in the routes array can include advanced preview states for different scenarios:

{
  "path": "/dashboard",
  "label": "User Dashboard",
  "states": [
    { "label": "Guest View", "query": "?auth=false" },
    { "label": "Admin View", "query": "?auth=true&role=admin" }
  ]
}

Type Values

Supported values for type:

Integration with Project Loading

When a project is added via the "Add Project" button in the Workspace Manager:

1. The editor scans the selected directory.
2. It attempts to auto-discover routes by analyzing the file structure (e.g., src/pages, pages, src/app, app, and optionally templates/).
3. It generates or updates this JSON file to persist your workspace settings.
4. Agents can repeat the same onboarding process by using the openeditor-project-setup skill.

Best Practices

• Place this file in the root directory of your repository.
• Ensure your runCommand matches the package manager you are using (e.g., npm run dev vs bun dev).
• Ensure your port matches the one your local dev server actually binds to.
• Do not store secrets in OpenEditor config files. Use environment variables or platform secrets.
• Keep agent instructions in AGENTS.md short: repo purpose, setup command, verification command, and files the agent should avoid touching.

iOS / SwiftUI Projects

OpenEditor supports native iOS and SwiftUI projects. Create an oe-swift.json file next to your .xcodeproj:

{
  "name": "MyApp",
  "project": "MyApp.xcodeproj",
  "scheme": "MyApp",
  "simulator": "iPhone 16 Pro",
  "bundleId": "com.example.myapp",
  "views": [
    { "name": "Home", "file": "Views/HomeView.swift" },
    { "name": "Profile", "file": "Views/ProfileView.swift" }
  ]
}

Each view gets a preview node on the canvas with live simulator screenshots. The preview engine watches .swift files and automatically rebuilds and re-captures when you make changes.

Full iOS & SwiftUI documentation →

Keyboard Shortcuts

Troubleshooting

Frames not loading

• Make sure your dev server is running (check the play button in the navbar)
• Verify the port in your .logic-editor.json matches your dev server
• Check the Console tab in the inspector for errors

iOS previews not capturing

• Ensure the iOS Simulator is booted and the app is installed
• Check that oe-swift.json has the correct project and scheme
• Try clicking Build & Capture to rebuild from scratch

Projects not appearing

• Projects must be inside ~/Documents/GitHub for auto-discovery
• Or use New > Open Folder to add any directory manually
• The project needs a package.json, oe-swift.json, or .logic-editor.json