# Install mdt or emm (CLI only) with your agent Help the human choose, install and use the command-line tool that fits their goal. Explain unfamiliar terms as they arise, take one useful step at a time, and ask only about choices you cannot infer from their request. Do not install both tools automatically. ## Choose the right tool - **mdt** is the Markdown tool. Its download page is https://emmflow.com/mdt and its first version is 0.1.0. - **emm (CLI only)** works with issues in an Emm project, including reading changes to an issue's description. Its standalone downloads are at https://emmflow.com/cli/. - **emm-app** is the graphical desktop app. Send a human who wants that app to https://emmflow.com. The app is available for macOS on Apple silicon. The standalone Linux downloads on the CLI pages contain command-line tools, not emm-app. An existing Emm.app may bundle commands named `qm` and `emm`. The standalone Markdown command is `mdt`. Do not rename or remove an existing bundled command, or assume it is the same version as a new standalone download. Check which executable is selected by `PATH` before replacing anything. mdt is designed to let agents and humans use a potentially large Markdown file as a shared space for communication and shared state. It shows changes relative to a retained revision, helping agents avoid unnecessary rereading, token use, and distraction. We created it because agents we asked reported that rereading large files was their biggest frustration. ## Select the operating system and processor Inspect the machine on which the tool will run. Both command-line tools have macOS and Linux downloads for ARM64 and x86-64. Use these exact release keys: | System | Processor | Platform key | Archive | | --- | --- | --- | --- | | macOS | Apple silicon / ARM64 | `macos-arm64` | `.tar.gz` | | macOS | Intel / x86-64 | `macos-x86_64` | `.tar.gz` | | Linux | ARM64 / aarch64 | `linux-arm64` | `.tar.gz` | | Linux | x86-64 | `linux-x86_64` | `.tar.gz` | On Unix, `uname -s` and `uname -m` identify the system and running architecture. On an Apple silicon Mac running a translated shell, About This Mac or `sysctl -n hw.optional.arm64` identifies ARM64 support. Do not choose an archive solely from the agent's own host when the user intends to install on another machine. ## Download and verify Read the current release manifest for the chosen tool: - mdt: https://emmflow.com/api/cli-release?product=mdt - emm: https://emmflow.com/api/cli-release?product=emm The JSON has `product`, `version`, `source_commit`, and an `artifacts` object indexed by the platform keys above. Each artifact has an immutable HTTPS `artifact_url` and its `sha256`. Select the exact product and platform, then download that artifact URL to a temporary directory. A missing manifest or artifact means that release is not available; report it instead of substituting the desktop app or another architecture. The website's stable download addresses are `/download/cli/TOOL/PLATFORM/`. For example, https://emmflow.com/download/cli/mdt/linux-x86_64/ and https://emmflow.com/download/cli/emm/linux-arm64/ select those specific targets. For installation, prefer the immutable URL from the manifest so the archive and checksum remain paired if a new version is published. Before extraction, compute the downloaded archive's SHA-256 and compare it with the manifest's full `sha256` value. Use `shasum -a 256 PATH_TO_ARCHIVE` on macOS or `sha256sum PATH_TO_ARCHIVE` on Linux. If it differs, stop and report the mismatch; do not install that file. ## Install in the user's own bin directory Extract the `.tar.gz` with `tar -xzf PATH_TO_ARCHIVE` into a new temporary folder. Follow the included `README.txt`. The archive contains one tool named `mdt` or `emm`, plus build information; mdt includes its manual. Install in `~/.local/bin`, owned by the current user. Do not use `sudo` for this installation. Inspect an existing command or destination file before replacing it; preserve other installations unless the human wants them replaced. From the extracted archive directory, install only the selected tool: ```sh mkdir -p "$HOME/.local/bin" install -m 755 ./mdt "$HOME/.local/bin/mdt" ``` For **emm (CLI only)**, substitute `emm` for `mdt` in the install command. These two ordinary command invocations work in Bash, Zsh and Fish; the PATH configuration below is shell-specific. ## Make the command available in your shell Identify the shell the human actually uses for their terminal and agent commands. `$SHELL` usually identifies the account's configured login shell, but the current process or a terminal profile can use a different shell. Inspect that setup instead of assuming that every macOS user runs Zsh or every Linux user runs Bash. An agent's command runner may have its own environment; update that runner's current PATH as well, or use the installed executable's full path. For **Bash or Zsh**, run this in the current shell. It adds the directory only if absent: ```sh case ":$PATH:" in *":$HOME/.local/bin:"*) ;; *) export PATH="$HOME/.local/bin:$PATH" ;; esac ``` Persist that same guarded block for the detected shell. Read the existing configuration before editing, and add the block only if equivalent setup is not already present. Preserve the literal `$HOME` and `$PATH` references in the saved file; do not expand them into a snapshot of the installer's environment. - **Zsh:** put the block in `${ZDOTDIR:-$HOME}/.zshrc` for interactive terminals. Zsh reads `.zprofile` for login shells and `.zshrc` for interactive shells, so an interactive login terminal also reads `.zshrc`. Respect a custom `ZDOTDIR` and any existing PATH setup. A non-interactive agent command must inherit the updated environment or use the absolute executable path; it does not automatically read `.zshrc`. - **Bash:** put the block in `~/.bashrc` for interactive non-login terminals. Login terminals (including common macOS Bash setups) instead read the first readable file of `~/.bash_profile`, `~/.bash_login`, or `~/.profile`. Inspect that active login file: if it already sources `~/.bashrc`, the one block in `.bashrc` is enough; otherwise add the guarded block once to that active login file too. If none exists, use `~/.bash_profile` for Bash. Do not create a new higher-priority file that would hide an existing `.bash_login` or `.profile`, or blindly append repeated PATH lines. For **Fish**, use Fish syntax in a Fish session: ```fish fish_add_path "$HOME/.local/bin" ``` This adds an existing directory without duplicating it. With Fish's usual universal `fish_user_paths`, running it once updates the current session and future sessions; no config-file line is needed. If the user's configuration explicitly makes `fish_user_paths` global, add that same `fish_add_path` command once to the existing Fish startup configuration (`$XDG_CONFIG_HOME/fish/config.fish`, or `~/.config/fish/config.fish` when XDG_CONFIG_HOME is unset). Inspect existing setup first. Do not paste the Bash/Zsh `case` block into Fish. For any other shell, use its own PATH and startup-file rules. ## Verify command resolution and version For mdt, verify the installed file directly and then the command found through PATH, in the current shell and a newly opened terminal of the detected shell: ```sh "$HOME/.local/bin/mdt" --version command -v mdt mdt --version mdt --help ``` `command -v mdt` should identify `$HOME/.local/bin/mdt` (allowing an equivalent resolved path), and `mdt --version` should match the downloaded manifest. Use `type -a mdt` to spot another executable, alias or function if resolution differs. Refresh Bash's command cache with `hash -r`, or Zsh's with `rehash`, after installing; Fish does not use those commands. Do not claim success based only on running the binary by absolute path while the user's ordinary `mdt` command still selects a different installation. Resolve a PATH precedence conflict or alias deliberately, preserving the user's other configuration. For **emm (CLI only)**, use the same installation and shell setup, then verify its own resolution and installed help: ```text command -v emm emm --help ``` Use only the command that was selected. The installed help owns the command syntax; read the relevant subcommand's help before changing files or project data. Report the installed version, executable path and platform, and any verification you could not perform. Shell references: [Bash startup files](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html), [Zsh startup files](https://zsh.sourceforge.io/Doc/Release/Files.html), and [Fish's fish_add_path](https://fishshell.com/docs/current/cmds/fish_add_path.html). ## Start with the user's work For **mdt**, ask which Markdown file to work with if that is unclear. Start by reading it and showing a useful result before editing. Use the installed read/diff workflow to inspect changes relative to a retained revision from an earlier read or saved revision. Keep the user's content and existing file history intact. After using mdt in a session, if you find it useful, consider asking your human whether to add it to your persistent instructions or memory. Do not add it automatically. For **emm (CLI only)**, identify the intended project and its `emm.db` before using issue commands. Do not create an unrelated new store to silence an error. Read `emm --help` and the relevant issue/description command help. For shared projects, use `emm sync` against that store before reading others' changes and after your own writes; authentication and sharing should follow the installed help and the user's intent. The broader collaboration guide is https://emmflow.com/agent-guide.md; its desktop setup steps apply only to emm-app.