config.yaml.example

# ContextMatrix configuration example.
# Copy this file to one of the following locations:
#   $XDG_CONFIG_HOME/contextmatrix/config.yaml   (if XDG_CONFIG_HOME is set)
#   ~/.config/contextmatrix/config.yaml           (XDG default)
#   ./config.yaml                                 (current working directory fallback)
#
# Environment variable overrides are available for every field — see the
# CONTEXTMATRIX_* variables documented below.

# TCP port the HTTP server listens on.
# Default: 8080
# Env: CONTEXTMATRIX_PORT
port: 8080

# Log output format.
# Allowed values: "text" (default, human-readable key=value) | "json" (structured JSON lines)
# Default: text
# Env: CONTEXTMATRIX_LOG_FORMAT
log_format: "text"

# Minimum log level to emit.
# Allowed values: "debug" | "info" (default) | "warn" | "error"
# Default: info
# Env: CONTEXTMATRIX_LOG_LEVEL
log_level: "info"

# Port for the admin/debug HTTP server. When non-zero, the admin listener
# serves /debug/pprof/* (Go runtime profiling) and /metrics (Prometheus). The
# main listener on `port` does NOT expose these — /metrics is admin-only by
# design so unauthenticated scrapers and path-scanners cannot reach it.
# Default: 0 (disabled)
# Env: CONTEXTMATRIX_ADMIN_PORT
admin_port: 0

# Bind address for the admin server. Defaults to loopback so pprof heap dumps
# and /metrics are unreachable from outside the host unless an operator
# explicitly chooses otherwise (in which case the server logs a warning).
# Override only if you know the listener is protected by a firewall / k8s
# NetworkPolicy / service-mesh restriction.
# Default: 127.0.0.1
# Env: CONTEXTMATRIX_ADMIN_BIND_ADDR
admin_bind_addr: "127.0.0.1"

# Path to the directory containing the workflow skill files (create-plan.md,
# execute-task.md, review-task.md, document-task.md, run-autonomous.md, etc.).
# These are the lifecycle scaffolding the MCP server hands to agents as
# prompts; they are NOT the same as the task_skills block below.
# When left empty, defaults to a "workflow-skills" directory next to this
# config file.
# Tilde expansion is supported.
# Env: CONTEXTMATRIX_WORKFLOW_SKILLS_DIR
workflow_skills_dir: workflow-skills

# How long an agent can go without sending a heartbeat before the card is
# automatically moved to the "stalled" state and the agent claim is released.
# Accepts Go duration strings: e.g. "15m", "30m", "1h".
# Default: 30m
# Env: CONTEXTMATRIX_HEARTBEAT_TIMEOUT
heartbeat_timeout: "30m"

# How often the lock manager scans for cards whose heartbeat has timed out.
# Must be positive. The default is fine for production; tests sometimes lower
# this to drive timeout assertions deterministically. No env-var override.
# Default: 1m
stalled_check_interval: "1m"

# Allowed origin for CORS requests. Set to the URL of your web UI in
# production. In development with Vite the default matches the dev server.
# Default: http://localhost:5173
# Env: CONTEXTMATRIX_CORS_ORIGIN
cors_origin: "http://localhost:5173"

# UI color palette theme (server-side default).
# Allowed values: "everforest" | "radix" | "catppuccin"
#   everforest      — warm, muted, medium-contrast (default)
#   radix           — cool slate-grey base with Radix accent scales (step 11)
#   catppuccin      — pastel palette (Mocha in dark mode, Latte in light mode)
# This value is used as the default for all users. Individual users can
# override it via the palette selector in the app header; their choice is
# stored in browser localStorage and takes precedence on subsequent loads.
# Default: everforest
# Env: CONTEXTMATRIX_THEME
theme: "everforest"

# Per-model token cost rates used for usage reporting (optional).
# Keys are model identifiers; prompt/completion values are USD per token.
# Rates per https://platform.claude.com/docs/en/about-claude/pricing, 2026-04-23.
token_costs:
  claude-haiku-4-5:   { prompt: 0.000001,  completion: 0.000005  }  # $1/$5 per MTok
  claude-sonnet-4-6:  { prompt: 0.000003,  completion: 0.000015  }  # $3/$15 per MTok
  claude-opus-4-6:    { prompt: 0.000005,  completion: 0.000025  }  # $5/$25 per MTok
  claude-opus-4-7:    { prompt: 0.000005,  completion: 0.000025  }  # $5/$25 per MTok
  claude-opus-4-8:    { prompt: 0.000005,  completion: 0.000025  }  # $5/$25 per MTok

