---
title: Mochi Help & Getting Started
url: https://www.trymochi.dev/docs
---

# Start with one calm folder.

The safest way to adopt Mochi is to begin narrowly, inspect the review queue, and expand only after the rules behave the way you expect.

## Install Mochi

- Download the current DMG from GitHub Releases.
- [Verify its SHA-256 checksum and release details](https://www.trymochi.dev/security).
- Open the DMG, move Mochi to Applications, and launch it.

If macOS reports a developer or notarization identity that does not match the canonical release, stop and compare the checksum and release notes. Avoid copies from download mirrors.

## Add your first watched folder

Choose a low-risk folder such as Downloads. macOS will ask you to grant access. Mochi cannot work outside the locations you authorize. You can remove a watched folder from the app without deleting the folder itself.

Keep the first scope small enough to inspect. If the destination sits outside the watched folder, authorize that destination when prompted. Removing access later prevents new operations but does not reverse moves you already approved.

## Create a narrow rule

Start with an obvious match, such as sending `.dmg` and `.pkg` files to an Installers folder. Keep review enabled while testing. Check the explanation for each proposed move before approval.

Name the rule after its outcome, such as “Installers from Downloads.” If unrelated files match, add a condition or reduce the watched scope. Prefer several readable rules to one large condition that is difficult to explain.

## Use the review queue

Review separates matching from moving. Confirm the filename, proposed destination, and reason. Reject an incorrect suggestion and adjust the rule before processing similar files. AI suggestions use the same review path and cannot approve themselves.

## Undo a move

Open History, find the operation, and choose Undo. Undo depends on the source and destination still being available and on avoiding a collision with a newer file. Mochi will not silently overwrite another file.

If Undo is unavailable, locate the file using the recorded source and destination rather than forcing the operation. History is stored locally and provides an explanation of what Mochi did.

## AI is optional

Ordinary rules work offline and require no account. If you enable AI, review the provider and privacy settings first. Use local Ollama when you do not want file descriptions sent to an external provider.

For an external provider, Mochi prepares limited metadata and an excerpt only when a rule cannot decide. Common email addresses, phone numbers, and long number strings are redacted locally. See [the full data flow](https://www.trymochi.dev/privacy) and [model evaluation policy](https://www.trymochi.dev/ai-safety).

## Troubleshooting basics

### A folder is not updating

Confirm it still appears under watched folders and that the folder has not been moved, renamed, disconnected, or denied in macOS privacy settings.

### A rule matches too much

Disable the rule, reject pending moves, and add a more specific condition. Test again in review mode.

### A destination already contains the filename

Mochi stops rather than silently overwriting. Rename one file or choose another destination, then review the operation again.

## Get support

Read the [project README](https://github.com/jerrysun-ofive/mochi/blob/main/README.md), inspect [known issues](https://github.com/jerrysun-ofive/mochi/issues), or email [trymochi.dev@gmail.com](mailto:trymochi.dev@gmail.com). Include the Mochi version and macOS version, but do not email private file contents.

The [feature guide](https://www.trymochi.dev/features) describes the major controls, while [the workflow guide](https://www.trymochi.dev/how-it-works) provides a complete first setup.

## Before changing a working setup

Export or record important rule conditions, confirm backups are current, and test destination changes with review enabled. Treat a renamed or disconnected external drive as a changed destination rather than assuming an old bookmark still points to the intended place.