Infrastructure Commands

Commands for setting up Genie, launching the TUI and desktop app, managing services, diagnosing issues, updating, database management, and configuring terminal shortcuts.

`genie tui`

Launch the interactive terminal UI (OpenTUI nav + tmux Claude Code).

genie tui is not in the top-level genie --help output. Invoke it directly by name — the CLI resolves it at dispatch time. If your install was built without the TUI module, the command will error immediately; fall back to genie app (desktop app) or the pane-level commands in this page.

genie tui [options]

Flag	Description
`--dev`	Development mode with auto-reload on file changes

# Launch TUI
genie tui

# Launch in dev mode (auto-reloads on source changes)
genie tui --dev

`genie serve`

Start, stop, and check status of all genie infrastructure services (pgserve, tmux, scheduler).

genie serve [command]

Subcommands

Command	Description
`start`	Start genie serve (pgserve, tmux, scheduler)
`stop`	Stop genie serve and all services
`status`	Show service health

`genie serve start` Options

Flag	Description
`--daemon`	Run as background daemon (redirects to `genie serve --headless`)
`--foreground`	Run in foreground (for systemd `ExecStart`)
`--headless`	Headless mode — no TUI, just services

genie daemon start now redirects to genie serve --headless. Use genie serve start directly for explicit control.

# Start all services
genie serve start

# Check service health
genie serve status

# Stop all services
genie serve stop

`genie app`

Launch the Genie desktop app — a Tauri-based native cockpit that layers 12 views on top of the same PostgreSQL state, NATS event stream, and tmux/SDK executors that power genie tui and the raw CLI. The app ships a Bun sidecar for IPC (JSON-RPC over stdin/stdout, proxied through Tauri’s invoke()), subscribes to khal.*.genie.* NATS subjects for live updates, and loads each view lazily from the app manifest.

genie app [options]

Flag	Description
`--backend-only`	Start only the backend sidecar (IPC on stdin/stdout, no window)
`--tui`	Fall back to terminal UI mode (useful on headless hosts)
`--dev`	Development mode with hot reload

The desktop app requires a graphical environment (Linux X11/Wayland, macOS, or Windows). On headless servers use --tui to fall back to the OpenTUI interface, --backend-only to run just the sidecar for remote frontends, or the plain genie CLI.

Views

The app manifest declares 12 native views. The primary sidebar surfaces nine of them; Terminal, Activity, and Setup are opened from context (per-agent terminals, detail panels, first-run onboarding).

Command Center (dashboard)

The app shell landing view — live activity feed, team activity rollups, recent cost snapshot, and quick links. Subscribes to events.runtime for real-time updates.

Fleet (agents)

Agent roster grouped by team with a detail panel for identity, executor, and activity. Replaces the earlier 5-icon agents strip — one view with sidebar + main list + detail rail.

Sessions

Historical session replay — scroll through completed sessions, re-watch transcripts, and inspect tool-use timelines.

Mission Control (tasks)

Orchestration dashboard for in-flight wishes and task groups. Modal overlays for task detail; backed by the task NATS prefix.

Cost Intelligence (costs)

Token spend and cost analytics — per-agent, per-team, and per-model breakdowns with live cost counters streamed from the backend.

Files

Browser for project files, the brain memory store, and scheduled artifacts. Backed by the fs NATS prefix for filesystem notifications.

Scheduler

Create, pause, and inspect cron + ad-hoc schedules. Mirrors genie schedule from the CLI.

System

Host health — processes, PostgreSQL, tmux, NATS, CPU/memory/disk. Requires the platform-dev role.

Settings

Tabbed configuration surface for executor defaults, NATS URL, theme, and per-view permissions. Anchored to the bottom of the sidebar.

Terminal

Embedded xterm.js panes streamed over NATS PTY subjects (pty.create, pty.resize, pty.data, pty.input). Opened from the Fleet detail panel when you attach to an agent. Requires the platform-dev role.

Activity

Recent events feed surfaced inside the Fleet detail panel (no standalone sidebar entry). Lives on the event NATS prefix.

Setup (wizard)

First-run onboarding flow for new workspaces — configures executor, NATS, and default team.

When to use app, TUI, or CLI

Desktop app

Rich multi-view cockpit on a workstation with a GUI. Best for day-to-day orchestration, cost tracking, and live agent supervision.

