# 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 the bundled `emm` CLI for issues and chat, and `qm` 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.

## 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. For Google/passkey sign-in and sharing, install the [latest build](https://emmflow.com/download/?channel=latest); it contains the matching browser authentication flow. If this is not a supported Mac, explain that before proposing installation.
2. **Open or create a project.** In Emm, choose an existing project, **Add local project** for a folder that already has `emm.db`, or **Create new project** for the folder where this work belongs. This is usually the code repository. Creating a project does not require creating a new repository. If the human has a shared-project invitation, use **Join a shared project** instead of creating an unrelated local copy.
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
```

Current latest builds also bundle the Markdown command-line tool:

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

Read `qm`'s help before editing a note. By default it shares Emm Notes' local state and write locks under `~/.emm/notes`. `EMM_HOME` relocates Emm's state directory; an absolute `QM_STATE_DIR` overrides the CLI's notes state for isolated use. A separate state directory does not share the app's write locks.

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.

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

Local work needs no account. When the human wants to share, Emm first asks them to **Sign in to Emm**, using Google or a passkey in their browser. Recipient addresses come later. Signing in does not publish a local project; **Create Project on Cloud** is a separate action.

A new passkey account requires one email verification and a saved passkey before it becomes active. A private invitation email can supply that verification for a new account, so **Create passkey and join** needs no second email. Open that private link in the human's browser; never paste its secret into an issue or agent prompt. An owner-copied invitation code identifies the project and recipient but does not prove identity. An existing account uses its allowed sign-in method before joining.

Passkeys saved in a configured password manager can be available on another Mac. A nearby phone can also approve a sign-in without copying its passkey to that Mac. If no credential is available, use **Can't use your passkey?** for deliberate email recovery and a replacement passkey. Only a project owner can require Google for that project. Connecting Google does not disable the account’s passkeys. Email recovery and passkeys can restore unrestricted-project access but cannot bypass project SSO. 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.

The CLI follows the same human approval flow. 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, so the human can use a passkey where allowed. A deliberate Google choice in the native app opens Google directly. `--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. The resulting saved CLI access reaches one project. The app can restore explicitly named, already-linked projects for the same account in one ceremony, saving a separate credential for each. Both show a matching device code for the human to compare with the browser; no code entry is required. Keep the private verifier and credentials out of issues and messages.

A linked folder keeps its original account. `emm auth login EMAIL` restores that account's access; choosing a different email does not transfer the folder. Use a separate empty folder for another identity. **Sign Out on this Mac** keeps files and unsent work. Revoking device access stops further cloud access but cannot erase downloaded copies. See [Emm's privacy information](https://emmflow.com/privacy/) for account and credential handling.

## When something gets in the way

- **`emm` or `qm` is not found:** use the executable inside Emm.app. Current latest builds offer **Add it to path** at startup and in **Emm → Settings → Command-line tools**, installing links for both commands in `/usr/local/bin` and the `qm` manual. macOS may ask for authentication. **Not now** changes nothing; Settings lets you try later. Open a new terminal afterward. Custom shell paths must include `/usr/local/bin`; a command earlier in PATH can take precedence. Emm does not edit shell profiles. Older builds may not yet bundle `qm`.
- **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 without the app running, the agent uses `emm sync` before reading others' changes and after its own writes.
- **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.