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.

​
Session Commands

The genie command is the primary entry point. Running it from any folder creates or attaches a tmux session named after that folder.

​
genie

Start or attach to a Genie session for the current directory. 
genie
Architecture: Each folder gets its own tmux session. Running genie from ~/projects/myapp creates a session named myapp.
Terminal
$ genie
╔════════════════════════════════════════════════════════════════╗
║                    ✨ Automagik Genie ✨                      ║
╠════════════════════════════════════════════════════════════════╣
║  Session: myapp                                               ║
║  Repo:    ~/projects/myapp                                    ║
║  Branch:  feat/add-auth                                       ║
╚════════════════════════════════════════════════════════════════╝

​
Options

FlagDescription
--session <name>Override session name (instead of folder-based)
--name <name>Set agent name for the session
--dir <path>Override working directory
--resetReset the session (kills existing, starts fresh)
--reset kills the existing tmux session and drops any unsaved pane state. It does not touch the persistent Claude sessions stored in PostgreSQL, but in-flight agents will be terminated. Use genie stop <name> if you only want to pause an agent.

​
Session Naming

Sessions are named after basename(cwd). When multiple folders share the same basename, a 4-character hash is appended for disambiguation:
Terminal
$ cd ~/projects/myapp && genie        # Session: myapp
$ cd ~/work/api-server && genie       # Session: api-server
$ cd ~/other/api-server && genie      # Session: api-server-c7b1
The hash suffix is deterministic — running genie from the same path always yields the same session name, so reconnecting from a new terminal attaches to the original session rather than starting a second one.
Prefer short, lowercase session names (auth, docs, sprint12) with --session <name> when you want to share the session across teammates or scripts. Avoid spaces and special characters — tmux treats them as argument boundaries, which breaks genie send and tmux attach -t round-trips.

​
Session with Teams

When a team is active, the session integrates with Claude Code’s native team features:
Terminal
$ genie --session my-feature
# Creates tmux session "my-feature" with:
#   Window 0: team-lead (with AGENTS.md context)
#   Window 1+: spawned agents appear here

​
genie --version

Print the installed Genie version.
Terminal
$ genie --version
4.260324.8

​
See also

Team

Pin a team to a shared tmux session with --tmux-session.

Spawn & Lifecycle

Spawn agents into the current session.

Messaging

Send messages between agents running in the session.

Observability

Inspect Claude sessions stored in PostgreSQL.