Directory Commands

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

`genie dir add`

genie dir add <name> --dir <path> [options]

Terminal

$ 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.

genie dir rm <name> [--global]

Terminal

$ genie dir rm sofia
Agent "sofia" removed from project directory.

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.

`genie dir ls`

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

genie dir ls [<name>]

Terminal

$ 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.

genie dir edit <name> [options]

Terminal

$ 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.

genie dir sync [--global]

`genie agent register`

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

Terminal

$ 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.

genie init agent <name>

$ genie init agent sofia
Created agent scaffold at .genie/agents/sofia/
  SOUL.md        — agent personality and instructions
  HEARTBEAT.md   — recurring task checklist

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.

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.

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.

Agents (concept)

How agents, roles, and providers relate.

Spawn & Lifecycle

Spawn the agents you’ve registered here.

Item Registry

Share agent definitions across machines via the registry.

Messaging

Message a registered agent from the CLI.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Directory

Directory Commands

`genie dir add`

Options

`genie dir rm`

`genie dir ls`

`genie dir edit`

`genie dir sync`

`genie agent register`

`genie init agent`

Scope

See also

Agents (concept)

Spawn & Lifecycle

Item Registry

Messaging

​Directory Commands

​genie dir add

​Options

​genie dir rm

​genie dir ls

​genie dir edit

​genie dir sync

​genie agent register

​genie init agent

​Scope

​See also

Agents (concept)

Spawn & Lifecycle

Item Registry

Messaging

Directory Commands

`genie dir add`

Options

`genie dir rm`

`genie dir ls`

`genie dir edit`

`genie dir sync`

`genie agent register`

`genie init agent`

Scope

See also