Configuration Files

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

{
  "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

Agent Profiles

Agent profiles (named workerProfiles in config) define how to launch Claude Code agents. Each profile specifies a launcher binary and CLI arguments.

"workerProfiles": {
  "default": {
    "launcher": "claude",
    "claudeArgs": ["--dangerously-skip-permissions"]
  },
  "safe": {
    "launcher": "claude",
    "claudeArgs": []
  }
}

Use profiles with: genie spawn engineer --profile safe

Council Presets

Council presets configure dual-model deliberation for the /council skill:

"councilPresets": {
  "default": {
    "left": "default",
    "right": "default",
    "skill": "council"
  }
}

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

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

Omni Integration

Connects Genie to the Omni unified messaging platform:

"omni": {
  "apiUrl": "http://localhost:3008",
  "apiKey": "your-api-key",
  "defaultInstanceId": "instance-uuid"
}

State Storage — PostgreSQL

As of v4, Genie’s primary state store is an embedded PostgreSQL instance managed by pgserve. 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 for full schema details and migration history.

Auto-Approve Configuration

Genie supports layered trust configuration for automatic tool approval. Config hierarchy (lower overrides higher):

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

YAML Schema

# ~/.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:

Checks deny lists first (deny wins over allow)
Checks allow lists
For Bash commands, checks bash_deny_patterns then bash_allow_patterns
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:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": ".*",
      "hooks": ["genie hook dispatch"]
    }],
    "PostToolUse": [{
      "matcher": "SendMessage",
      "hooks": ["genie hook dispatch"]
    }]
  }
}

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

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Configuration Files

config.json

Full Schema

Key Sections

State Storage — PostgreSQL

State Locations

Legacy File Locations (deprecated)

Connection Details

Auto-Approve Configuration

YAML Schema

Evaluation Order

Environment Variables

Claude Code Settings

​config.json

​Full Schema

​Key Sections

​State Storage — PostgreSQL

​State Locations

​Legacy File Locations (deprecated)

​Connection Details

​Auto-Approve Configuration

​YAML Schema

​Evaluation Order

​Environment Variables

​Claude Code Settings

config.json

Full Schema

Key Sections

State Storage — PostgreSQL

State Locations

Legacy File Locations (deprecated)

Connection Details

Auto-Approve Configuration

YAML Schema

Evaluation Order

Environment Variables

Claude Code Settings