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

# Infrastructure

> Setup, TUI, app, serve, diagnostics, updates, database management, and terminal shortcuts.

# 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).

<Note>
  `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.
</Note>

```bash theme={"dark"}
genie tui [options]
```

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

```bash theme={"dark"}
# 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).

```bash theme={"dark"}
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                            |

<Note>
  `genie daemon start` now redirects to `genie serve --headless`. Use `genie serve start` directly for explicit control.
</Note>

```bash theme={"dark"}
# 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.

```bash theme={"dark"}
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                                |

<Note>
  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.
</Note>

### 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).

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Sessions">
    Historical session replay — scroll through completed sessions, re-watch transcripts, and inspect tool-use timelines.
  </Accordion>

  <Accordion title="Mission Control (tasks)">
    Orchestration dashboard for in-flight wishes and task groups. Modal overlays for task detail; backed by the `task` NATS prefix.
  </Accordion>

  <Accordion title="Cost Intelligence (costs)">
    Token spend and cost analytics — per-agent, per-team, and per-model breakdowns with live cost counters streamed from the backend.
  </Accordion>

  <Accordion title="Files">
    Browser for project files, the brain memory store, and scheduled artifacts. Backed by the `fs` NATS prefix for filesystem notifications.
  </Accordion>

  <Accordion title="Scheduler">
    Create, pause, and inspect cron + ad-hoc schedules. Mirrors `genie schedule` from the CLI.
  </Accordion>

  <Accordion title="System">
    Host health — processes, PostgreSQL, tmux, NATS, CPU/memory/disk. Requires the `platform-dev` role.
  </Accordion>

  <Accordion title="Settings">
    Tabbed configuration surface for executor defaults, NATS URL, theme, and per-view permissions. Anchored to the bottom of the sidebar.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Activity">
    Recent events feed surfaced inside the Fleet detail panel (no standalone sidebar entry). Lives on the `event` NATS prefix.
  </Accordion>

  <Accordion title="Setup (wizard)">
    First-run onboarding flow for new workspaces — configures executor, NATS, and default team.
  </Accordion>
</AccordionGroup>

### When to use app, TUI, or CLI

<CardGroup cols={3}>
  <Card title="Desktop app" icon="display">
    Rich multi-view cockpit on a workstation with a GUI. Best for day-to-day orchestration, cost tracking, and live agent supervision.
  </Card>

  <Card title="TUI" icon="terminal">
    Same visual affordances in a pure terminal. Best over SSH, in tmux, or on hosts without a display.
  </Card>

  <Card title="CLI" icon="code">
    Scripts, CI, heartbeats, and remote automation. Best when you need deterministic, composable commands with JSON output.
  </Card>
</CardGroup>

### Examples

```bash theme={"dark"}
# 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.

<Note>
  `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`.
</Note>

```bash theme={"dark"}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Examples

```bash theme={"dark"}
# 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
```

<Tip>
  The NATS subjects, subscription patterns, and reliability semantics the bridge relies on are documented in [Architecture → Messaging](/genie/architecture/messaging).
</Tip>

***

## `genie setup`

Interactive wizard for configuring Genie settings.

```bash theme={"dark"}
genie setup [options]
```

```bash Terminal theme={"dark"}
$ 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                                           |

```bash Terminal theme={"dark"}
$ 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.

```bash theme={"dark"}
genie doctor [options]
```

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

```bash Terminal theme={"dark"}
$ 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.

```bash theme={"dark"}
genie update [options]
```

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

```bash Terminal theme={"dark"}
$ 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.

```bash theme={"dark"}
genie uninstall
```

```bash Terminal theme={"dark"}
$ 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/cli/database).

## `genie shortcuts`

Configure Warp-like keyboard shortcuts for tmux.

```bash theme={"dark"}
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                           |

```bash theme={"dark"}
# 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                             |

```bash Terminal theme={"dark"}
$ 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
```