reference.yaml

# HAL config reference — all supported keys
# Full key index for docs. See [Configuration](README.md). Short copy-paste example: ../../examples/hal.config.yaml

# Optional path to a custom env file for variable substitution (see README → Environment variable substitution).
# env: "~/.hal/secrets.env"

# ─── Top-level: globals (defaults for all projects) ─────────────────────────────
# See this README for globals table and Access control section.

globals:
  # Access: allowedUserIds (numbers or "${VAR}" strings), dangerouslyAllowUnrestrictedAccess
  access:
    allowedUserIds: []  # e.g. [123456789] or ["${TELEGRAM_USER_ID}"]
    dangerouslyAllowUnrestrictedAccess: false

  # See [Engines](../engines/README.md); per-engine: [Codex](../engines/codex/README.md), [Antigravity](../engines/antigravity/README.md)
  engine:
    name: claude  # required unless each project sets its own; claude|copilot|codex|opencode|cursor|antigravity
    command: ""   # override CLI path
    model: ""     # override model (see engine docs)
    enforceCwd: true  # default true; inject a cwd system instruction into prompts and markdown crons
    session: true # optional; false = stateless, true = adapter default, "shared" = force shared, "user" = per-user (OpenCode rejects "user" at boot). Codex/Copilot default/true = per-user; Cursor default/true = shared.
    sessionMsg: "hi!"
    # envFile: ".env"  # optional; path to env file sourced before running engine CLI (relative to project cwd, or absolute)
    codex:        # Codex-only flags
      networkAccess: false
      fullDiskAccess: false
      dangerouslyEnableYolo: false
    antigravity:  # Antigravity-only flags
      approvalMode: yolo  # default|auto_edit|yolo
      sandbox: false
    copilot:      # Copilot-only flags
      allowAllPaths: false  # true = allow access to any path on disk (default: cwd only)

  # See [Logging](logging/README.md)
  logging:
    level: info   # debug|info|warn|error
    flow: true
    persist: false

  # See [Rate limit](rate-limit/README.md)
  rateLimit:
    max: 10
    windowMs: 60000

  # Voice transcription (Whisper)
  transcription:
    model: base.en
    mode: confirm  # confirm|inline|silent
    # Legacy compatibility flags (deprecated):
    # sticky: true
    # showTranscription: true

  dataDir: ""     # default: project-cwd/.hal/users; see dataDir values in README

  # See [Commands config](commands/README.md) and [System commands](../commands/system/README.md)
  commands:
    start:
      enabled: true
      showInMenu: false
      showInHelp: false
      session:
        reset: false
      message:
        text: ""   # or from: "path/to/file.md"
    help:
      enabled: true
      showInMenu: true
      showInHelp: true
      message: {}
    reset:
      enabled: false
      showInMenu: true
      showInHelp: true
      session: {}
      message:
        confirm: ""
        done: ""
      timeout: 60
    clear:
      enabled: true
      showInMenu: true
      showInHelp: true
      message: {}
    info:
      enabled: true
      showInMenu: true
      showInHelp: true
      cwd: true
      engineModel: true
      session: true
      context: true
    git:
      enabled: false
      showInMenu: true
      showInHelp: true
    model:
      enabled: true
      showInMenu: true
      showInHelp: true
    engine:
      enabled: true
      showInMenu: true
      showInHelp: true
    npm:
      enabled: false          # opt-in; run npm scripts via /npm
      showInMenu: true
      showInHelp: true
      whitelist: []            # optional; if set, only these scripts are allowed
      blacklist: []            # optional; if set, these scripts are excluded
      timeoutMs: 60000         # hard timeout (ms); process is killed after this
      maxOutputChars: 4000     # inline output limit; excess is sent as file
      sendAsFileWhenLarge: true

# ─── Top-level: providers (model lists for /model) ───────────────────────────
# See [Engines — Model list](../engines/README.md#model-list-providers-key)
providers: {}
# Example shape (per engine): claude: [{ name: "sonnet", description: "...", default: true }, ...]

# ─── Top-level: root context (all projects) ───────────────────────────────────
# See [Context](context/README.md)
context: {}
# Example: { "IMPLICIT_KEY": "value", "CUSTOM": "{{projectCwd}}" }

# ─── Top-level: projects (map keyed by project key) ───────────────────────────
# Each key = project key (legacy internal name: slug); name/cwd default to key. See projects table in README.

projects:
  my-project:
    name: my-project    # optional; defaults to key
    active: true
    cwd: my-project     # optional; defaults to key
    telegram:
      botToken: "${BOT_TOKEN}"  # required
    access: {}          # optional; replaces globals when set
    engine:
      enforceCwd: true   # optional override; same engine keys as globals.engine
    providers: {}        # optional; override top-level list
    logging: {}
    rateLimit: {}
    transcription:
      mode: confirm
      # Legacy compatibility flags (deprecated):
      # sticky: true
      # showTranscription: true
    dataDir: ""
    # See [Context](context/README.md)
    context: {}
    # See [Commands config](commands/README.md) and [System commands](../commands/system/README.md)
    commands: {}