How to keep a project's mini-me files in a .mm folder

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# How to keep a project's mini-me files in a `.mm` folder

This guide shows how to put an agent's configuration, skills, hooks and sessions in a `.mm` folder at the root of a project, instead of beside its source, and still start the agent with a plain `mm` or `mm tui`. It assumes `mm` is installed on your `PATH` and that you already have an `agent.yaml` (written by `mm init`, for example).

## Steps

1. Create the folder and move the configuration into it:

   ```bash
   mkdir -p .mm
   mv agent.yaml .mm/agent.yaml
   ```

2. Write every relative path in `.mm/agent.yaml` **from the project root**, not from `.mm/`:

   ```yaml
   skillsDir: .mm/skills
   sessions:
     enabled: true
     dir: .mm/sessions
   hooks:
     preToolCall:
       - matcher: ^bash$
         command: node "$MM_CONFIG_DIR/.mm/hooks/bash-guard.js"
   ```

   For a file in a `.mm` folder, `$MM_CONFIG_DIR` is the project root, so a hook script in `.mm/hooks/` is named `$MM_CONFIG_DIR/.mm/hooks/…`. The same goes for `mmConfigs`, the deciders of `skillRouting` and `toolRouting`, and `tools[].wasm`.

3. Start the agent from the project root, with no argument:

   ```bash
   mm        # or: mm tui
   ```

   The banner names the file it read:

   ```
   mm … | config: .mm/agent.yaml | provider: …
   ```

## Variants

- **A new agent.** `mm init` does all of this when you answer `yes` to its first question, or with `mm init --project yes`: it creates `.mm/`, writes `.mm/agent.yaml` with paths from the project root and, with `--skills yes`, creates `.mm/skills/`. See [How to create an agent with `mm init`](create-an-agent.md).

- **An `agent.yaml` is also at the root.** It wins: `mm` reads `./agent.yaml` first and `./.mm/agent.yaml` only when there is none. Remove or rename the root file, or name the one you want: `mm -config .mm/agent.yaml`.
- **In a Docker Sandbox.** `mm sbxinit` finds `.mm/agent.yaml` and writes a `sbxenv.yaml` that mounts `.mm/` read-only, its sessions and traces writable; see [When the agent is in a `.mm` folder](run-in-a-docker-sandbox.md#when-the-agent-is-in-a-mm-folder).
- **From an editor (ACP).** Point `AGENT_CONFIG` at the absolute path of `.mm/agent.yaml`. Its paths keep the same meaning: a relative `skillsDir` such as `.mm/skills` is resolved from the project root, not from the editor's working directory. See [How to use mini-me from an editor](use-from-an-editor.md).
- **Started from a sub-directory.** The lookup only looks in the working directory: from `src/`, `mm` does not find `../.mm/agent.yaml`. Start it from the root: in a terminal a relative `skillsDir` follows the working directory, so `mm -config ../.mm/agent.yaml` from `src/` would look for the skills in `src/.mm/skills`.
- **Several agents in one project.** Keep the extra ones in the same folder (`.mm/agents/reviewer.yaml`) and name them with `-config`, or from `mmConfigs` (`reviewer: .mm/agents/reviewer.yaml`). Only a file *directly* in `.mm` uses the project root as its base: the paths inside `.mm/agents/reviewer.yaml` are relative to `.mm/agents/`.

## Requirements

`mm` v1.0.7 or later. An older `mm` does not look in `.mm/`, and resolves the paths of a `.mm/agent.yaml` from `.mm/` itself: `$MM_CONFIG_DIR/.mm/hooks/…` then points to `.mm/.mm/hooks/…`.

When the same agent may run with both — a Docker Sandbox kit often ships an older mm than your machine — write the hook commands with `${MM_CONFIG_DIR%/.mm}`, which drops a trailing `/.mm` and gives the project root with any mm (hook commands run in `sh -c`):

```yaml
hooks:
  preToolCall:
    - matcher: ^bash$
      command: node "${MM_CONFIG_DIR%/.mm}/.mm/hooks/bash-guard.js"
```

A script that builds paths from `MM_CONFIG_DIR` itself needs the same rule: take the parent folder when its last element is `.mm`.

## See also

- The lookup order and the base directory rule: [Configuration file resolution](../reference/cli.md#configuration-file-resolution)
- Every key of the file: [Configuration reference](../reference/configuration.md)
- The variables a hook receives: [Hooks reference](../reference/hooks.md)