> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory

> Agent directory CRUD — add, remove, list, and edit agent registrations.

# Directory Commands

Agent directory management — register, remove, list, and edit agent entries.

## `genie dir add`

Register an agent in the directory.

```bash theme={"dark"}
genie dir add <name> --dir <path> [options]
```

```bash Terminal theme={"dark"}
$ genie dir add sofia --dir ~/agents/sofia --model opus --roles engineer,reviewer
Agent "sofia" registered (project).
  Dir: ~/agents/sofia
  Prompt mode: append
  Model: opus
  Roles: engineer, reviewer
```

### Options

| Flag                   | Description                                  | Default      |
| ---------------------- | -------------------------------------------- | ------------ |
| `--dir <path>`         | Agent folder (CWD + AGENTS.md)               | **Required** |
| `--repo <path>`        | Default git repo                             | —            |
| `--prompt-mode <mode>` | Prompt mode: append or system                | `append`     |
| `--model <model>`      | Default model (sonnet, opus, codex)          | —            |
| `--roles <roles...>`   | Built-in roles this agent can orchestrate    | —            |
| `--global`             | Write to global directory instead of project | —            |

## `genie dir rm`

Remove an agent from the directory.

```bash theme={"dark"}
genie dir rm <name> [--global]
```

```bash Terminal theme={"dark"}
$ genie dir rm sofia
Agent "sofia" removed from project directory.
```

<Warning>
  `genie dir rm` only removes the registry entry — the agent folder on disk is untouched. If the agent has active sessions or team memberships, stop those first (`genie stop <name>`, `genie team fire <name>`) before removing the entry, otherwise dispatch commands will fail to resolve it.
</Warning>

## `genie dir ls`

List all registered agents or show details for a specific agent.

```bash theme={"dark"}
genie dir ls [<name>]
```

```bash Terminal theme={"dark"}
$ genie dir ls
AGENT     DIR                    MODEL    ROLES              SCOPE
sofia     ~/agents/sofia         opus     engineer,reviewer  project
marco     ~/agents/marco         sonnet   engineer           global

$ genie dir ls sofia
Agent: sofia
  Dir:         ~/agents/sofia
  Repo:        ~/projects/myapp
  Prompt mode: append
  Model:       opus
  Roles:       engineer, reviewer
  Scope:       project
```

## `genie dir edit`

Update fields on an existing agent entry.

```bash theme={"dark"}
genie dir edit <name> [options]
```

```bash Terminal theme={"dark"}
$ genie dir edit sofia --model sonnet --roles engineer
Agent "sofia" updated.
  Model: opus → sonnet
  Roles: engineer,reviewer → engineer
```

## `genie dir sync`

Sync directory entries from filesystem agent folders into the PostgreSQL registry.

```bash theme={"dark"}
genie dir sync [--global]
```

## `genie agent register`

Register an agent locally and auto-register in Omni (if configured).

```bash theme={"dark"}
genie agent register <name> [options]
```

| Option                 | Description                               |
| ---------------------- | ----------------------------------------- |
| `--dir <path>`         | Agent folder (CWD + AGENTS.md)            |
| `--repo <path>`        | Default git repo                          |
| `--prompt-mode <mode>` | Prompt mode: `append` or `system`         |
| `--model <model>`      | Default model (sonnet, opus, codex)       |
| `--roles <roles...>`   | Built-in roles this agent can orchestrate |
| `--global`             | Write to global directory                 |
| `--skip-omni`          | Skip Omni auto-registration               |

```bash Terminal theme={"dark"}
$ genie agent register sofia
Agent "sofia" registered locally.
  Omni registration: ✅ connected to omni-api
  Provider: automagik-genie
```

## `genie init agent`

Scaffold a new agent in the workspace. Creates the agent directory structure with default configuration files.

```bash theme={"dark"}
genie init agent <name>
```

```bash theme={"dark"}
$ genie init agent sofia
Created agent scaffold at .genie/agents/sofia/
  SOUL.md        — agent personality and instructions
  HEARTBEAT.md   — recurring task checklist
```

<Note>
  Three related commands, one clear split:

  * `genie init agent <name>` — scaffolds the **files** (SOUL.md, HEARTBEAT.md). Use this when starting from scratch.
  * `genie dir add <name> --dir <path>` — registers an **existing folder** in the directory. Use this when the agent already lives on disk.
  * `genie agent register <name>` — registers locally **and** in Omni for cross-channel messaging. Use this when the agent should reply on WhatsApp, Slack, etc.
</Note>

***

## Scope

Agent entries can be stored at two levels:

| Scope       | Location                  | Use case                          |
| ----------- | ------------------------- | --------------------------------- |
| **Project** | `.genie/directory.json`   | Agents specific to this repo      |
| **Global**  | `~/.genie/directory.json` | Agents available across all repos |

Use `--global` to target the global directory.

<Tip>
  Register reusable, role-style agents (engineer, reviewer, qa) in the **global** directory so every repo picks them up. Keep repo-specific personas (e.g., a project mascot or domain expert) in the **project** directory so they don't leak into unrelated work.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="Agents (concept)" icon="robot" href="/genie/concepts/agents">
    How agents, roles, and providers relate.
  </Card>

  <Card title="Spawn & Lifecycle" icon="rocket" href="/genie/cli/spawn">
    Spawn the agents you've registered here.
  </Card>

  <Card title="Item Registry" icon="store" href="/genie/cli/registry">
    Share agent definitions across machines via the registry.
  </Card>

  <Card title="Messaging" icon="message" href="/genie/cli/messaging">
    Message a registered agent from the CLI.
  </Card>
</CardGroup>