TUI

Same visual affordances in a pure terminal. Best over SSH, in tmux, or on hosts without a display.

CLI

Scripts, CI, heartbeats, and remote automation. Best when you need deterministic, composable commands with JSON output.

Examples

# Launch the full desktop app
genie app

# Dev mode with hot reload (while hacking on the app package)
genie app --dev

# Start only the Bun sidecar — useful for remote frontends or CI
genie app --backend-only

# Headless host: fall back to the OpenTUI interface
genie app --tui

`genie omni`

Manage the Omni ↔ Genie NATS bridge. genie omni subscribes to omni.message.> subjects, routes inbound messages to agent sessions, and streams responses back to Omni. Session state and executor configuration are read from PostgreSQL — there is no in-memory Map, so status queries stay accurate across restarts and multiple bridge processes.

genie omni is not in the top-level genie --help output. It resolves by name at dispatch time; installations without the Omni bridge module will exit with a clear error. The bridge is opt-in and does not auto-start with genie serve.

genie omni [command] [options]

Subcommands

Command	Description
`start`	Start the NATS bridge and subscribe to `omni.message.>`
`status`	Show bridge status — active sessions, queue depth, idle timers (PG-backed)
`stop`	Stop the running NATS bridge
`help [command]`	Display help for a subcommand

`genie omni start` options

Flag	Default	Description
`--nats-url <url>`	`localhost:4222`	NATS server URL
`--max-concurrent <n>`	`20`	Maximum concurrent agent sessions
`--idle-timeout <ms>`	`900000`	Idle timeout before a session is suspended (ms)
`--executor <type>`	`tmux`	Executor backend — `tmux` or `sdk`

`genie omni status` options

Flag	Description
`--json`	Emit the status payload as JSON (for scripts and dashboards)

Key concepts

PG-backed status queries

genie omni status reads active sessions, queue depth, and idle timers directly from PostgreSQL via the executors table and its metadata index. The legacy in-memory session Map is documented but no longer authoritative, so status is consistent across bridge restarts and multiple observer processes. A safePgCall helper + pgAvailable scaffolding keeps the bridge resilient if PG is briefly unavailable.

Executor config resolver and genie_executor flip switch

The bridge resolves executor configuration (tmux vs SDK, concurrency, idle timeout) through a single resolver that honours the genie_executor flip switch. Flipping a single row swaps the backend for new sessions without restarting the bridge; in-flight sessions continue on their original executor.

Lazy resume via the executors table

Suspended sessions are resumed on demand. When a new message arrives for an idle chat, the bridge looks up the session row in executors, rehydrates state from its metadata index, and reattaches the executor. The SDK executor additionally captures inline session content so resumed SDK sessions start with their previous turns.

Examples

# Start the bridge with defaults (tmux executor, localhost NATS)
genie omni start

# Start with the SDK executor and tighter concurrency
genie omni start --executor sdk --max-concurrent 8 --idle-timeout 300000

# Point at a remote NATS cluster
genie omni start --nats-url nats://nats.internal:4222

# Check bridge health (human-readable)
genie omni status

# Check bridge health (JSON — for dashboards, alerts, CI)
genie omni status --json

# Stop the running bridge
genie omni stop

The NATS subjects, subscription patterns, and reliability semantics the bridge relies on are documented in Architecture → Messaging.

`genie setup`

Interactive wizard for configuring Genie settings.

genie setup [options]

Terminal

$ genie setup
╔════════════════════════════════════════════════════════════════╗
║                  ✨ Genie Setup Wizard ✨                     ║
╠════════════════════════════════════════════════════════════════╣
║  Terminal: tmux                                               ║
║  Session:  auto                                               ║
║  Codex:    not configured                                     ║
╚════════════════════════════════════════════════════════════════╝

? Configure terminal shortcuts? (Y/n)
? Set up Codex integration? (Y/n)
? Configure session naming? (auto/manual)

Options

Flag	Description
`--quick`	Skip interactive prompts, use defaults
`--shortcuts`	Only configure keyboard shortcuts (shell aliases + tmux keybindings)
`--codex`	Only configure Codex integration
`--terminal`	Only configure terminal settings
`--session`	Only configure session naming
`--reset`	Reset all settings to defaults
`--show`	Show current configuration

