Installation

This document defines how plugins are installed, scoped, cached, and resolved by conformant tools.

Installation Scopes

When a plugin is installed, it is associated with a scope that determines where it is available and who can use it.

Scope	Typical Settings File	Use Case
`user`	`~/.config/<tool>/settings.json`	Personal plugins available across all projects. Default scope.
`project`	`.config/<tool>/settings.json` in project root	Team plugins shared via version control.
`local`	`.config/<tool>/settings.local.json` in project root	Project-specific plugins, not committed to version control.
`managed`	Managed by external tooling	Organization-managed plugins. Read-only for end users.

Tools MUST support at least the user scope. Tools SHOULD support project and local scopes. The managed scope is OPTIONAL.

When the same plugin is installed at multiple scopes, tools MUST apply the following precedence (highest to lowest):

A plugin disabled at a higher-precedence scope overrides it being enabled at a lower-precedence scope.

{
  "enabledPlugins": [
    "plugin-name",
    "another-plugin"
  ],
  "disabledPlugins": [
    "disabled-plugin"
  ]
}

Installed plugins SHOULD be stored in .agents/plugins/ at the appropriate scope level.

Scope	Recommended Path
User	`~/.agents/plugins/<plugin-name>/`
Project	`<project-root>/.agents/plugins/<plugin-name>/`

Tools SHOULD copy installed plugins to a local plugin cache rather than using them in-place.

When loading plugins, tools resolve them in this order:

Direct directory (--plugin-dir): Load directly, no caching. Used for development.
Cache: Load from cache if up-to-date.
Source: Copy to cache, then load from cache.

# Load a plugin in development
<tool> --plugin-dir ./my-plugin

In development mode, the plugin is loaded directly — no caching, changes take effect on restart.

When a plugin is uninstalled: