Studio Overview
DOT Studio is the primary way to compose, inspect, and run Dance of Tal systems.
Studio is a local visual workspace. It opens a project directory, shows the Performers and Acts you are working with, and runs them through Studio's managed OpenCode sidecar.
Use Studio first when you want to understand or operate DOT assets. Use the CLI when you need publishing, scripted installation, or GitHub Dance management.
Install And Launch#
npm install -g dot-studio@latest
dot-studio .
Common commands:
dot-studio
dot-studio /path/to/project
dot-studio . --performer performer/@acme/agent-presets/reviewer
dot-studio . --act act/@acme/workflows/review-flow
dot-studio doctor .
| Command or Flag | What It Does |
|---|---|
dot-studio | Open the current directory |
dot-studio <path> | Open a specific directory |
open | Explicit open command; default behavior if omitted |
doctor | Check workspace, port, Node.js, and OpenCode readiness |
--performer <urn> | Focus an existing canvas performer or install/import a Registry Performer |
--act <urn> | Focus an existing canvas act or install/import a Registry Act |
--port <port> | Use a custom Studio server port |
--no-open | Start without opening the browser |
If the target directory is not initialized yet, Studio initializes the DOT workspace automatically.
What Studio Shows You#
Most AI tools hide their real setup behind a prompt box. Studio makes the setup visible.
| Area | What You Use It For |
|---|---|
| Canvas | Place Performers and Acts, organize a workspace, select what to inspect |
| Asset Library | Browse local installed assets, Registry imports, drafts, and dependencies |
| Inspector | Edit the selected Performer or Act and inspect its asset cascade |
| Performer Chat | Run one Performer in a standalone thread |
| Act Threads | Run a multi-participant workflow |
| Draft Editors | Author Tal and Dance drafts before publishing or exporting |
The Fastest Useful Workflow#
1. Open a Performer from the Registry#
dot-studio . --performer performer/@acme/agent-presets/sprint
Studio opens the workspace, imports the Performer if needed, and focuses it.
2. Inspect The Performer#
Look at:
- the Tal identity and instruction markdown
- attached
SKILL.mdDances - selected model and variant
- MCP bindings or runtime requirements
- direct/safe mode
3. Start In Safe Mode#
Safe mode runs in a shadow workspace and lets you review changes before applying them. It is the best default for an unfamiliar Performer.
4. Promote What Works#
Once you have a useful local setup:
- keep it as a workspace-specific draft
- turn it into a reusable Performer
- publish stable assets through the CLI
Working With Acts#
Open an Act from the Registry:
dot-studio . --act act/@acme/workflows/incident-response
An Act contains:
- participants: Act-local keys that point at Performer assets
- relations: handoffs and coordination paths between participant keys
- subscriptions: wake signals such as teammate messages, shared board keys, or
runtime.idle - act rules: shared choreography instructions
Use Acts when one role is not enough: planner + implementer, lead + reviewer, incident commander + specialist, and similar workflows.
Workspace State#
A Studio Workspace is saved per working directory. Reopening the same path restores that directory's canvas and local state.
Workspace state can include:
| Component | Description |
|---|---|
| Canvas layout | Positions and arrangement |
| Imported assets | Registry assets pulled into the workspace |
| Drafts | Work-in-progress Tal, Dance, Performer, and Act content |
| Runtime choices | Model selection, mode choices, active threads |
| Act thread state | Collaboration history and participant sessions |
The workspace is local. Publishing is a separate action.
Drafts And Local Authoring#
Studio is useful even before you publish anything.
You can:
- create Tal drafts for persona and rule text
- create Dance drafts with
SKILL.mdcontent - add bundle files such as
references/,scripts/,assets/, oragents/openai.yaml - compose Performers visually from local and imported assets
- build Acts from local Performers
When a draft becomes stable, publish Tal/Performer/Act through dot publish. Dance uses the GitHub export/import flow instead of generic publish.
Direct Mode And Safe Mode#
| Mode | What Happens | Use When |
|---|---|---|
| Direct | Runtime works against the real project directory | small, trusted, easily reversible tasks |
| Safe | Runtime works in a shadow workspace and exposes changes for review | large edits, refactors, unfamiliar assets, multi-file work |
Safe mode changes the target workspace. The same runtime still executes the work.
Studio vs CLI#
| Goal | Prefer Studio | Prefer CLI |
|---|---|---|
| Open and understand a Registry Performer | yes | optional |
| Open and run a Registry Act | yes | optional |
| Compose assets visually | yes | no |
| Review AI edits before applying | yes | no |
| Publish a stable asset | no | yes |
| Add GitHub Dance bundles | sometimes | yes |
| Script onboarding or CI | no | yes |
Next Pages#
| Page | What You'll Learn |
|---|---|
| Performer Composer | How Studio builds a runnable Performer |
| Act Editor & Runtime | How Studio runs multi-performer workflows |
| OpenCode Runtime | What Studio prepares and what OpenCode executes |