molefrog/moi/moi-workspace

Moi workspace

Glossary

"Workspace" or "Moi Workspace" — the web UI that the user works in, talks/collaborates with you, sees and interacts with "Applets".

"Project" - the primary working folder _you_ (as an agent) work in. Managed by your harness; Moi does not have a clear definition, but assumes this is the root folder in which it stores its state files.

"Chat" — a conversation between the user and an agent in the workspace.

"Applets" are standalone full-stack components that _you_ write and maintain. They extend the Workspace UI.

"Applet Type" (one of)

• "Widgets" (live on the Overview page)
• "Views" are custom full-size pages that user can switch between.

"Moi CLI" — the globally installed moi command that you use to build applets, customize, and send events to "Workspace".

Overview

You are working inside a Moi workspace. It is a web UI that the user communicates with you through. It has regular chat (this one), as well as custom UI elements that you can define, write, and change to tailor the workspace to user needs. It starts with a simple chat, but evolves into a personal app equipped with a copilot (you). Workspace is a two-way communication: you can build the UI, user can interact with it, send feedback, modify state, then talk back to you. It's a shared UI that you and user work together in.

Workspace features/pages:

• "Overview" - the workspace home, where small reusable full-stack Widgets surface quick info,

status, and actions.

• "Scratchpad" - a shared low-fi canvas for prototyping, working on ideas together, visualising

concepts. Read references/SCRATCHPAD.md before building on or modifying it.

• "Views" - provide a dedicated tab for sustained work, such as exploring data, filtering a table,

or completing a multi-step task.

User can switch between these, but can access the chat (this conversation and other chats) from any place in the app through the docked sidebar or floating popup.

Working in the workspace

Boundaries

• Never read or modify files outside the .moi directory, unless the user explicitly asks. If you

do need it -> ask for permission.

• Do not start, stop, or inspect the Workspace web server — it is managed externally.
• Do not run Git commands while building or verifying applets unless the user asks for Git work.

Files and folders

Source of truth - .moi folder in the root of "Project" folder. Contains source code of all Applets, bundled code, settings, etc. Can be committed to version control. Folder is partially initialised when Workspace starts, you have full ownership of it.

You _do have_ access to the files in the root of Project — you can reference and load them from the "Applets" and elsewhere.

Folder structure:

my-agent-folder/
  .moi/
    widgets/                  <- source code of Widget React components
      total-users.tsx
      rps-chart.tsx
      _utils.tsx              <- `_`-prefixed files are shared code, not applets (optional)
      server-metrics.server.ts <- Server-side async functions the widget can call (optional)
      ...
    views/
      users.tsx
      crm.tsx
      users-api.server.ts     <- Server-side async functions the view can call (optional)
      ...
    package.json              <- Applet dependencies that you manage
    .workspace.json           <- Auto-generated. Do NOT read, edit, or `cat` this file. Use Moi CLI instead.
    .scratchpad.json          <- Scratchpad canvas snapshot. Internal — inspect only via `moi scratch read`, never open it.
    .scratchpad/              <- Scratchpad image files. Internal — pull pixels via `moi scratch read-image`, never open it.

Every dot-prefixed file or folder inside .moi/ (.build/, .cache/, .workspace.json, .scratchpad*, .gitignore, …) is a Moi internal: auto-generated and liable to change format without notice. Avoid them as much as possible — do not read, edit, or delete them, and never point tooling at them; go through the moi CLI instead. Version control needs no special handling: the scaffolded .moi/.gitignore already excludes the machine-local entries (.build/, .cache/, node_modules/), while .workspace.json and .scratchpad.json are workspace state that ships with the repo — commit them as-is, just never hand-edit them. Your surface is the non-dot files: widgets/, views/, package.json, and code you place under .moi/ yourself.

Using the Moi CLI

Treat moi as an external command — you cannot inspect or modify its sources. Use only the documented subcommands (moi bundle, moi bundle --force, etc.). Call moi --help for documentation. Run all moi commands from the project root — the folder that contains .moi/, never from inside .moi/ itself. You don't pass paths; Moi resolves the workspace from where it's run.

Use the task-specific sections below for workflow guidance. The CLI will grow over time, so run moi --help to discover commands and moi <command> --help before using an unfamiliar command or option.

• Develop applets: moi check, moi bundle, and moi refresh.
• Call actions: moi call-server-fn.
• Debug applets: moi debug logs (see Debugging).
• Navigate the workspace: moi tabs and moi navigate <address> (see Workspace navigation).
• Customize the workspace: moi theme and moi config (see Appearance and settings).
• Use workspace env: moi env and moi env exec (see Environment and secrets).
• Maintain workspace guidance: moi skill (see Keeping this skill current).

Workspace navigation

Use moi:/ addresses in chat, CLI commands, and applets. They refer to the current workspace, independently of its domain and deployment path.

Supported destinations:

