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

# Configuration Files

> config.json schema, PostgreSQL state, environment variables, and auto-approve configuration

Genie uses several configuration files and a PostgreSQL database for state. The main config file is `~/.genie/config.json`, but the primary state store is an embedded PostgreSQL instance managed by pgserve.

## config.json

**Location:** `~/.genie/config.json`

The primary configuration file, managed by `genie setup` or edited directly. Validated by a Zod schema on every load — invalid configs fall back to defaults with a warning.

### Full Schema

```json theme={"dark"}
{
  "version": 2,
  "session": {
    "name": "genie",
    "defaultWindow": "shell",
    "autoCreate": true
  },
  "terminal": {
    "execTimeout": 120000,
    "readLines": 100,
    "worktreeBase": "~/.genie/worktrees"
  },
  "logging": {
    "tmuxDebug": false,
    "verbose": false
  },
  "shell": {
    "preference": "auto"
  },
  "shortcuts": {
    "tmuxInstalled": false,
    "shellInstalled": false
  },
  "codex": {
    "configured": false
  },
  "installMethod": "bun",
  "updateChannel": "latest",
  "setupComplete": true,
  "workerProfiles": {
    "default": {
      "launcher": "claude",
      "claudeArgs": ["--dangerously-skip-permissions"]
    },
    "safe": {
      "launcher": "claude",
      "claudeArgs": []
    }
  },
  "defaultWorkerProfile": "default",
  "councilPresets": {
    "default": {
      "left": "default",
      "right": "default",
      "skill": "council"
    }
  },
  "systemPromptMode": "append",
  "omni": {
    "apiUrl": "http://localhost:3008",
    "apiKey": "...",
    "defaultInstanceId": "..."
  }
}
```

### Key Sections

<AccordionGroup>
  <Accordion title="Agent Profiles">
    Agent profiles (named `workerProfiles` in config) define how to launch Claude Code agents. Each profile specifies a launcher binary and CLI arguments.

    ```json theme={"dark"}
    "workerProfiles": {
      "default": {
        "launcher": "claude",
        "claudeArgs": ["--dangerously-skip-permissions"]
      },
      "safe": {
        "launcher": "claude",
        "claudeArgs": []
      }
    }
    ```

    Use profiles with: `genie spawn engineer --profile safe`
  </Accordion>

  <Accordion title="Council Presets">
    Council presets configure dual-model deliberation for the `/council` skill:

    ```json theme={"dark"}
    "councilPresets": {
      "default": {
        "left": "default",
        "right": "default",
        "skill": "council"
      }
    }
    ```

    Each preset pairs two agent profiles (left/right panes) with a skill.
  </Accordion>

  <Accordion title="System Prompt Mode">
    Controls how Genie injects system prompts into Claude Code agents:

    | Mode      | Flag                          | Behavior                                             |
    | --------- | ----------------------------- | ---------------------------------------------------- |
    | `replace` | `--system-prompt-file`        | Replaces Claude Code's default system prompt         |
    | `append`  | `--append-system-prompt-file` | Preserves Claude Code default, appends Genie context |
  </Accordion>

  <Accordion title="Omni Integration">
    Connects Genie to the Omni unified messaging platform:

    ```json theme={"dark"}
    "omni": {
      "apiUrl": "http://localhost:3008",
      "apiKey": "your-api-key",
      "defaultInstanceId": "instance-uuid"
    }
    ```
  </Accordion>
</AccordionGroup>

## State Storage — PostgreSQL

As of v4, Genie's primary state store is an embedded PostgreSQL instance managed by [pgserve](/genie/architecture/postgres). State that was previously stored in JSON files now lives in PG tables.

### State Locations

| State                       | Location                                                  | Notes                                    |
| --------------------------- | --------------------------------------------------------- | ---------------------------------------- |
| Tasks, stages, dependencies | PostgreSQL `tasks`, `task_dependencies`, `task_stage_log` | Full lifecycle with audit trail          |
| Boards and pipelines        | PostgreSQL `boards`, `board_templates`                    | Project-scoped column pipelines          |
| Projects                    | PostgreSQL `projects`                                     | Named task boards                        |
| Agents (workers)            | PostgreSQL `agents`, `agent_templates`                    | Replaces `~/.genie/workers.json`         |
| Teams                       | PostgreSQL `teams`                                        | Replaces `~/.genie/teams/*.json`         |
| Mailbox                     | PostgreSQL `mailbox`                                      | Replaces `.genie/mailbox/*.json`         |
| Team chat                   | PostgreSQL `team_chat`                                    | Replaces `.genie/chat/*.jsonl`           |
| Sessions                    | PostgreSQL `sessions`, `session_content`                  | Claude Code session metadata and content |
| Schedules and triggers      | PostgreSQL `schedules`, `triggers`, `runs`                | Cron-based automation                    |
| Audit events                | PostgreSQL `audit_events`                                 | OTel-structured immutable log            |
| Heartbeats                  | PostgreSQL `heartbeats`                                   | Agent liveness tracking                  |
| App registry                | PostgreSQL `app_store`, `installed_apps`                  | Unified item registry                    |
| Conversations               | PostgreSQL `conversations`, `messages`                    | Task-linked conversations                |
| pgserve data                | `~/.genie/data/pgserve/`                                  | PostgreSQL data directory                |