# Optional API key for MCP endpoint authentication.
# When set, all MCP requests must include this key in the Authorization header
# as "Bearer <key>". Leave empty to disable MCP authentication (current behavior).
# Env: CONTEXTMATRIX_MCP_API_KEY
mcp_api_key: ""

# Boards repository configuration.
# All settings below relate to the boards git repository — the separate repo
# that stores your kanban cards and project configs.
boards:
  # Path to the directory that holds your boards (a separate git repository).
  # This field is required — the server will not start without it.
  # Tilde expansion is supported (e.g. ~/contextmatrix-boards).
  # Env: CONTEXTMATRIX_BOARDS_DIR
  dir: ~/contextmatrix-boards

  # Automatically create a git commit in the boards repository after every card
  # mutation. Disable only if you manage commits yourself.
  # Default: true
  # Env: CONTEXTMATRIX_BOARDS_GIT_AUTO_COMMIT (true/false/1/0)
  git_auto_commit: true

  # Defer git commits: instead of committing after every write, accumulate changes
  # and commit them together when a task transitions to a terminal state (done,
  # not_planned). Reduces commit noise for tasks with many intermediate updates.
  # Has no effect unless git_auto_commit is also true.
  # Default: false
  # Env: CONTEXTMATRIX_BOARDS_GIT_DEFERRED_COMMIT (true/false/1/0)
  git_deferred_commit: false

  # Push commits to the remote after each commit. Requires the boards repository
  # to have a configured remote and credentials (e.g. SSH key).
  # Default: false
  # Env: CONTEXTMATRIX_BOARDS_GIT_AUTO_PUSH (true/false/1/0)
  git_auto_push: false

  # Pull from the remote on startup and at the interval defined by
  # git_pull_interval. Useful for sharing a board across multiple machines.
  # Default: false
  # Env: CONTEXTMATRIX_BOARDS_GIT_AUTO_PULL (true/false/1/0)
  git_auto_pull: false

  # How often to pull from the remote when git_auto_pull is enabled.
  # Accepts Go duration strings: e.g. "30s", "5m", "1h".
  # Default: 60s
  # Env: CONTEXTMATRIX_BOARDS_GIT_PULL_INTERVAL
  git_pull_interval: "60s"

  # Clone-on-empty + remote URL — useful in container deployments where
  # persistent storage starts empty. Requires git_remote_url to be set.
  # HTTPS only; SSH is no longer supported.
  # Default: false
  # Env: CONTEXTMATRIX_BOARDS_GIT_CLONE_ON_EMPTY (true/false/1/0)
  git_clone_on_empty: false

  # HTTPS URL for the boards repository. Used for clone-on-empty and as
  # the default origin remote when no remote is configured.
  # Authentication uses the global github.* config below.
  # Example: https://github.com/user/boards.git
  # Env: CONTEXTMATRIX_BOARDS_GIT_REMOTE_URL
  git_remote_url: ""

# Task-skills repository configuration. The curated set of specialist filesystem
# skills (Go, TypeScript/React, etc.) that the runner mounts into worker
# containers. NOT the same as workflow_skills_dir above — that one is the
# lifecycle scaffolding handed to agents via MCP prompts.
task_skills:
  # Path to the directory that holds the task-skills repo. When empty,
  # defaults to a "task-skills" directory next to this config file.
  # Tilde expansion supported.
  # Env: CONTEXTMATRIX_TASK_SKILLS_DIR
  dir: ""

  # Clone the repo if dir is empty (no existing .git). Useful in
  # container deployments. Requires git_remote_url to be set.
  # Env: CONTEXTMATRIX_TASK_SKILLS_GIT_CLONE_ON_EMPTY
  git_clone_on_empty: false

  # HTTPS URL only (SSH no longer supported).
  # Authentication uses the global github.* config above.
  # Env: CONTEXTMATRIX_TASK_SKILLS_GIT_REMOTE_URL
  git_remote_url: ""

