Plugin Configuration

Plugin configuration is easiest to understand in three layers:

• project-level enablement
• project-level plugin options
• Console-facing setup and usage protocols

1. Project-level enablement

Whether a plugin is enabled is stored in project downcity.json.

It is a project-level fact.

That means:

• plugins.<name>.enabled controls whether the current project enables that plugin
• if enabled is omitted, built-in plugins are generally treated as enabled
• enabled: false explicitly disables the plugin for this project

2. Project-level plugin options

Runtime options for how an agent uses a plugin usually live in:

{
  "plugins": {
    "chat": {
      "enabled": true,
      "channels": {
        "telegram": {
          "enabled": true,
          "channelAccountId": "telegram-main"
        }
      }
    }
  }
}

This expresses:

• how the current agent uses the plugin
• whether the current project has explicitly disabled it

3. config.scope

Plugin config definitions support:

• global
• project

This describes config field scope. The current built-in project plugins use project config for both enablement and runtime options.

Many current built-in plugins keep agent-side runtime options at project scope.

What setup and usage mean

setup

setup is about:

• install
• repair
• dependency preparation

Typical examples:

• install dependencies
• download a model
• install Python dependencies

usage

usage is about:

• how the current agent should use that plugin
• which behavior choices should be saved

Typical examples:

• whether to inject prompts
• default model
• default format, language, or speed

Why setup and usage are separate

Because they solve different problems:

• setup makes the capability exist
• usage controls how the current agent uses it

That split lets Console present clearer surfaces for:

• Install / Repair
• Options

How plugin config is usually persisted

Project-side plugin settings are generally written back into:

• downcity.json.plugins.*

The persistence path writes the plugins section instead of dumping the entire merged runtime state back into the project file.

Recommended mental model

Remember these three lines:

• enablement lives in project plugins.<name>.enabled
• runtime options usually live beside it in project plugins.<name>
• setup and usage are UI protocol layers

Related docs

• Plugin overview
• Plugin availability