Concepts

Settings

Declare your app's settings as a schema and Chataway renders one consistent settings view for them — on the Apps page, in your panel's Settings tab and on the phone.

Apps don't ship settings UI. You declare fields in the manifest; Chataway draws the form, stores the values, and shows every setting once, with where its current value comes from. The same view appears on the Apps page, as the Settings view in your panel's header, and on the phone.

#Declare settings

plugin.json

json

"contributes": {
  "settingSections": [
    { "id": "upload", "title": "Uploads", "description": "How new assets are created.", "summary": ["visibility", "folder"] },
    { "id": "naming", "title": "Naming" }
  ],
  "settings": [
    {
      "key": "visibility", "label": "Visibility", "type": "select", "scope": "both", "section": "upload",
      "options": [
        { "value": "private", "label": "Private", "description": "Only you can see new assets" },
        { "value": "team", "label": "Team", "description": "Everyone in your Acme team" }
      ],
      "default": "private"
    },
    { "key": "folder", "label": "Folder", "type": "string", "scope": "project", "section": "upload", "placeholder": "e.g. /game/sprites" },
    { "key": "prefix", "label": "Name prefix", "type": "string", "scope": "both", "section": "naming", "default": "" },
    { "key": "maxSize", "label": "Max size (px)", "type": "number", "scope": "global", "section": "upload", "min": 64, "max": 4096, "default": 1024, "advanced": true },
    { "key": "watermark", "label": "Add watermark", "type": "boolean", "scope": "both", "section": "naming", "default": false },
    { "key": "watermarkText", "label": "Watermark text", "type": "string", "scope": "both", "section": "naming",
      "visibleWhen": { "key": "watermark", "equals": [true] } }
  ]
}

#Fields

Field	Type
`key`	string	Stable identifier. Don't rename it — stored values are keyed by it.
`label`	string	Shown next to the control.
`description`	string	Help text under the control.
`type`	`string` · `number` · `boolean` · `select` · `textarea`	The control.
`options`	`{ value, label, description? }[]`	For `select`. `description` shows under the choice — prices, trade-offs.
`default`	string · number · boolean	Used when nothing is set.
`scope`	`global` · `project` · `both`	Where it can be set — see below. Required.
`min`, `max`	number	For `number`.
`placeholder`	string	Empty-state hint.
`section`	string	A `settingSections` id. Fields without one go to General.
`advanced`	boolean	Hidden behind More options in its section.
`visibleWhen`	`{ key, equals: [...] }`	Only shown while another setting has one of these values.

#Scope

`scope`	Set…	Typical use
`global`	once, for every project	Personal preferences: default size, language
`project`	per project only	Things that only make sense per project: a target folder, a linked board
`both`	globally, with a per-project override	Most settings: a sensible default everywhere, changed where needed

Values resolve project → global → default. The form labels each setting with where its effective value comes from (This project, All projects, Default); a per-project value has Reset and Use everywhere.

#Sections

settingSections groups fields, in display order. Each section is shown collapsed as a one-line summary built from the values of its summary keys (default: its first two basic fields) — Uploads · Private · /game/sprites. Keep sections small and summaries meaningful.

#Reading settings

#What not to put in settings

Secrets. No API keys, passwords or tokens. Store apps can't declare secrets; use a connected account.
Things the agent should decide per call. Make those tool arguments.
Your own account data. If it lives on your service (a user's team, their plan), read it from your API with the account token.