# Execution backends.
#
# A backend is a sister project that CM drives over HMAC-signed
# contextmatrix-protocol webhooks. The backends map has a closed set of entry
# names; each name implies a distinct role:
#
#   runner — contextmatrix-runner: executes cards AND serves global chat.
#            Mutually exclusive with agent and chat — runner already covers both
#            roles, so mixing them is an error.
#   agent  — contextmatrix-agent: executes cards only (no chat).
#   chat   — contextmatrix-chat: serves global chat only (not yet released).
#
# Roles and callback paths are derived from the entry name. CM picks:
#   task backend  → runner (if enabled) else agent (if enabled)
#   chat backend  → runner (if enabled) else chat (if enabled)
#
# Callback paths are derived as /api/<name> (e.g. /api/runner, /api/agent).
# The browser-facing /api/runner/logs and /api/runner/health endpoints are
# hard-wired whenever a task backend is configured; they do not move.
#
# ENABLED FLAG: each entry has an optional `enabled` field (default: true).
# Omitting `enabled` means the entry is active. Set `enabled: false` to keep
# the config block as an inert placeholder. Switch backends by toggling
# enabled flags — do not delete blocks.
#
# TASK-ONLY FIELDS:
#   orchestrator_sonnet_model, orchestrator_opus_model, reconcile_interval —
#     runner entry only; rejected on agent and chat entries.
#   default_model — agent entry only; rejected on runner and chat entries.
#
# RESTART REQUIRED: backends are read once at startup. Any change requires
# a CM restart.

# Backend entries. Valid names: runner, agent, chat.
# Every field has an env override (NAME = RUNNER | AGENT | CHAT). Env values
# take precedence over this file, and a backend can be configured through
# env vars alone:
#   CONTEXTMATRIX_BACKEND_<NAME>_URL
#   CONTEXTMATRIX_BACKEND_<NAME>_API_KEY
#   CONTEXTMATRIX_BACKEND_<NAME>_ENABLED
#   CONTEXTMATRIX_BACKEND_<NAME>_ORCHESTRATOR_SONNET_MODEL  (runner only)
#   CONTEXTMATRIX_BACKEND_<NAME>_ORCHESTRATOR_OPUS_MODEL    (runner only)
#   CONTEXTMATRIX_BACKEND_<NAME>_RECONCILE_INTERVAL         (runner only)
#   CONTEXTMATRIX_BACKEND_<NAME>_DEFAULT_MODEL              (agent only)
backends: {}
#  runner:
#    # Base URL of the backend. Protocol paths are appended: /trigger, /kill,
#    # /stop-all, /message, /promote, /end-session, /chat/*, /logs, ...
#    # Env: CONTEXTMATRIX_BACKEND_RUNNER_URL
#    url: "http://localhost:9090"
#
#    # Shared secret for HMAC-SHA256 webhook signing (both directions).
#    # Must match the backend's configured api_key; min 32 characters.
#    # Env: CONTEXTMATRIX_BACKEND_RUNNER_API_KEY
#    api_key: ""
#
#    # Set to false to disable this entry without removing the config block.
#    # Default: true (omitting = active).
#    # Env: CONTEXTMATRIX_BACKEND_RUNNER_ENABLED
#    enabled: true
#
#    # Model IDs passed in the trigger payload. Defaults shown.
#    # Env: CONTEXTMATRIX_BACKEND_RUNNER_ORCHESTRATOR_SONNET_MODEL /
#    #      CONTEXTMATRIX_BACKEND_RUNNER_ORCHESTRATOR_OPUS_MODEL
#    orchestrator_sonnet_model: "claude-sonnet-4-6"
#    orchestrator_opus_model: "claude-opus-4-8"
#
#    # How often the backstop sweep reconciles containers against card state.
#    # "0s" disables. Default: 60s.
#    # Env: CONTEXTMATRIX_BACKEND_RUNNER_RECONCILE_INTERVAL
#    reconcile_interval: "60s"
#
#  agent:
#    # contextmatrix-agent: card execution only (no chat).
#    # Mutually exclusive with runner; use agent when runner is disabled.
#    url: "http://localhost:9092"
#    api_key: ""
#    enabled: false  # flip to true and set runner: enabled: false to switch
#
#    # Default orchestrator model for the agent backend — any OpenRouter slug.
#    # Per-card pins override it. The complexity selector picks coder/reviewer
#    # models per task; this default drives planning, review synthesis and docs.
#    # OPTIONAL: when unset, triggers carry an empty model and the agent service
#    # falls back to its own serve-config default. Resolution precedence is
#    # card pin → CM default_model → agent serve default.
#    # Env: CONTEXTMATRIX_BACKEND_AGENT_DEFAULT_MODEL
#    default_model: "deepseek/deepseek-v4-flash"
#
#  chat:
#    # contextmatrix-chat: global chat only (no card execution). Project not
#    # yet released. Paired with agent when card execution is also needed.
#    url: "http://localhost:9093"
#    api_key: ""
#    enabled: false

