> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# gandalf.toml team manifest reference

> Full reference for the gandalf.toml manifest, including MCP servers, skills, hooks, and env templates, with annotated examples and drift checks.

gandalf.toml is the team manifest that Gandalf reads when you run `gandalf init`, `gandalf check`, and `gandalf apply`. It declares the MCP servers, skills, hooks, and environment templates your team wants present in local agent setups. This page describes every supported field and shows a complete annotated example.

## File structure overview

A manifest is a TOML file with a top-level metadata section, plus optional sections for MCP servers, skills, hooks, and environment templates. Not all sections are required: include only the ones your team manages centrally.

## Top-level fields

```toml theme={null}
# Required: manifest schema version
version = "1.0"

# Required: project or team name
name = "my-team"

# Optional: short description of this manifest
description = "Shared setup for backend squad"

# Required: list of agents this manifest targets
agents = ["claude-code", "codex"]
```

| Field         | Type             | Required | Description                                                     |
| ------------- | ---------------- | -------- | --------------------------------------------------------------- |
| `version`     | string           | Yes      | Manifest schema version. Must be `"1.0"`.                       |
| `name`        | string           | Yes      | Name of the team or project. Used in snapshot and report names. |
| `description` | string           | No       | Human-readable summary of the manifest purpose.                 |
| `agents`      | array of strings | Yes      | Agent IDs to target. Valid values: `codex`, `claude-code`.      |

## MCP servers

Declare MCP (Model Context Protocol) servers under `[mcp_servers.<name>]`. Each server must define either a `command` with optional `args`, or a `url` for HTTP-based servers.

```toml theme={null}
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Filesystem access for project context"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Stripe customer data"
```

| Field          | Type             | Required               | Description                                                                   |
| -------------- | ---------------- | ---------------------- | ----------------------------------------------------------------------------- |
| `command`      | string           | Yes (unless `url`)     | Executable to run the MCP server.                                             |
| `args`         | array of strings | No                     | Arguments passed to `command`. Supports `${ENV_VAR}` templates.               |
| `url`          | string           | Yes (unless `command`) | HTTP endpoint for the MCP server. If set, do not include `command` or `args`. |
| `headers`      | table of strings | No                     | Headers sent with each request. Supports `${ENV_VAR}` templates.              |
| `required_env` | array of strings | No                     | Environment variables Gandalf checks before applying the server.              |
| `description`  | string           | No                     | Human-readable summary of what the server provides.                           |

<Tip>
  Any field that accepts `${ENV_VAR}` will be expanded at apply time, not when the manifest is parsed. This lets you commit shared manifests without embedding secrets.
</Tip>

## Skills

Declare skills in a `[[skills]]` array-of-tables. Each entry names a skill and its source.

```toml theme={null}
[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "SQL skill for PostgreSQL introspection"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment helper"
```

| Field         | Type   | Required | Description                                                                       |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `name`        | string | Yes      | Skill identifier. Must match the name the agent expects.                          |
| `source`      | string | Yes      | Where the skill comes from. Can be a marketplace URI, a Git URL, or a local path. |
| `description` | string | No       | Human-readable summary of the skill.                                              |

## Hooks

Declare agent hooks under `[hooks.<name>]`. Each hook binds an event to a command.

```toml theme={null}
[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"
```

| Field     | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `event`   | string | Yes      | Event name that triggers the hook.  |
| `command` | string | Yes      | Command to run when the hook fires. |

## Environment templates

Use `[env_template]` to document expected environment variables. Gandalf does not write these into shell profiles; it uses them for drift checks and reports.

```toml theme={null}
[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
```

Each key is the environment variable name, and each value is an example default. Gandalf compares these against the current environment during `check` and highlights missing variables.

## Full annotated example

```toml theme={null}
# gandalf.toml
# Full team manifest for backend squad

version = "1.0"
name = "backend-squad"
description = "Shared Codex and Claude Code setup for backend engineers"
agents = ["claude-code", "codex"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Read project files via MCP"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Live Stripe customer lookup"

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "PostgreSQL introspection helper"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment scripts"

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
STRIPE_API_KEY = "sk_test_..."
```

## Check and apply behavior

`gandalf check` compares your manifest against the current local agent setup and reports drift. When run with `--ci`, it exits with code 1 if any drift is found. This makes it suitable for CI pipelines that enforce team standards.

<Note>
  `gandalf apply` runs Smart Merge (non-destructive) and creates a pre-apply safety snapshot before changing anything. If the manifest targets an unsupported agent directory, apply skips that agent and logs a warning.
</Note>

