Config File Reference

English · 简体中文

All configuration lives in a single config file, ~/.code-meeseeks/config.yaml (YAML format). For day-to-day use, visual editing via the in-app Settings page and the first-launch wizard is enough — no need to edit the file by hand; this document is the complete structure and field reference, for bulk configuration, advanced parameter tuning, and troubleshooting.

How to edit: saving on the Settings page writes to disk and hot-reloads; the Settings page's "Open config.yaml with the system default app" lets you edit the file directly.
When it takes effect: connection / LLM / proxy / language / concurrency, etc. are rebuilt and applied immediately on save; a few advanced parameters (such as workspace.repos_dir) require an app restart.
A note on credentials: access tokens, API keys, and proxy passwords are stored in plaintext in this file (isolated from the config structure but not encrypted). Request credentials with least privilege, protect this file well, and revoke promptly on leak.

Full example

language: ''            # empty = auto by system language, falling back to English; or explicitly zh-CN / en-US / ja-JP / de-DE

appearance:
  editor_theme: auto
  editor_font_family: ''
  editor_font_size: 14

workspace:
  repos_dir: ~/.code-meeseeks/repos

agent:
  dir: ''
  max_steps: 8
  summary_max_chars: 800
  autopilot:
    enabled: false
    batch_size: 10
    grants: []
  strategy:
    auto_followup: true
    max_followup_asks: 2
    max_code_suggestions: 4
    code_suggestion_spec: ''
    code_suggestion_layout: ''

poller:
  interval_seconds: 300

proxy:
  enabled: false
  protocol: http
  host: ''
  port: 8080
  username: ''
  password: ''
  no_proxy: ''         # hosts that bypass the proxy, comma-separated; loopback is always bypassed

pr_agent:
  strategy: auto
  max_concurrency: 2

notifications:
  enabled: true
  new_pr: true
  reply: true
  mention: true
  authored_comment: true
  authored_needs_work: true
  authored_conflict: true

service:
  enabled: false
  host: 127.0.0.1
  port: 18765
  token: ''

update:
  check_enabled: true

connections:
  - id: my-bitbucket
    kind: bitbucket-server
    base_url: https://bitbucket.example.com
    display_name: Company Bitbucket
    auth:
      type: pat
      token: <BITBUCKET_HTTP_ACCESS_TOKEN>
    clone:
      protocol: pat
  - id: my-github
    kind: github
    base_url: https://api.github.com
    display_name: GitHub
    auth:
      type: pat
      token: <GITHUB_PERSONAL_ACCESS_TOKEN>
    clone:
      protocol: pat

active_connection_id: my-bitbucket

llm:
  active_id: default
  context_tokens: 128000
  profiles:
    - id: default
      label: OpenAI
      provider: openai
      base_url: ''
      model: gpt-4o
      api_key: <OPENAI_API_KEY>

Top-level fields

Field	Type	Default	Description
`language`	string	`''` (auto)	Language used by the UI and pr-agent-generated content (ISO locale, e.g. `zh-CN` / `en-US` / `ja-JP` / `de-DE`). Default empty = auto: matched against your system's preferred language, falling back to English if none fits. Switchable on the Settings page (hot-applied).
`appearance`	object	—	UI and editor appearance (theme / font), see below.
`workspace`	object	—	Working directory settings, see below.
`agent`	object	—	Advanced Agent and AutoPilot settings (the Agent directory and personalized rules both belong here), see below.
`poller`	object	—	PR polling settings, see below.
`proxy`	object	—	Outbound network proxy settings, see below (details in Network proxy setup).
`pr_agent`	object	—	pr-agent runtime settings, see below.
`notifications`	object	—	System notification and dock badge settings, see below.
`service`	object	—	Local API service (CLI / external integration entry) settings, see below (details in CLI tool).
`update`	object	—	Version update-check settings, see below.
`connections`	array	`[]`	Code platform connection list, see below (details in Code platform setup).
`active_connection_id`	string	`''`	The `id` of the currently active connection, see below.
`llm`	object	—	LLM profile settings, see below (details in LLM setup).

`appearance` — appearance

