Skip to main content

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 Commands

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

​
genie dir add

Register an agent in the directory. 
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

FlagDescriptionDefault
--dir <path>Agent folder (CWD + AGENTS.md)Required
--repo <path>Default git repo—
--prompt-mode <mode>Prompt mode: append or systemappend
--model <model>Default model (sonnet, opus, codex)—
--roles <roles...>Built-in roles this agent can orchestrate—
--globalWrite 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

Register an agent locally and auto-register in Omni (if configured). 
genie agent register <name> [options]
OptionDescription
--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
--globalWrite to global directory
--skip-omniSkip 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:
ScopeLocationUse case
Project.genie/directory.jsonAgents specific to this repo
Global~/.genie/directory.jsonAgents 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.

​
See also

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.