# Chat (global chat panel)
chat:
  # SQLite database for chat sessions and transcripts.
  # CONTEXTMATRIX_CHAT_DB_PATH overrides this.
  # Default: $XDG_STATE_HOME/contextmatrix/chats.db
  # db_path: /var/lib/contextmatrix/chats.db

  # How long a chat container survives after browser disconnects.
  # CONTEXTMATRIX_CHAT_IDLE_TTL overrides this.
  idle_ttl: 1h

  # Maximum concurrent chat containers. Default is 8 — enough headroom for
  # the multi-pane chat UI's 4 user-facing panes plus 2-4 agent-owned
  # background sessions.
  # CONTEXTMATRIX_CHAT_MAX_CONCURRENT overrides this.
  max_concurrent: 8

  # Claude model used when a chat is created without an explicit
  # selection in the New Chat dialog. Must be a key in chat.models.
  default_model: claude-sonnet-4-6

  # Rough token budget for the rehydration payload sent to the runner on
  # cold-reopen. Older transcript turns are dropped (first user turn and
  # last 20 turns are always preserved) until the estimate fits.
  resume_budget_tokens: 40000

  # Force the rehydration phase off after this duration even if the
  # agent never called chat_rehydration_complete. The first user message
  # also ends the phase, so this is a belt-and-suspenders cap.
  rehydration_timeout: 10m

  # Allowlist of selectable models for new chats. The label is shown in
  # the picker; max_tokens drives the context-window denominator in the
  # ChatThread header indicator. Adding a new model is a single edit.
  models:
    claude-sonnet-4-6:
      label: "Sonnet 4.6"
      max_tokens: 1000000
    claude-opus-4-7:
      label: "Opus 4.7"
      max_tokens: 1000000
    claude-opus-4-8:
      label: "Opus 4.8"
      max_tokens: 1000000
    claude-haiku-4-5-20251001:
      label: "Haiku 4.5"
      max_tokens: 200000

# Image upload + retrieval (paste / drag-drop screenshots into cards).
images:
  # SQLite database for stored images. Content-hashed IDs make this
  # cache-friendly and naturally deduplicate identical uploads.
  # CONTEXTMATRIX_IMAGES_DB_PATH overrides this.
  # Default: $XDG_STATE_HOME/contextmatrix/images.db
  # db_path: /var/lib/contextmatrix/images.db

# GitHub authentication and integration.
# Used for boards git, task-skills git, issue importing, and branch listing.
github:
  # Auth method. Allowed values: "app" (recommended) | "pat"
  # Env: CONTEXTMATRIX_GITHUB_AUTH_MODE
  auth_mode: "app"

  # GitHub Enterprise Cloud with Data Residency (GHEC-DR) or GHES hostname.
  # Leave empty for standard github.com.
  # Example: acme.ghe.com
  # Env: CONTEXTMATRIX_GITHUB_HOST
  host: ""

  # GitHub API base URL. When empty, derived from host:
  #   host empty → https://api.github.com
  #   host set   → https://api.<host>
  # Set explicitly only for non-standard enterprise URLs.
  # Env: CONTEXTMATRIX_GITHUB_API_BASE_URL
  api_base_url: ""

  # GitHub App credentials. Required when auth_mode is "app".
  app:
    # Env: CONTEXTMATRIX_GITHUB_APP_ID
    app_id: 0
    # Env: CONTEXTMATRIX_GITHUB_INSTALLATION_ID
    installation_id: 0
    # Path to the App's PEM private key file.
    # Env: CONTEXTMATRIX_GITHUB_PRIVATE_KEY_PATH
    private_key_path: ""

  # Fine-grained PAT (alternative to GitHub App).
  # Mutually exclusive with app.*.
  pat:
    # Never hard-code in production. Supply via env var.
    # Env: CONTEXTMATRIX_GITHUB_PAT_TOKEN
    token: ""

  # Issue importing.
  issue_importing:
    # Env: CONTEXTMATRIX_GITHUB_ISSUE_IMPORTING_ENABLED
    enabled: false
    # Min: 5m. Default: 5m.
    # Env: CONTEXTMATRIX_GITHUB_ISSUE_IMPORTING_SYNC_INTERVAL
    sync_interval: "5m"