### Legacy File Locations (deprecated)

These locations are no longer the primary state store but may still exist on disk:

| File                    | Replaced By       | Status                           |
| ----------------------- | ----------------- | -------------------------------- |
| `~/.genie/workers.json` | `agents` table    | Deprecated — PG is authoritative |
| `~/.genie/teams/*.json` | `teams` table     | Deprecated — PG is authoritative |
| `.genie/mailbox/*.json` | `mailbox` table   | Deprecated — PG is authoritative |
| `.genie/chat/*.jsonl`   | `team_chat` table | Deprecated — PG is authoritative |

### Connection Details

| Setting          | Value                       |
| ---------------- | --------------------------- |
| Default port     | `19642`                     |
| Host             | `127.0.0.1`                 |
| Database name    | `genie`                     |
| Data directory   | `~/.genie/data/pgserve/`    |
| Port lockfile    | `~/.genie/pgserve.port`     |
| Migration marker | `~/.genie/pgserve.migrated` |

See the [PostgreSQL architecture page](/genie/architecture/postgres) for full schema details and migration history.

## Auto-Approve Configuration

Genie supports layered trust configuration for automatic tool approval.

**Config hierarchy** (lower overrides higher):

1. **Global defaults:** `~/.config/genie/auto-approve.yaml`
2. **Repo-level:** `.genie/auto-approve.yaml` in each repo
3. **Wish-level:** `## Auto-Approve` section in WISH.md

### YAML Schema

```yaml theme={"dark"}
# ~/.config/genie/auto-approve.yaml
defaults:
  allow:
    - Read
    - Glob
    - Grep
  deny:
    - Bash
  bash_allow_patterns:
    - "^git status"
    - "^bun test"
  bash_deny_patterns:
    - "^rm -rf"
    - "^git push.*--force"

repos:
  /home/user/myproject:
    inherit: global    # or "none" to start fresh
    allow:
      - Write
      - Edit
    bash_allow_patterns:
      - "^bun run"
```

### Evaluation Order

For each tool use, the auto-approve engine:

1. Checks deny lists first (deny wins over allow)
2. Checks allow lists
3. For Bash commands, checks `bash_deny_patterns` then `bash_allow_patterns`
4. Merges layers: wish > repo > global defaults

## Environment Variables

| Variable                               | Default                 | Purpose                                            |
| -------------------------------------- | ----------------------- | -------------------------------------------------- |
| `GENIE_HOME`                           | `~/.genie`              | Relocates all global state                         |
| `GENIE_AGENT_NAME`                     | —                       | Agent identity for hooks (required for auto-spawn) |
| `GENIE_TEAM`                           | —                       | Default team name                                  |
| `GENIE_NATS_URL`                       | `nats://localhost:4222` | NATS server URL                                    |
| `GENIE_PG_PORT`                        | `19642`                 | pgserve PostgreSQL port                            |
| `GENIE_MAX_CONCURRENT`                 | `5`                     | Max concurrent scheduler runs                      |
| `GENIE_IDLE_TIMEOUT_MS`                | —                       | Auto-suspend idle agents after N ms                |
| `CLAUDECODE`                           | —                       | Set to `1` to enable Claude Code features          |
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | —                       | Set to `1` for native teammate UI                  |

## Claude Code Settings

Genie integrates with Claude Code's settings at `~/.claude/settings.json`. The hook system is registered there:

```json theme={"dark"}
{
  "hooks": {
    "PreToolUse": [{
      "matcher": ".*",
      "hooks": ["genie hook dispatch"]
    }],
    "PostToolUse": [{
      "matcher": "SendMessage",
      "hooks": ["genie hook dispatch"]
    }]
  }
}
```

<Note>
  Genie never modifies `~/.claude/settings.json` directly. Hook registration is done during `genie setup` with user confirmation.
</Note>