Start here
Core concepts
Understand projects, threads, agents, flows, runs, tasks, artifacts, and workspaces.
Projects
A project is the top-level container in the sidebar. Motriz supports two kinds:
- Code projects point at an existing local directory. The directory may or may not be a Git repository.
- Ventures hold the founder journey, co-founder conversation, evidence, documents, decisions, and later build work. A venture can begin without a repository.
Removing a project deletes Motriz's project record, threads, messages, and run history. It does not delete the underlying folder or repository on disk.
Threads
A thread is a durable conversation inside one project. It stores the selected mode, messages, run history, attached artifacts, uploads, and any folder placement. Threads can be renamed, archived, deleted, or moved between sidebar folders.
Deleting a sidebar folder does not delete its threads; Motriz moves them back to the top level. Deleting a thread permanently removes its Motriz conversation data and is unavailable while that thread is running.
Modes
| Mode | Designed for | Repository behavior |
|---|---|---|
| Chat | Discussion, brainstorming, analysis, and research. | Reads repository context and can create artifacts, but does not edit repository files. |
| Build | Implementation, fixes, refactors, tests, and code review. | Agents have full repository and command access. |
| Product Design | Specs, product flows, UI exploration, prototypes, and build prompts. | Uses the repository as read-only context and writes outputs to the artifact workspace. |
| Co-founder | Venture discovery, evidence, checkpoints, strategy, and build readiness. | Owns one durable venture conversation and can bring in founder specialists. |
Motriz does not stop Build agents for per-command approval. Choose the mode intentionally and point Build only at repositories you are comfortable letting an agent modify.
Agents and roles
An agent execution combines a provider, model, reasoning effort, optional Fast tier, and role. Roles add task-specific behavior such as Coder, Planner, Heavy Planner, Reviewer, System Architect, Product Specialist, Product/UI Designer, or Co-founder.
The same Build role can be used with different providers. This makes flows provider-neutral: a Planner can be Claude in one flow and Ollama in another, while keeping the planning contract.
Single-agent runs
A new Build thread defaults to one agent. This is the simplest and often the best execution model: the selected agent receives the conversation, project context, role instructions, and tools, then runs until the task completes or you stop it.
A run timeline records status, provider, model, elapsed time, usage, estimated cost when the provider reports it, nested research or sub-agent activity, and completion or error state.
Flows
A flow is an optional pipeline of independently configured steps. Steps can run sequentially, execute a plan, fan out into parallel branches, or loop back when a reviewer has not approved the result.
Flows are reusable configuration. Runs are the concrete executions of that configuration inside a thread.
Tasks and the queue
Project tasks are durable dashboard items, separate from ad hoc thread messages. A task can be created manually, promoted from a Product Design build prompt, or seeded by a venture handoff.
- Assign one agent configuration or a flow.
- Keep work in the backlog, queue it, or run it immediately.
- Run independent tasks in parallel isolated worktrees.
- Pause, resume, retry, edit, or remove tasks.
Artifacts
Artifacts are outputs meant to remain useful after a message scrolls away. They can be specifications, documents, plans, prompts, research, briefs, images, links, arbitrary files, or multi-screen HTML prototypes.
Artifacts live in Motriz's app data rather than being silently written into the repository. They retain project, thread, run, and version provenance. Suitable prompts can become dashboard tasks, and suitable artifacts can start a Build thread.
The workspace
The workspace is the inspection surface beside or in place of chat. Its tabs adapt to the active project stage:
- Code: Files, Changes, Artifacts.
- Venture journey: Journey, Artifacts, Documents, Evidence.
- Venture building: Files, Changes, Artifacts, Documents, Evidence.
- Stopped venture: Artifacts, Documents, Evidence.
Local state and remote boundaries
Motriz stores project metadata, SQLite data, messages, artifacts, uploads, provider configuration, and voice models locally. Data leaves the machine when you deliberately invoke an AI provider, search engine, integration, Git remote, GitHub workflow, or update download. See Privacy and safety for the exact boundaries.