# Emm for your agent

Help the human achieve something they care about, starting with one useful piece of work. This guide introduces Emm and the collaboration pattern behind it. Teach a little, take the next useful step, and adapt to what the human already knows. Do not read this whole guide back to them or turn setup into a questionnaire.

## Start with their goal

If you do not already know, ask what they want to accomplish and which project folder they want to use. Explain unfamiliar terms as they arise. An experienced developer may only need the setup commands; a new user may want you to guide them through the app.

Emm is a fast, local task manager and Markdown notes app for macOS on Apple silicon. The human uses the app; their agent uses `emm` for issues and the standalone `mdt` tool for Markdown notes. Both work with the same files and issues. Emm complements coding agents such as Codex and Claude Code: it gives the work and its feedback a durable home. It does not run the agent for you. Keep the agent session running in its own app or terminal.

Local use needs no Emm account. Tasks live in `emm.db` in the project folder; Markdown notes remain files. An issue holds a desired outcome, context, discussion and status. Its status tells you whose turn it is. A team groups issues within a project; the first project already has one, so no organization setup is needed.

For a terminal or agent on macOS or Linux, [standalone CLI downloads](https://emmflow.com/cli/) provide `mdt` and `emm` for ARM64 and x86-64. Follow the [CLI installation guide](https://emmflow.com/cli-agent-guide.md) to select and verify the matching archive, install in `~/.local/bin`, and configure the user's shell without duplicate PATH entries or unnecessary `sudo`. Verify command resolution, then run `mdt --version` and `mdt --help`, or `emm --help` for the issue CLI. The Markdown tool has [its own download page](https://emmflow.com/mdt). These downloads install the command-line tools; the desktop app remains available for macOS on Apple silicon. The app setup below applies when the human is using that desktop app.

A project is a folder containing `emm.db`, which holds its issues and teams. It is not a Git repository: the folder can contain one repository, several repositories, or no code. Creating an Emm project does not create or clone a repository. Choose the folder that should own this collection of work. Notes use a configurable folder; when switching projects, the human can switch Notes too or keep the current Notes folder.

## Get to the first useful task

1. **Install only if needed.** Use https://emmflow.com/download/, open the disk image, and drag **Emm.app** into Applications. The default download is stable; the [latest channel](https://emmflow.com/download/?channel=latest) is also available. If this is not a supported Mac, explain that before proposing installation.
2. **Open or create a project.** From **Emm → Switch Project…** or **Cmd+Shift+O**, choose **All projects…** to reach the **Emm Project List**. Under **Add project…**, choose **Open an existing local project** for a folder that already has `emm.db`, **Create new project** for a new local store, or **Open an Obsidian vault** to use its existing folder in place. Adding or creating a local project returns to the list; select it there to open it. If the human has a shared-project invitation or membership, use **Join a shared project** or account sign-in to discover it instead of creating an unrelated local project.
3. **Connect this conversation.** With the intended project open, choose **Emm → Copy Agent Prompt**, paste into the existing coding-agent conversation, and send it. This names the actual installed command and project store. If you are already that agent, load those local instructions and keep helping here.
4. **Prepare one issue together.** Give it a concrete title, the result the human wants, relevant constraints, and a simple way to tell whether it worked. A screenshot or exact error helps with a bug. Agree on any reduced scope: a mockup is useful when the human wants one, but label simulated actions honestly rather than claiming a real result. Keep uncertain ideas as Draft. When the human is ready for you to act, they set the issue to Open.
5. **Finish one loop.** Work the issue, let the human try the result, and adjust from their feedback. Then prepare the next few ready issues. A long backlog can wait; start with enough ready work to make progress without repeated chat prompts.

Do steps you can perform in the human's environment yourself. Do not claim to have installed, created or changed anything without doing it. If you lack local command access, say so and guide the human through the app; do not pretend a chat-only session can operate their project.

## A collaboration pattern to try

The human sets the goal, priorities and constraints. The agent owns routine implementation, verification and integration. Give the agent discretion for easily reversed choices; ask the human about consequential, ambiguous product decisions. Match the scope they gave you instead of treating every item on the board as permission to begin.

Keep each task's questions and answers in its issue, where the next session can find them. When asking for input, state the decision or action needed and, when helpful, your recommendation. Report results concisely: what changed, whether it is available to try, and anything the human needs to decide. Routine successful checks belong in technical logs, not a repeated release checklist.

| Status | Next step |
| --- | --- |
| Draft | The human is still preparing it. Leave it alone. |
| Open | Ready for an agent to start or resume, in priority order. |
| In Progress | Reserved for its working agent, even with a blank assignee or old timestamp. Resume your own work; otherwise the human must establish ownership and explicitly reassign it. |
| Needs Input | Ask the specific question, then take other ready work. The human answers and sets it to Open when ready. An edited answer alone is not a start signal. |
| Blocked | Name the external dependency that prevents progress. |
| Completed | Integrated, verified and ready for human review, including any required release and branch/worktree cleanup. |
| Accepted / Cancelled | Finished. Only the human sets these unless they delegate that authority. |

For example: the human opens “Make the signup form usable on a phone,” with a screenshot and acceptance criteria. The agent takes it In Progress. If a consequential choice needs the human, the agent explains it and sets Needs Input. The human answers, finishes editing, and sets Open. The agent resumes, delivers a result the human can try, and marks Completed. The human accepts it or adds feedback and returns it to Open.

Start with one working agent. If the human wants parallel work, assign distinct issues before work begins; two agents reading the same Open queue can choose the same issue. A coordinator or the human should allocate the work. A blank assignee does not prove an In Progress issue is abandoned: check who is working before reassigning it. If a session must end with unfinished work, record what remains and any branch or worktree so its next owner can resume deliberately.

For a new session, use **Copy Agent Prompt** again. Current issues are the source of task state. The installed workflow explains when a short `SESSION_HANDOFF.md` is useful; it is optional, not a document to rewrite after every task.

## For the agent operating Emm

The installed version is authoritative for commands. Read its help, then the relevant subcommand's help; do not guess flags or edit `emm.db` directly. The usual executable is:

```sh
/Applications/Emm.app/Contents/MacOS/emm --help
```

For Markdown notes, install the standalone `mdt` tool using the [CLI installation guide](https://emmflow.com/cli-agent-guide.md), then read its help:

```sh
mdt --help
```

Read the installed help before editing a note or changing state-directory settings. The default notes state is under `~/.emm/notes`; a separate state directory does not share the app's write locks. Older Emm.app releases may bundle the predecessor command named `qm`. Keep existing installations intact and check command resolution; do not rename an older bundled executable to `mdt`.

Use the actual path from Copy Agent Prompt if Emm is installed elsewhere. Read `emm agent --help`, then run the supplied `agent prompt` command for the current local workflow. Use its explicit `--store` path on project commands. For command-line project setup, read `emm project create --help` first. For issues, start with `emm issue --help`; append discussion with `issue note`, rather than replacing a description the human may be editing. Each note carries a stamp line with the UTC date and time and the writer's name, so the human can tell what happened before or after a release; text added any other way starts with the same line.

Without `--store` or `EMM_STORE`, the CLI looks for the nearest `emm.db` in its working directory or a parent folder, then falls back only when there is exactly one usable known project. Switching projects in the app does not retarget a terminal or an existing agent command. Keep using the intended store explicitly, especially when working in several repositories or projects.

This website can be newer than an installed app. If a command is unavailable, use that version's help and check **Emm → Update Emm**. Repository instructions such as `AGENTS.md` supply the project's own build and release rules.

## Share only when it helps the work

In the native app, four actions have separate effects:

| Action | What it does |
| --- | --- |
| Sign in to Emm | Saves account access and discovers accepted memberships and pending invitations. Returns to the Project List. It can reconnect existing copies that already use that account. |
| Accept or reject an invitation | Acts on that invitation for its recipient. Accepting adds the project to the list without downloading or opening it. |
| Open a shared project | Shows its account, local folder and Notes choices. **Download and open project** creates a missing local copy; **Switch project** opens an existing copy. |
| Create a project on the cloud | Explicitly publishes a local project after verification. Ordinary account sign-in does not publish it. |

The Project List separates **Authenticated accounts**, **Pending invitations**, and **Project list**. An outstanding invitation is not yet a project membership. Signing in with another account keeps existing accounts and each local copy's selected identity. A saved credential for one project does not grant account-wide discovery: if projects or invitations are missing, sign in to that account from the Project List. Do not treat old project-list entries as proof of current membership.

Native **Sign in to Emm** offers Google or **Continue with email / passkey**. Google uses the default browser; native passkeys use macOS's authentication sheet and communicate directly with Emm's relay. Continuing with email/passkey tries an available passkey and falls back to email verification when needed. Typing an email alone does not send a message or launch a sign-in sheet. After verification, the app can offer to save a passkey; **Skip passkey, I'll stick with email** is supported.

To share a local project, use **Create cloud account for PROJECT** from the Emm menu, or **Create Project on Cloud** where offered. This has its own verification flow, even if an account is already signed in for project discovery. Once published, use **Manage Users** to invite collaborators.

A private invitation email can supply inbox verification for a new account, avoiding a second verification email. The landing page offers downloading Emm or continuing in Emm; signing in still leaves the invitation for an explicit Accept or Reject in the Project List. An existing account authenticates normally. An owner-copied invitation code identifies the project and exact recipient but does not prove ownership of that inbox. Open private links in the human's browser; never paste their secrets into an issue or agent prompt.

Only a project owner can require Google for that project. Google is then required to accept its invitation or obtain cloud access; email verification and passkeys do not bypass that requirement. Connecting Google does not disable the account's passkeys. Google-derived access depends on continuing Google authorization; a failed Google grant does not revoke independent passkey access to unrestricted projects. Invitations and new accounts do not support email `+` tags; do not silently remove a tag or substitute another address.

A shared download contains Emm project data; it does not clone the code repository. The app normally uses `~/Emm/PROJECT` and lets the human choose a folder. It reuses a matching linked copy at that default path, preserving its selected account; another project's database is not overwritten. For a copy elsewhere, use **Open an existing local project**. Removing a project from the list only forgets the entry; it does not delete the folder, revoke membership or sign out.

In project details or **Account for this project…**, the human can explicitly choose another relay-confirmed eligible account for that local copy. Merely signing in never makes that choice. The last-used identity remains available for local work without cloud access. Detached copies cannot reconnect in place; keep their edits and download a separate copy if needed.

Native **Sign out** forgets the selected account's access across Emm on this Mac, keeping other accounts signed in. It preserves local files, unsent work and each copy's last-used identity. It does not lock downloaded data, delete passkeys or sign out of Google in the browser. Revoking cloud access cannot erase downloaded copies. See [Emm's privacy information](https://emmflow.com/privacy/) for account and credential handling.

## Shared projects from the CLI

The CLI has project-scoped commands and browser approval. Read `emm project publish --help`, `emm project join --help`, or `emm auth login --help` for the intended operation. Current builds offer `--method google` (the default), `passkey`, `create`, or `recover`. The CLI's Google-default request keeps a browser method chooser. `--no-browser` prints a separate device approval link and code for a human to open elsewhere; keep that command running while they approve. Do not ask for their Google password, passkey or emailed secret. Keep verifiers and credentials out of issues and messages.

`emm project join --invite CODE` explicitly accepts that invitation and downloads its project after approval. Joining by project ID requires existing membership. Use the installed help for destination and folder checks; private emailed invitation links belong in the browser, not the `--invite` argument. The saved CLI credential reaches one project and does not replace the app's account sign-in for discovery.

`emm auth login EMAIL` restores the linked copy's selected account; it cannot switch its identity. Use the app's account chooser for that. `emm auth logout` clears all saved account and project credentials in its selected `EMM_HOME`, whereas native sign-out affects one account. Both preserve local files and identities.

## When something gets in the way

- **`mdt` or standalone `emm` is not found:** follow the [CLI installation guide](https://emmflow.com/cli-agent-guide.md) to check `~/.local/bin`, the current PATH and the detected shell's startup files. Verify the command in a new terminal as well as the current session. A command, alias or function earlier in resolution can take precedence.
- **The app's bundled `emm` is not found:** use its full path inside Emm.app or the path from **Copy Agent Prompt**. App builds may offer **Add it to path** or **Emm → Settings → Command-line tools** for bundled commands; follow that installed version's instructions. This is separate from installing standalone `mdt` in the user's own bin directory.
- **Wrong project or no project:** open the intended project and copy its agent prompt again. Do not create a second store just to make an error disappear.
- **The agent does not resume:** confirm the issue is Open and within the agreed scope, then continue the existing agent session. Emm does not wake a stopped session when a status changes.
- **Sharing with another person:** local use can stay local. When sharing is wanted, use Emm's invitation flow and the installed `emm project --help`. For a shared project, use `emm sync` against its store before reading others' changes and after your own writes. An app open on another project does not keep this one synced.
- **An Emm problem:** capture what happened, the expected behavior and the app version. `emm feedback --help` explains how to send feedback to Emm's makers.