agent-orchestrator/docs/config/ref-settings.md

# Configuration Reference

All configuration paths, environment variables, database files, and per-project
settings for Agents Orchestrator.

## Environment variables

### Core

| Variable | Default | Description |
|----------|---------|-------------|
| `AGOR_TEST` | unset | Set to `1` to enable test mode. Disables file watchers, wake scheduler, and telemetry. |
| `AGOR_OTLP_ENDPOINT` | unset | OpenTelemetry OTLP/HTTP endpoint (e.g. `http://localhost:4318`). When unset, telemetry is console-only. |
| `AGOR_TEST_DATA_DIR` | unset | Override data directory in test mode. Isolates SQLite databases. |
| `AGOR_TEST_CONFIG_DIR` | unset | Override config directory in test mode. Isolates groups.json and plugins. |
| `AGOR_TEST_CTX_DIR` | unset | Override ctx database directory in test mode. |
| `AGOR_EDITION` | `community` | Set to `pro` to enable commercial features (used by vitest and CI). |

### Provider-specific

Provider environment variables (`CLAUDE_*`, `CODEX_*`, `OLLAMA_*`) are stripped
from the sidecar process environment to prevent cross-contamination. The
whitelist `CLAUDE_CODE_EXPERIMENTAL_*` is preserved.

Variables the sidecar runner may read:

| Variable | Provider | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Claude | API key (used by Claude CLI internally) |
| `OPENAI_API_KEY` | Codex | API key for Codex SDK |
| `OPENROUTER_API_KEY` | Aider | API key for OpenRouter-routed models |
| `CLAUDE_CONFIG_DIR` | Claude | Override Claude config directory (multi-account) |
| `BTMSG_AGENT_ID` | All (Tier 1) | Injected for management agents to enable btmsg/bttask CLI |

## Config files

Base directory: `~/.config/agor/`

### groups.json

Primary configuration file. Defines project groups, projects, and management
agents.

```
~/.config/agor/groups.json
```

Schema: `GroupsFile` (see `src/lib/types/groups.ts`).

Structure:

```json
{
  "version": 1,
  "groups": [
    {
      "id": "group-id",
      "name": "Group Name",
      "projects": [ ... ],
      "agents": [ ... ]
    }
  ],
  "activeGroupId": "group-id"
}
```

Managed via the Settings tab in the UI or by editing the file directly. Changes
are picked up on next group load.

### accounts.json (Pro edition)

Commercial multi-account configuration.

```
~/.config/agor/accounts.json
```

Only present when `AGOR_EDITION=pro`. Not included in the community build.

### plugins/

Plugin discovery directory. Each plugin is a subdirectory containing a
`plugin.json` manifest.

```
~/.config/agor/plugins/
  my-plugin/
    plugin.json
    index.js
```

Plugins run in Web Worker sandboxes with permission-gated APIs. See
`src/lib/plugins/plugin-host.ts`.

## Database files

Base directory: `~/.local/share/agor/`

All databases use SQLite WAL mode with 5-second busy timeout for concurrent
access.

### sessions.db

Session persistence, layout state, settings, session metrics, and anchors.

```
~/.local/share/agor/sessions.db
```

Tables:

| Table | Description |
|-------|-------------|
| `sessions` | Session state (project_id, group_name, layout data) |
| `agent_messages` | Per-project message persistence |
| `project_agent_state` | SDK session ID, cost, status per project |
| `session_metrics` | Historical session data (tokens, turns, cost, model) |
| `session_anchors` | Preserved turns through compaction chains |
| `settings` | Key-value application settings |

### btmsg.db

Shared database for inter-agent messaging (btmsg) and task board (bttask).

```
~/.local/share/agor/btmsg.db
```

Created by the `btmsg` CLI on first `btmsg register`. Used concurrently by
Python CLIs and the Rust backend.

Tables:

| Table | Description |
|-------|-------------|
| `agents` | Registered agents (id, name, role, group_id, tier, model, status) |
| `messages` | Direct messages between agents |
| `channels` | Named broadcast channels |
| `channel_messages` | Messages posted to channels |
| `contacts` | ACL for agent-to-agent visibility |
| `heartbeats` | Agent liveness tracking |
| `dead_letter_queue` | Undeliverable messages |
| `audit_log` | Agent action audit trail |
| `seen_messages` | Per-message read tracking (session_id, message_id) |
| `tasks` | Kanban task board entries |
| `task_comments` | Comments on tasks |

### search.db

FTS5 full-text search index.

```
~/.local/share/agor/search.db
```

Virtual tables:

| Table | Description |
|-------|-------------|
| `search_messages` | Indexed agent messages |
| `search_tasks` | Indexed task board entries |
| `search_btmsg` | Indexed btmsg messages |

Rebuilt on demand via the search overlay (`Ctrl+Shift+F`).

## Tauri configuration

### src-tauri/tauri.conf.json

Community edition Tauri config. Defines window properties, permissions, updater
endpoint, and bundle metadata.

### src-tauri/tauri.conf.commercial.json

Commercial edition overlay. Merged with the base config when building with
`--config src-tauri/tauri.conf.commercial.json`. Changes bundle identifier,
product name, and updater URL.

## Theme settings

17 themes in 3 groups, all mapping to the same 26 `--ctp-*` CSS custom
properties.

| Group | Themes |
|-------|--------|
| Catppuccin | Mocha (default), Macchiato, Frappe, Latte |
| Editor | VSCode Dark+, Atom One Dark, Monokai, Dracula, Nord, Solarized Dark, GitHub Dark |
| Deep Dark | Tokyo Night, Gruvbox Dark, Ayu Dark, Poimandres, Vesper, Midnight |

Settings keys (persisted in `sessions.db` settings table):

| Key | Default | Description |
|-----|---------|-------------|
| `theme` | `mocha` | Active theme ID |
| `ui_font_family` | system sans-serif | UI element font |
| `ui_font_size` | `14` (px) | UI font size (feeds CSS `--ui-font-size`) |
| `term_font_family` | system monospace | Terminal font |
| `term_font_size` | `14` (px) | Terminal font size (feeds CSS `--term-font-size`) |
| `default_shell` | system default | Default shell for terminal panes |
| `default_cwd` | `~` | Default working directory |

All font settings are restored from SQLite on startup via `initTheme()`.

## Per-project settings

These fields are set in `groups.json` per project entry (`ProjectConfig`):

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | `ProviderId` | `claude` | Agent provider |
| `model` | string | provider default | Model identifier override |
| `profile` | string | `default` | Claude profile name |
| `useWorktrees` | boolean | `false` | Git worktree isolation per session |
| `sandboxEnabled` | boolean | `false` | Landlock filesystem sandbox |
| `autonomousMode` | string | `restricted` | `restricted` or `autonomous` |
| `anchorBudgetScale` | string | `medium` | Anchor budget: `small` (2K), `medium` (6K), `large` (12K), `full` (20K) |
| `stallThresholdMin` | number | `15` | Minutes before idle agent is marked stalled (range 5--60) |

### Agent-specific fields

Set on `GroupAgentConfig` entries in the `agents` array:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `role` | string | required | `manager`, `architect`, `tester`, or `reviewer` |
| `wakeIntervalMin` | number | `3` | Auto-wake check interval (Manager only) |
| `wakeStrategy` | string | `smart` | `persistent`, `on-demand`, or `smart` |
| `wakeThreshold` | number | `0.5` | Threshold for smart wake strategy (0.0--1.0) |
| `systemPrompt` | string | none | Custom system prompt appended to generated prompt |