Terminal

$ genie setup --show
Genie Configuration:
  Config: ~/.genie/config.json
  Terminal: tmux
  Session naming: auto
  Shortcuts: installed
  Codex: configured (OTel relay on port 4318)

`genie doctor`

Diagnose the Genie installation and environment.

genie doctor [options]

Flag	Description
`--fix`	Auto-fix: kill zombie postgres, clean shared memory, restart daemon

Terminal

$ genie doctor
Genie Doctor — Checking your environment...

  genie CLI       ✅ v4.260324.8
  bun runtime     ✅ v1.2.x
  tmux            ✅ v3.4
  git             ✅ v2.43.0
  claude code     ✅ installed
  PostgreSQL      ✅ connected (pgserve)
  NATS            ⚠️  not running (optional)
  .genie/         ✅ scaffolded
  AGENTS.md       ✅ found
  CLAUDE.md       ✅ found

Summary: 9/10 checks passed. 1 warning.

`genie update`

Update Genie to the latest version.

genie update [options]

Flag	Description
`--next`	Switch to dev builds (npm `@next` tag)
`--stable`	Switch to stable releases (npm `@latest` tag)

Terminal

$ genie update
Checking for updates...
  Current: v4.260324.7
  Latest:  v4.260324.8
Updating...
  ✅ Updated to v4.260324.8

`genie uninstall`

Remove Genie from the system. Cleans up global state, configuration, and the CLI binary.

genie uninstall

Terminal

$ genie uninstall
Uninstalling Genie...
  Removed ~/.genie/
  Removed CLI binary
  ✅ Genie uninstalled.

`genie db`

For full database commands (db status, db migrate, db query, db backup, db restore, db url), see the Database CLI reference.

`genie shortcuts`

Configure Warp-like keyboard shortcuts for tmux.

genie shortcuts [command]

Subcommands

Command	Description
`show`	Show available shortcuts and installation status
`install`	Install shortcuts to config files (`~/.tmux.conf`, shell rc)
`uninstall`	Remove shortcuts from config files

# Show current shortcut status
genie shortcuts show

# Install shortcuts
genie shortcuts install

# Remove shortcuts
genie shortcuts uninstall

Generates and installs:

Platform	Config	Shortcuts
tmux	`~/.tmux.conf`	Ctrl+T (new tab), Ctrl+S (vertical split), Ctrl+Shift+S (horizontal split)
Termux	`~/.termux/termux.properties`	F1 (new tab), F2 (vsplit), F3 (hsplit)
Shell	`~/.bashrc` / `~/.zshrc`	Helper functions + disable Ctrl+S flow control

Terminal

$ genie shortcuts
Installing keyboard shortcuts...
  tmux config:    ✅ written to ~/.tmux.conf
  shell config:   ✅ appended to ~/.zshrc
  termux config:  ⬜ skipped (not on Termux)

Shortcuts installed! Restart tmux to apply:
  tmux source ~/.tmux.conf

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Infrastructure

Infrastructure Commands

`genie tui`

`genie serve`

Subcommands

`genie serve start` Options

`genie app`

Views

When to use app, TUI, or CLI

Desktop app

TUI

CLI

Examples

`genie omni`

Subcommands

`genie omni start` options

`genie omni status` options

Key concepts

Examples

`genie setup`

Options

`genie doctor`

`genie update`

`genie uninstall`

`genie db`

`genie shortcuts`

Subcommands

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Documentation Index

​Infrastructure Commands

​genie tui

​genie serve

​Subcommands

​genie serve start Options

​genie app

​Views

​When to use app, TUI, or CLI

Desktop app

TUI

CLI

​Examples

​genie omni

​Subcommands

​genie omni start options

​genie omni status options

​Key concepts

​Examples

​genie setup

​Options

​genie doctor

​genie update

​genie uninstall

​genie db

​genie shortcuts

​Subcommands

Infrastructure Commands

`genie tui`

`genie serve`

Subcommands

`genie serve start` Options

`genie app`

Views

When to use app, TUI, or CLI

Examples

`genie omni`

Subcommands

`genie omni start` options

`genie omni status` options

Key concepts

Examples

`genie setup`

Options

`genie doctor`

`genie update`

`genie uninstall`

`genie db`

`genie shortcuts`

Subcommands