Config reference

Coldtea has two kinds of configuration: app settings and repo files.

Use app settings for your machine and TeaHouse. Use repo files only when a project needs repeatable setup for everyone.

App settings

Area	Use it for	Notes
Appearance	Theme and visual preferences.	User preference, not repo policy.
Agents	Installed agents, launch args, model and effort presets where supported.	The agent CLI still owns auth and provider setup.
Cloud runs	Background or cloud-backed agent setup where enabled.	Requires workspace and provider setup.
Features	App-level toggles such as global hotkey behavior.	Availability depends on build and platform.
TeaHouse	Active TeaHouse, members, and team-scoped settings.	Owners can invite people and revoke pending invites.
Integrations	Connected tools such as GitHub or Linear.	Upstream provider permissions still apply.
QA	Matcha QA setup and test users where enabled.	Keep test-user credentials scoped and intentional.
Scripts and updates	Worktree scripts, update flows, or supporting setup.	Keep shared scripts boring and reviewable.

If a setting is missing, it may not be enabled for your build, platform, or TeaHouse.

Coldtea reads worktree script config from .coldtea/ in the project:

File	Commit it?	Purpose
`.coldtea/config.json`	Usually yes	Shared worktree setup, run, and teardown commands.
`.coldtea/config.local.json`	Usually no	Machine-specific overrides, local ports, private file copying, or personal paths.

Shared config should not contain secrets, personal absolute paths, or commands that only work on one developer's machine.

Shared config accepts optional arrays:

{
  "setup": ["npm install"],
  "run": ["npm run dev"],
  "teardown": ["npm run clean"]
}

Use the fields this way:

Field	When it runs
`setup`	After Coldtea creates a worktree.
`run`	When you start the configured project command for that worktree.
`teardown`	Before deleting or retiring a worktree, when configured.

Each command runs in a visible terminal pane. If it fails, inspect the pane before continuing.

A local array replaces the shared script for that key:

{
  "run": ["npm run dev -- --port 3010"]
}

A local hook object wraps the shared script:

{
  "setup": {
    "before": ["cp ../coldtea/.env.local .env.local"],
    "after": ["npm run db:prepare"]
  }
}

Use hooks when the team command is right, but your machine needs a little setup before or after it.

For a worktree, Coldtea resolves scripts in this order:

Later entries can replace or wrap earlier entries. This lets the shared config stay team-safe while local config handles private machine details.

Coldtea provides these variables to worktree commands:

Variable	Meaning
`COLDTEA_ROOT_PATH`	Absolute path to the base project.
`COLDTEA_WORKTREE_PATH`	Absolute path to the worktree.
`COLDTEA_WORKTREE_NAME`	Worktree display name.
`COLDTEA_BASE_BRANCH`	Branch the worktree was created from.
`COLDTEA_BRANCH_NAME`	Branch checked out inside the worktree.
`COLDTEA_WORKTREE_ACCENT_TONE`	Accent tone assigned to the worktree.

Use these instead of hardcoding paths.

Agent sessions launched by Coldtea may also receive session-scoped values such as:

These are live session values, not config you should copy into repo files. Treat them as sensitive. See MCP and local API for the full boundary.