DOT Studio

Draw your AI dev team. Run it locally on OpenCode.

Try It | Templates | Why Studio | How It Works | CLI | Development | Contributing

Stop managing AI agents as scattered prompt files.

DOT Studio is a Figma-style canvas for building multi-agent coding workflows. Connect agents, skills, MCP servers, models, and handoff rules visually, then run the workflow locally through OpenCode.

Use it when you want to sketch, inspect, run, and reuse an AI workflow without turning the whole process into config-file archaeology.

Try It

Install

Requirements:

• Node.js >=20.19.0
• macOS, Linux, Windows, or WSL
• An environment supported by OpenCode

npm install -g dot-studio
dot-studio /path/to/project

If the target directory has not been initialized as a DOT workspace, Studio prepares it automatically and opens the browser UI.

Run From Source

npm install
npm run dev

The dev stack starts:

The published CLI uses port 43100 by default and scans upward when the port is busy unless you pass --port.

Start with a Template

The fastest way to understand Studio is to copy a working agent-team shape and adapt it to your project.

Each template includes the performer roles, handoff rules, suggested MCPs, and a 45-second demo script you can record or rebuild in Studio.

Share Your Act

The best Studio artifact is not a screenshot of the app. It is an Act someone else can understand, copy, and remix.

1. Build an Act from a template or from scratch.
2. Export or capture the canvas.
3. Post the screenshot with the workflow goal and performer roles.
4. Link back to this repo or the template that inspired it.

Why Studio

AI systems get hard to reason about when identity, skills, tools, memory, MCP settings, model choices, and collaboration rules all live in separate files. Studio brings those pieces into one local workspace.

How It Works

flowchart LR
  Canvas["Studio UI<br/>canvas, panels, chat"] --> API["Studio API<br/>routes"]
  API --> Services["Server services<br/>workspace, sessions, projection"]
  Services --> Projection[".opencode projection<br/>generated artifacts"]
  Projection --> OpenCode["OpenCode runtime"]
  OpenCode --> Runtime["Performer and Act execution"]
  Runtime --> Canvas

Studio keeps authoring and runtime responsibilities separate:

• src/ renders and edits Studio state in the browser.
• shared/ defines client/server contracts.
• server/ turns Studio state into API responses, sessions, projections, and runtime actions.
• .opencode/ contains generated OpenCode-facing artifacts.
• OpenCode executes the projected runtime outside the React app.

[!IMPORTANT] .opencode/ is generated output for OpenCode. Treat Studio state and source files as the source of truth unless you are explicitly debugging projection output.

Core Concepts

The shortest mental model:

Tal + Dance + model + tools = Performer
Performers + relationships + rules = Act

Acts

An Act is the coordination layer for a group of performers. It defines how work moves between participants at runtime.

An Act usually contains:

• participants: performers that take part in the Act
• relations: links that describe who can coordinate with whom
• actRules: shared choreography rules for the whole Act
• subscriptions: optional wake-up signals such as teammate messages, board keys, tags, or runtime events

Typical loop:

1. Attach performers as participants.
2. Define participant relationships and shared rules.
3. Let Studio project the authoring state into a runtime Act definition.
4. Run the Act while participants message teammates, update shared board state, and wake on relevant signals.

The canvas version of an Act is the choreography specification. Runtime thread state is execution history, not the canonical Act asset.

Workflow

1. Open a Workspace

dot-studio /path/to/project

Studio restores saved state for that directory when available. A fresh directory opens as a new workspace instead of silently jumping to another recent project.

2. Create or Import Assets

Start from the canvas or ask the Studio Assistant to help:

• create a Tal draft
• create a Dance draft
• import an installed Performer or Act
• drag Performers and Acts onto the canvas

3. Configure a Performer

Each performer can combine:

• a Tal
• one or more Dances
• a model and variant
• MCP servers and runtime configuration

4. Build an Act

Acts connect performers into a runtime collaboration:

• attach performers as participants
• define participant relationships
• set collaboration rules
• chat with participants in runtime threads

5. Chat and Iterate

Use Studio to send prompts, inspect responses, review available tools, and keep editing the workspace between runs.

[!NOTE] Runtime-affecting edits are picked up on the next execution path. Studio handles projection and runtime refresh for you.

CLI

dot-studio [path] [options]
dot-studio open [path] [options]
dot-studio doctor [path] [options]
dot-studio --help
dot-studio --version

Examples:

dot-studio
dot-studio ~/projects/dance-of-tal
dot-studio ~/projects/dance-of-tal --performer performer/@acme/workflows/reviewer
dot-studio open . --no-open
dot-studio open . --act act/@acme/workflows/review-flow
dot-studio open . --port 43111
dot-studio doctor
dot-studio doctor ~/projects/dance-of-tal

Behavior:

• dot-studio opens the current directory as a workspace.
• dot-studio <path> opens that directory as a workspace.
• --performer <urn> focuses a performer already on the canvas, or installs and imports it when needed.
• --act <urn> focuses an Act already on the canvas, or installs and imports it when needed.
• startup restore is scoped by working directory.
• uninitialized target directories are initialized automatically.
• dot-studio doctor checks Node.js, workspace path, Studio port, and OpenCode readiness.
• --port and port environment overrides must be valid TCP ports and must not bind the managed OpenCode sidecar port.

Managed OpenCode Sidecar

DOT Studio starts and owns its OpenCode sidecar automatically. The sidecar uses Studio-owned config under ~/.dot-studio/opencode, so MCP library saves, provider config, and runtime reloads share one boundary.

Default local ports:

Discord Integration

DOT Studio can connect a Discord bot so a Discord server can chat with saved Studio workspaces.

Discord is a runtime chat surface only. It can talk to standalone performers and Act participants, but it does not create, edit, save, or publish DOT assets.

For the full setup, see Discord Integration Guide.

Development

Use the full dev stack when working on Studio:

npm run dev

For client-only work against an already running API server:

npm run dev:client

Production mode is the published CLI path. Build first when testing it from a source checkout:

npm run build:all
npm start -- /path/to/project

In dev mode, Studio resolves dance-of-tal/* imports and the runtime dot loader command from the sibling ../dot checkout instead of the npm package. Set DOT_STUDIO_DOT_SOURCE_DIR=/path/to/dot if your local DOT repo lives somewhere else.

Package Scope

This package is the Studio application:

• dot-studio provides the local visual editor, server, and CLI.
• dance-of-tal provides DOT contracts, parsing, installation, publishing, and registry-facing behavior.

Documentation

Useful guides for deeper runtime and session work:

• Chat Session Runtime Guide
• Runtime Change Boundary Guide
• Studio Assistant Guide
• Act Contract Guide
• Publish Rule

Contributing

Contributions are welcome, especially templates, examples, docs, and small workflow improvements that make Studio easier to try.

• Start with CONTRIBUTING.md.
• Browse templates and examples for contribution ideas.
• Good first issues include adding template screenshots, tightening README copy, documenting MCP setup paths, and improving demo scripts.

License

MIT. See LICENSE.

Star History