# Configuration

[Documentation index](../README.md)

Pi Herd intentionally has very little settings state.

Agent behavior lives in Markdown definitions. The extension settings currently
own worker placement.

## Worker placement

Settings shape:

```json
{
  "piHerd": {
    "spawnPlacement": "tab"
  }
}
```

Supported values:

```text
tab
split
```

Default:

```text
tab
```

`tab` places future workers in the managed subagent-tab workflow.

`split` places future workers by splitting from the caller's tab/pane placement
boundary.

This affects future starts, not existing workers.

## Settings scope

Pi Herd reads Pi settings through Pi's settings manager.

Global settings are stored in the Pi agent directory's `settings.json`
(default `~/.pi/agent/settings.json`).

Project settings are stored in:

```text
<project>/.pi/settings.json
```

A project placement value is effective only when:

- the project is trusted by Pi; and
- the project setting is `tab` or `split`.

If no valid trusted project placement is active, the global value is used.

`/subagents placement` reports both the effective value and whether the active scope
is `project` or `global`. A set operation writes to that current effective
scope and verifies the value after writing.

## Agent definitions are not extension settings

Do not put per-agent model, thinking, tool, skill, extension, body, or
delegation policy in `piHerd`.

Those belong in Markdown agent definitions.

See:

- [Agent definitions](../guides/agent-definitions.md)
- [Agent-definition schema](agent-definition-schema.md)

## Herdr integration

The required Pi integration is installed separately:

```sh
herdr integration install pi
herdr integration status
```

Pi Herd requires integration version `2` or newer for supported native session
identity/restore behavior.

## See also

- [`/subagents` commands](commands.md)
- [Getting started](../getting-started.md)