Purely front-end display items for the UI and editor (the main process only sets the native window's light/dark from the theme). All are visually adjustable on the Settings page and take effect immediately.

Field	Type	Default	Description
`editor_theme`	enum	`auto`	Global theme (shared by the Monaco editor and the whole UI): `auto` follows the system dark / light, the rest are built-in / third-party theme ids.
`editor_font_family`	string	`''`	The editor's monospace font family (CSS font-family, comma-separated candidates allowed). Empty = the built-in mono font stack.
`editor_font_size`	integer	`14`	Editor font size (px), constrained to a reasonable range.

`workspace` — working directory

Field	Type	Default	Description
`repos_dir`	string	`~/.code-meeseeks/repos`	Directory storing the repos' local mirrors (bare clones). Changes fully take effect only after an app restart. Supports `~` expansion.

`agent` — Advanced Agent & AutoPilot

The advanced Agent turns natural-language requests into autonomous planning + multi-tool orchestration (design in docs/arch/02-agent/01-agent.md). The Agent directory <agent.dir>/ is the Agent's complete persona and knowledge source, with a fixed layout:

<agent.dir>/
├── SOUL.md      # Soul: core responsibilities and boundaries (read-only)
├── AGENTS.md    # Working conventions and red lines
├── MEMORY.md    # Long-term memory (writable)
├── USER.md      # User profile (writable)
└── rules/       # Personalized rules directory (the former rules.dir folded in here; structure in Custom review rules)

The Agent has no separate enable toggle — it's available once an LLM is configured and pr-agent is ready. When dir is empty it falls back to the default location under the working directory, ~/.code-meeseeks/agent (a startup-time idempotent scaffold fills in any missing files); a custom path can point at a git repo, making it easy for a team to share context and rules.

Migrating from the old rules.*: earlier versions configured personalized rules at the top-level rules.dir; this is now folded into <agent.dir>/rules/, and the old rules.* fields are no longer read. Just move the contents of your original rules directory into <agent.dir>/rules/ (the rule file structure is unchanged, see Custom review rules).

Field	Type	Default	Description
`dir`	string	`''`	Agent directory path. Empty = the default `~/.code-meeseeks/agent` under the working directory. Supports `~` expansion. Can point at a git repo to share.
`max_steps`	integer	`8`	Upper bound on the Agent's planning steps per session, `1`–`50`.
`summary_max_chars`	integer	`800`	Strict length limit (characters) of the closing summary, `100`–`4000`.
`autopilot`	object	—	AutoPilot pre-review settings, see below.
`strategy`	object	—	Agent behavior strategy (applies to manual auto-review and AutoPilot), see below.

`agent.autopilot` — AutoPilot pre-review

After polling discovers PRs awaiting review, automatically pre-runs /describe + /review, so a draft awaits your confirmation the moment you open the app (the decision still rests with the reviewer). Admission control only lets through "awaiting my review · pending" PRs not yet reviewed; removing / purging a PR terminates an in-flight task.

Field	Type	Default	Description
`enabled`	boolean	`false`	AutoPilot master switch. Toggleable in the status bar; when `false` the scheduling logic doesn't run at all.
`batch_size`	integer	`10`	Upper bound on PRs per single LLM-judged batch, `1`–`50`.
`grants`	array	`[]`	Per-item write-permission grants (default empty = deny all), e.g. `approve` / `needs_work` / `publish_comment`; enforced against the red lines at runtime.

`agent.strategy` — Agent behavior strategy

Applies to the auto-review micro-flow (shared by manual "auto review" and AutoPilot), not AutoPilot-exclusive.

Field	Type	Default	Description
`auto_followup`	boolean	`true`	Whether the review stage enables automatic follow-up (conditional `/ask`). Disabling it skips the interpretation + follow-up and summarizes directly, saving an LLM call and the follow-up cost.
`max_followup_asks`	integer	`2`	Upper bound on automatic follow-ups (a hard cap on conditional `/ask`), `0`–`5`. Effective only when `auto_followup` is on; `0` is equivalent to off.
`max_code_suggestions`	integer	`4`	Upper bound on code suggestions generated by a single `/review`, `/improve`, or `/ask`, `2`–`8`.
`code_suggestion_spec`	string	`''`	Free-text spec injected into `/improve`, `/review`, `/ask` to shape how each suggestion is written (soft constraint). Empty = nothing injected. See below.
`code_suggestion_layout`	string	`''`	Deterministic markdown layout for the review-draft comment created from a suggestion. Empty = the default layout. See below.

Code-suggestion spec & layout

Two optional fields control how AI code suggestions read and how they land in a review-draft comment. Both are editable from Settings → Agent → Strategy via an inline editor, so you don't have to hand-edit the config file.

code_suggestion_spec — a soft guideline appended to the model's instructions for /improve, /review, and /ask. Use it to steer the content structure of each suggestion, e.g. "Structure every suggestion as three sections — Problem, Analysis, Suggestion — each on its own line." The model generally complies but is not guaranteed to.
code_suggestion_layout — a deterministic markdown template applied when a suggestion becomes a review-draft comment (substitution is exact, no dependency on the model). Placeholders:

Placeholder	Value
`<TITLE>`	Localized "AI suggestion" label
`<SUGGESTIONS>`	The suggestion body
`<HOME>`	Project website
`<PR>`	Current PR link
`<MODEL>`	Current active model name

If the layout contains <SUGGESTIONS> it is used as the full comment body; otherwise the whole string is prepended as a prefix before the body. Empty falls back to the default layout:

[[<TITLE>](<HOME>) (<MODEL>)]
<SUGGESTIONS>

`poller` — PR polling

Field	Type	Default	Description
`interval_seconds`	integer	`300`	The interval in seconds for automatically polling PRs awaiting review, minimum `30`.

`proxy` — outbound network proxy

When enabled, LLM calls, code platform REST, and git HTTPS all go through the proxy; loopback / local addresses (including a local Ollama) connect directly, as do any hosts listed in no_proxy. git fetch over SSH does not use this config — configure it yourself in ~/.ssh/config.

Field	Type	Default	Description
`enabled`	boolean	`false`	Proxy master switch. Off = everything connects directly.
`protocol`	enum	`http`	Currently only `http` is supported.
`host`	string	`''`	Proxy host address.
`port`	integer	`8080`	Proxy port, `1`–`65535`.
`username`	string	`''`	Basic Auth username, empty if no auth.
`password`	string	`''`	Basic Auth password, empty if no auth.
`no_proxy`	string	`''`	Hosts that connect directly instead of through the proxy, in the conventional `NO_PROXY` syntax (comma-separated; a domain also covers its subdomains; `*` bypasses everything; CIDR ranges are not supported). Loopback is always bypassed and need not be listed. See Network proxy setup.

`pr_agent` — runtime

Field	Type	Default	Description
`strategy`	enum	`auto`	Runtime strategy: `auto` prefers the bundled embedded runtime and falls back to the system `pr-agent` CLI if missing; you can also force `embedded` / `local-cli` explicitly.
`max_concurrency`	integer	`2`	Review task concurrency, `1`–`8`. Adjustable in the "AI" section of the Settings page (hot-applied, no restart), or edit this file by hand — details in LLM setup · Advanced: review concurrency.

`notifications` — notifications

Toggles for system notifications (toasts) and the macOS dock "awaiting response" badge. enabled is the master switch (when off, neither notifications pop nor the badge lights up); the rest control system notifications per event type — new_pr / reply / mention target scenarios like "awaiting my review", and authored_* target "authored by me" PRs. System notifications are subject to OS permissions, and the app silently degrades if the user disables them in system settings. Adjustable on the Settings page, effective immediately.

Field	Type	Default	Description
`enabled`	boolean	`true`	Notification master switch; when off, no system notifications pop and the dock badge doesn't light up.
`new_pr`	boolean	`true`	Pop a notification when a new PR awaiting my review appears.
`reply`	boolean	`true`	Pop a notification when a comment reply is received.
`mention`	boolean	`true`	Pop a notification when @-mentioned in a comment.
`authored_comment`	boolean	`true`	Pop a notification when a PR I authored receives a new comment from someone else.
`authored_needs_work`	boolean	`true`	Pop a notification when a PR I authored is marked "needs work" in review.
`authored_conflict`	boolean	`true`	Pop a notification when a PR I authored develops a merge conflict.

`service` — local API service

Listen configuration for the local HTTP API service, providing app capabilities to the meebox CLI and external scripts / agents (details in CLI tool). Off by default with zero exposure; enabling it enforces bearer token auth. Visually toggle and view / copy / regenerate the token in the "Integration" section of the Settings page, effective immediately (a toggle / host / port change stops the old and starts the new; a token change takes effect on the next request).

Field	Type	Default	Description
`enabled`	boolean	`false`	Service master switch. Off = not listening, no exposure.
`host`	string	`127.0.0.1`	Listen address. Default reachable only from the local machine; set `0.0.0.0` to expose to the LAN (high risk — the token is the only line of defense then).
`port`	integer	`18765`	Listen port, `1`–`65535`.
`token`	string	`''`	Access token (bearer). Auto-generated on first enable; regeneratable on the Settings page (the old token is invalidated immediately). Stored in plaintext.

`update` — version update check

Field	Type	Default	Description
`check_enabled`	boolean	`true`	On startup (and on manual trigger from the Settings page), check the latest stable version on GitHub Releases and compare it against the current version; if newer, only prompt you to go download it (no auto-download / install). Set to `false` to disable the check — this toggle is adjustable only by editing this file (the Settings page shows update status but offers no toggle).

`connections` — code platform connections

connections is an array, each element being one connection. kind determines the platform type and field shape.

Common fields

Field	Type	Description
`id`	string	Connection unique identifier, referenced by `active_connection_id`.
`kind`	enum	Platform type: `github` / `bitbucket-server` / `gitlab`.
`display_name`	string	Display name (shown on the Settings page and status bar).
`auth.type`	literal	Fixed `pat`.
`auth.token`	string	Access token (PAT). For required permissions see Code platform setup.
`clone.protocol`	enum	git clone protocol: `pat` (default, HTTPS, username + PAT embedded in the URL) / `ssh` (uses the system `~/.ssh/config`).

`kind: github`

Field	Type	Description
`base_url`	string (URL)	GitHub API base. Optional: empty defaults to `https://api.github.com` (github.com); for GitHub Enterprise Server enter the instance address `https://<ghe-host>`, and `/api/v3` is appended automatically (a full API base by hand also works). The clone / web domains are derived by the app automatically.

`kind: bitbucket-server`

Field	Type	Description
`base_url`	string (URL)	Bitbucket Server / Data Center address, e.g. `https://bitbucket.example.com`. Required.

`kind: gitlab`

Field	Type	Description
`base_url`	string (URL)	GitLab API base. Optional: empty defaults to `https://gitlab.com/api/v4` (gitlab.com); for Self-Managed enter the instance address `https://<gitlab-host>`, and `/api/v4` is appended automatically (a full API base by hand also works). The clone / web domains are derived by the app automatically.

`active_connection_id` — currently active connection

Type	Default	Description
string	`''`	Takes the `id` of one connection. Only one is active at a time: only it is polled, and the PR list and status bar reflect only it. An empty string / an id that doesn't exist polls no connection (the UI guides you to enable one). `connections` still retains all configuration, and historical PRs are unaffected.

`llm` — LLM profiles

Field	Type	Default	Description
`profiles`	array	`[]`	LLM profile list, each with independent provider / model / base_url / api_key.
`active_id`	string	`''`	The `id` of the profile currently in effect. An empty string / an id that doesn't exist injects no LLM environment variables into the review (pr-agent falls back to reading shell environment variables).
`context_tokens`	integer	`128000`	Context-length limit (tokens) for trimming input content, `32000`–`1000000`. Over-long changes are truncated to this to fit the model. Does not apply to local CLI mode (the CLI tool manages its own context). Adjustable in the "AI" section of the Settings page (effective on the next review).

A single profile (`profiles[]`)

Field	Type	Default	Description
`id`	string	—	Profile unique identifier, referenced by `active_id`.
`label`	string	`''`	Display name; when empty the UI falls back to provider + model.
`provider`	enum	`openai-compatible`	Provider: `openai` / `anthropic` / `deepseek` / `dashscope` (Alibaba Bailian) / `volcengine-ark` (Volcengine Ark) / `openai-compatible` (any OpenAI-protocol-compatible service, including a local Ollama's `/v1`) / `cli` (a local agentic CLI, no direct API connection). The old value `ollama` is auto-migrated to `openai-compatible`.
`base_url`	string	`''`	API endpoint. Most official providers leave it empty for the default; `openai-compatible` / self-hosted must fill it in.
`model`	string	`''`	Model name. Most providers take only the model name and the app adds the litellm prefix automatically; in `cli` mode this holds a command name (e.g. `claude`).
`api_key`	string	`''`	Auth key. Empty for local types (local CLI / self-hosted service without auth).

For value examples per provider and local CLI mode notes, see LLM setup.

FilesExpand file tree

04-config-reference.md

Latest commit

History

04-config-reference.md

File metadata and controls

Config File Reference

Full example

Top-level fields

appearance — appearance

workspace — working directory

agent — Advanced Agent & AutoPilot

agent.autopilot — AutoPilot pre-review

agent.strategy — Agent behavior strategy

Code-suggestion spec & layout

poller — PR polling

proxy — outbound network proxy

pr_agent — runtime

notifications — notifications

service — local API service

update — version update check

connections — code platform connections