meith

Developers

Architecture

A closer look at workspaces, the browser runtime, the renderer, and the CLI.

A space is the visible workspace in the left rail. A project is a folder on disk. The renderer never mutates services directly — it calls tools, then re-renders from pushed app state.

Workspaces and projects

Opening a folder with project_open detects package metadata, creates or reuses a dedicated space, records a project, and opens an editor tab rooted at the folder. ProjectService detects:

  • project name,
  • package manager (pnpm, npm, yarn, bun, or unknown),
  • framework hints such as Next.js, Vite, React, Vue, Svelte, Astro, Remix, or Node,
  • package scripts.

Run commands live on the project record. The top bar's Run button calls project_run, which uses the configured command or falls back to a detected dev/start-style script. Dev servers are associated by cwd, their output is captured, and detected ports can be opened in browser tabs.

Generated projects are copied from templates/ into ~/Documents/meith by default. project_prewarm can keep generated app copies ready so creating a new workspace is fast.

Browser runtime

Browser tab metadata is persisted in app state. Live browser views are supplied by a BrowserViewHost:

  • Electron uses ElectronBrowserViewHost backed by native WebContentsViews.
  • Headless tests and harness runs use HeadlessBrowserViewHost.

The renderer measures the actual content area and reports it over meith:browser:viewport; the main process sizes the native view to that region. When settings, overlays, or split-drag drop zones need DOM interaction above the native view, the renderer temporarily collapses the view.

Ownership

Automation callers (agent and plugin) must claim a tab with browser_use_start before mutating it. Interactive callers (renderer, cli) can control unclaimed tabs directly. Ownership conflicts return PERMISSION_DENIED.

Renderer

The renderer is a React and Vite workbench in packages/desktop/src/renderer/src. It uses the preload bridge exposed as window.meith; in browser-only preview mode it falls back to an in-memory mock bridge. Major surfaces include:

  • SpacesRail for switching, creating, opening, closing, and inspecting spaces.
  • TabStrip and PaneToolbar for tab management.
  • BrowserArea for the embedded browser controls and native view target.
  • EditorView for Monaco-backed file editing through workspace_* tools, and TerminalView for PTY sessions.
  • AgentView for session list, transcript, composer, stop button, and permission cards.
  • SettingsView, DebugPanel, and StatusBar for preferences, diagnostics, and connection state.

CLI

The CLI resolves a target runtime from --socket, --instance, live instance records, or ~/.meith/config.json. It sends NDJSON frames to the runtime socket. Common surfaces:

  • meith [path] launches the app and optionally opens a project path.
  • meith new [name] creates and opens a generated project.
  • mapped commands such as open, tabs, navigate, screenshot, and processes call specific tools.
  • meith call <toolName> can invoke any registered tool, and meith tools lists them.
  • meith app <list|logs|health|bug-report|kill|screenshot> inspects or controls runtime instances.