For command-line flags and workflow details, see [/cli/init](/cli/init), [/cli/check](/cli/check), and [/cli/apply](/cli/apply).

gandalf.toml is the team manifest that Gandalf reads when you run `gandalf init`, `gandalf check`, and `gandalf apply`. It declares the MCP servers, skills, hooks, and environment templates your team wants present in local agent setups. This page describes every supported field and shows a complete annotated example.

## File structure overview

A manifest is a TOML file with a top-level metadata section, plus optional sections for MCP servers, skills, hooks, and environment templates. Not all sections are required: include only the ones your team manages centrally.

## Top-level fields

```toml theme={null}
# Required: manifest schema version
version = "1.0"

# Required: project or team name
name = "my-team"

# Optional: short description of this manifest
description = "Shared setup for backend squad"

# Required: list of agents this manifest targets
agents = ["claude-code", "codex"]
```

| Field         | Type             | Required | Description                                                     |
| ------------- | ---------------- | -------- | --------------------------------------------------------------- |
| `version`     | string           | Yes      | Manifest schema version. Must be `"1.0"`.                       |
| `name`        | string           | Yes      | Name of the team or project. Used in snapshot and report names. |
| `description` | string           | No       | Human-readable summary of the manifest purpose.                 |
| `agents`      | array of strings | Yes      | Agent IDs to target. Valid values: `codex`, `claude-code`.      |

## MCP servers

Declare MCP (Model Context Protocol) servers under `[mcp_servers.<name>]`. Each server must define either a `command` with optional `args`, or a `url` for HTTP-based servers.

```toml theme={null}
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Filesystem access for project context"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Stripe customer data"
```

| Field          | Type             | Required               | Description                                                                   |
| -------------- | ---------------- | ---------------------- | ----------------------------------------------------------------------------- |
| `command`      | string           | Yes (unless `url`)     | Executable to run the MCP server.                                             |
| `args`         | array of strings | No                     | Arguments passed to `command`. Supports `${ENV_VAR}` templates.               |
| `url`          | string           | Yes (unless `command`) | HTTP endpoint for the MCP server. If set, do not include `command` or `args`. |
| `headers`      | table of strings | No                     | Headers sent with each request. Supports `${ENV_VAR}` templates.              |
| `required_env` | array of strings | No                     | Environment variables Gandalf checks before applying the server.              |
| `description`  | string           | No                     | Human-readable summary of what the server provides.                           |

<Tip>
  Any field that accepts `${ENV_VAR}` will be expanded at apply time, not when the manifest is parsed. This lets you commit shared manifests without embedding secrets.
</Tip>

## Skills

Declare skills in a `[[skills]]` array-of-tables. Each entry names a skill and its source.

```toml theme={null}
[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "SQL skill for PostgreSQL introspection"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment helper"
```

| Field         | Type   | Required | Description                                                                       |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `name`        | string | Yes      | Skill identifier. Must match the name the agent expects.                          |
| `source`      | string | Yes      | Where the skill comes from. Can be a marketplace URI, a Git URL, or a local path. |
| `description` | string | No       | Human-readable summary of the skill.                                              |

## Hooks

Declare agent hooks under `[hooks.<name>]`. Each hook binds an event to a command.

```toml theme={null}
[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"
```

| Field     | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `event`   | string | Yes      | Event name that triggers the hook.  |
| `command` | string | Yes      | Command to run when the hook fires. |

## Environment templates

Use `[env_template]` to document expected environment variables. Gandalf does not write these into shell profiles; it uses them for drift checks and reports.

```toml theme={null}
[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
```

Each key is the environment variable name, and each value is an example default. Gandalf compares these against the current environment during `check` and highlights missing variables.

## Full annotated example

```toml theme={null}
# gandalf.toml
# Full team manifest for backend squad

version = "1.0"
name = "backend-squad"
description = "Shared Codex and Claude Code setup for backend engineers"
agents = ["claude-code", "codex"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Read project files via MCP"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Live Stripe customer lookup"

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "PostgreSQL introspection helper"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment scripts"

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
STRIPE_API_KEY = "sk_test_..."
```

## Check and apply behavior

`gandalf check` compares your manifest against the current local agent setup and reports drift. When run with `--ci`, it exits with code 1 if any drift is found. This makes it suitable for CI pipelines that enforce team standards.

<Note>
  `gandalf apply` runs Smart Merge (non-destructive) and creates a pre-apply safety snapshot before changing anything. If the manifest targets an unsupported agent directory, apply skips that agent and logs a warning.
</Note>

For command-line flags and workflow details, see [/cli/init](/cli/init), [/cli/check](/cli/check), and [/cli/apply](/cli/apply).