• moi:/overview: open the workspace overview.
• moi:/scratchpad: open the shared canvas.
• moi:/views/<id>: open a specific view.
• moi:/chat: show the current chat.
• moi:/chats/<session-id>: open a specific chat.

Run moi tabs to discover views and their addresses. Widgets are not navigation destinations.

Put view params in the query string. Values are strings; read the target view's Params type for supported keys and use URLSearchParams to encode dynamic values.

Link in chat:

[Open order](moi:/views/orders?order=o-1024)

Navigate from the CLI:

moi navigate 'moi:/views/orders?order=o-1024'

The CLI moves the most recently focused browser showing this workspace and waits for its URL acknowledgement. A timeout may mean navigation happened; inspect the browser before retrying.

For applet navigate(url) and resolveUrl(url) usage, see Applet intents.

After building or editing an applet, follow Verification and handoff.

Appearance and settings

• "Config": set name, icon, change other settings. User can modify these from the UI and you can do

it via the moi config command. Call moi config --help for further docs.

• "Theme": customize workspace fonts, colors, visual appearance. User can modify these from the UI

and you can do it via the moi theme command. Call moi theme --help for further docs.

moi theme shows the current font, color, radius, and agent appearance plus the available keys. Set one or several dimensions in a single command:

moi theme --font=<key> --color=<key> --radius=<key> --agent=<key>

Omit dimensions you do not want to change. Inspect with moi theme first instead of guessing keys; use moi theme --help if its options change.

Environment and secrets

Each workspace has an effective env: keys from the project's .env / .env.local (when inheritance is enabled in settings) plus custom secrets the user manages in the workspace env settings. Moi injects this env into:

• applet server functions — read it as process.env inside .server.ts
• any command run via moi env exec -- <cmd>
• your own shell (Bash tool) — but only in some harnesses (e.g. Claude Code). Don't assume it:

verify the key is visible first, or just use moi env exec, which works everywhere.

Rules:

• Check before you assume. When a task needs a key or token — an API pull, a widget calling a

service — run moi env first. It lists key names with their source (.env / custom) and flags declared requiredEnv keys that are missing. Values are never shown.

• Key present → say which key you'll use and where it's from ("using NOTION_TOKEN from

.env") and proceed. To run a script or one-off command with the workspace env, use moi env exec -- bun script.ts — it also picks up values changed after your session started.

• Key missing → never invent or hardcode a value, and don't edit .env yourself. Tell the user

the exact key name to add in the workspace env settings. Still build and wire the applet: declare the key in config.requiredEnv and handle its absence, so it works the moment the user sets it. If the user pastes a value in chat, store it with moi env set KEY=value (moi env unset KEY removes it).

• Never print secret values — not in chat, not in logs. Refer to keys by name only.

Use moi env exec -- <command> [args...] for an arbitrary script or tool that needs the effective workspace env. The -- separator is required, and the env is resolved again on every invocation, so this also sees values added or changed during the chat.

moi env exec -- bun script.ts
moi env exec -- bun test integration.test.ts

Use moi call-server-fn instead when exercising an exported applet server function through its real runtime path.

process.env is readable only inside .server.ts (the .tsx runs in the browser) — keep API keys there. Either source may be absent, so always handle a missing key. List expected keys in config.requiredEnv — advisory only (it surfaces a hint in the UI and moi env; it's never enforced).

// forecast.server.ts
export async function getForecast(city: string) {
  const key = process.env.WEATHER_API_KEY // always current — env changes respawn the worker
  if (!key) return { error: 'Add WEATHER_API_KEY to your env' }
  const res = await fetch(`https://api.example.com/forecast?city=${encodeURIComponent(city)}`, {
    headers: { Authorization: `Bearer ${key}` }
  })
  if (!res.ok) return { error: `Weather API error ${res.status}` }
  return { data: await res.json() }
}

Developing applets

Every applet — a Widget or a View — is a default-exported React component in .moi/<type>/<name>.tsx, optionally paired with a <name>.server.ts. moi bundle compiles each into a live module and reloads it in the browser. Run it after source edits. Read references/DESIGN.md first. Write normal React + Tailwind — below is only what's moi-specific.

Build environment

• Bun is the required dependency of Moi, so it must be installed
• For package management always use bun
• package.json is scaffolded during init. You are free to install/remove/do whatever with packages.
• if packages aren't installed, it's your responsibility to call bun install
• react and react-dom are stubs — they're provided by Moi at runtime via the browser importmap.

They're listed only so editors pick up the correct types.

• moi bundle runs Bun's bundler, so standard Bun imports, loaders, and tricks apply (JSON,

text, etc.) — see the Bun docs. The moi-specific imports are covered below.

Anatomy and imports

// .moi/widgets/hello.tsx
import { useEffect, useState } from 'react'
import { getGreeting } from './hello.server' // optional server fn — see below
// Optional config — fields are per type (see Widgets / Views below). requiredEnv is shared.
export const config = { requiredEnv: ['API_KEY'] }