# Configuration

# Configuration

The plugin requires **zero configuration** — it wires itself on installation. This page documents the configuration model used by the plugin, useful for understanding how agents are defined.

## Frontmatter Fields

Each agent is defined as a Markdown file with YAML frontmatter:

| Field         | Type              | Description             | Values                      |
| ------------- | ----------------- | ----------------------- | --------------------------- |
| `description` | string            | What the agent does     | Free text                   |
| `mode`        | string            | Agent invocation mode   | `all`, `subagent`           |
| `permission`  | object            | Tool access permissions | See below                   |
| `color`       | string (optional) | Tab color in the UI     | Hex color (e.g., `#ff6600`) |
| `maxSteps`    | number (optional) | Max delegation steps    | Integer                     |

### Example

```yaml
---
description: Focused implementation agent for atomic tasks.
mode: subagent
permission:
  read: allow
  edit: allow
  bash:
    "*": ask
---
```

## Permission Model

Each tool can have one of three permission levels:

| Level   | Behavior                             |
| ------- | ------------------------------------ |
| `allow` | Agent can use the tool freely        |
| `ask`   | Agent must ask before using the tool |
| `deny`  | Agent cannot use the tool            |

Permissions can also use bash pattern matching for granular control:

```yaml
permission:
  bash:
    "*": deny
    "git *": allow
    "npm *": ask
```

## Agent Modes

| Mode       | Description                                                                            |
| ---------- | -------------------------------------------------------------------------------------- |
| `all`      | Full agent with conversation and tool access. Can be invoked directly or via `task()`. |
| `subagent` | Can only be invoked via `task()`. Cannot start conversations independently.            |

The orchestrator (`@orchestrator`) uses `mode: all` because it manages workflows. All specialists use `mode: subagent` because they are invoked by the orchestrator or directly by the user.