Quickstart

This walks through Mochi's core loop on a repo you already have: find what you can run, run it, and remember what happened.

It assumes you have installed Mochi.

1. Register a workspace

A workspace is a directory Mochi knows about. It is flow's concept, and it works the same way in both tools:

cd ~/code/my-project
mochi workspace add my-project . --set

flow conceptWorkspaces

What a workspace is, how flow.yaml configures it, and how to manage several.

2. Find what you can run

Discovery scans the workspace for task files it recognizes: Makefile targets, npm scripts, Justfile recipes, Taskfile tasks, Compose services, scripts, and more.

mochi discover --dry-run   # preview what would be found
mochi discover             # surface it

Nothing is written into your repo. See Discovery for the full list of providers and flags.

3. Find it again, from anywhere

Search ranks results by name match, favorites, and how often and how recently you've run something:

mochi search build

4. Run it

Discovered tasks and flow executables run the same way: the verb is the command, followed by the executable's reference (workspace/namespace:name). mochi search prints each result's full reference.

mochi build my-project/<namespace>:<name>

flow conceptExecutables & references

How verbs, workspaces, namespaces, and names combine into an executable reference.

5. See what happened

mochi logs          # flow's run history
mochi stats         # success rates and busiest tasks, per workspace

If a run failed, ask Mochi why:

mochi ai diagnose <run-id>

AI is optional and needs a provider. See AI to set one up, including fully local models.

6. Open the desktop app

mochi desktop

Everything above is also in the app: press ⌘K to search, open an executable to run it, and use the Runs page for history.

Next

• Discovery, in depth
• The desktop app
• AI